Merge pull request #19 from kousuke-nakano/update.turboworkflows

add description to turboworkflows class references

Author: kousuke-nakano

source/_sources/03turboworkflows_manual/reference/workflow_convertfort10.rst

@@ -36,3 +36,31 @@ convertfort10 parameters
    "in_fort10", "str", "fort.10_in", "input wavefunction file"
    "out_fort10", "str", "fort.10_out", "template wavefunction file"
    "grid_size", "float", "0.10", "grid size for xyz (bohr)"
+
+
+Description
+--------------------------------
+
+In the :class:`Convertfort10_workflow` class, the convertfort10 workflow is
+executed asynchronously (via :meth:`async_launch`). The workflow runs a single
+conversion of a fort.10 file using grid-based interpolation with the
+convertfort10.x (or convertfort10-mpi.x) binary from TurboRVB.
+
+If the pkl file already exists and :attr:`convertfort10_rerun` is
+:const:`False`, the calculation is skipped. Otherwise, the workflow:
+
+- Builds a :class:`Convertfort10_genius` instance with :attr:`in_fort10`,
+  :attr:`out_fort10`, and :attr:`grid_size`, and generates ``convertfort10.input``.
+- Submits the job, waits for submission and completion using
+  :func:`asyncio.sleep`, then fetches output files (e.g. ``out_mol``,
+  ``fort.10_new``).
+- Persists state in a pkl file under the ``pkl`` directory.
+
+On success, the method returns (status, list of output file paths under the
+root directory, and an empty output-values dict).
+
+See also
+--------------------------------
+
+- :class:`turbogenius.convertfort10_genius.Convertfort10_genius` — convertfort10
+  driver used for input generation.

source/_sources/03turboworkflows_manual/reference/workflow_convertfort10mol.rst

@@ -36,3 +36,33 @@ convertfort10mol parameters
    "add_random_mo", "bool", "True", "flag to add random molecular orbitals."
    "grid_size", "float", "0.10", "grid size for x,y,z (Bohr)."
    "additional_mo", "int", "0", "number of additional molecular orbitals to add."
+
+
+Description
+--------------------------------
+
+In the :class:`Convertfort10mol_workflow` class, the convertfort10mol workflow is executed
+asynchronously (via :meth:`async_launch`). The workflow runs a single
+conversion of a fort.10 file to molecular format using the convertfort10mol.x
+binary, with optional random molecular orbital addition.
+
+If the pkl file already exists and :attr:`convertfort10mol_rerun` is
+:const:`False`, the calculation is skipped. Otherwise, the workflow:
+
+- Builds a :class:`Convertfort10mol_genius` instance with
+  :attr:`add_random_mo`, :attr:`grid_size`, and :attr:`additional_mo`, and
+  generates ``convertfort10mol.input``.
+- Submits the job (convertfort10mol.x or convertfort10mol-mpi.x), waits for
+  submission and completion using :func:`asyncio.sleep`, then fetches output
+  files (e.g. ``out_mol``, ``fort.10_new``).
+- Persists state in a pkl file under the ``pkl`` directory.
+
+On success, the method returns (status, list of output file paths under the
+root directory, and an empty output-values dict).
+
+
+See also
+--------------------------------
+
+- :class:`turbogenius.convertfort10mol_genius.Convertfort10mol_genius` —
+  convertfort10mol driver used for input generation.

source/_sources/03turboworkflows_manual/reference/workflow_convertwf.rst

@@ -29,3 +29,33 @@ conversion parameters
    "clean_flag", "bool ", "True", "clean temporary files."
    "only_generate_template", "bool ", "False", "only generate template without full conversion."
    "change_contr", "bool ", "True", "enable to change contraction coefficients."
+
+
+Description
+--------------------------------
+
+In the :class:`Conversion_wf_workflow` class,
+the wavefunction conversion workflow is executed asynchronously (via
+:meth:`async_launch`). The workflow converts wavefunctions between formats
+(sd, agps, agpu, pf) using :meth:`Wavefunction.to_agp` for AGP singlet/triplet
+(no job submission; runs locally).
+
+If the pkl file already exists and :attr:`conversion_wf_rerun` is
+:const:`False`, the conversion is skipped. Otherwise, the workflow:
+
+- Reads ``fort.10`` with :class:`Wavefunction`. Depending on :attr:`to_wf`:
+  conversion to ``sd`` or ``pf`` raises :exc:`NotImplementedError`; for
+  ``agps`` or ``agpu``, calls :meth:`to_agp` with :attr:`grid_size`,
+  :attr:`additional_hyb`, :attr:`nosym`, :attr:`clean_flag`,
+  :attr:`only_generate_template`, and :attr:`change_contr`.
+- Persists state in a pkl file under the ``pkl`` directory.
+
+On success, the method returns (status, list of output file paths under the
+root directory, and an empty output-values dict).
+
+
+See also
+--------------------------------
+
+- :class:`turbogenius.wavefunction.Wavefunction` — wavefunction I/O and
+  conversion (e.g. :meth:`to_agp`).

source/_sources/03turboworkflows_manual/reference/workflow_init_occ.rst

@@ -29,3 +29,33 @@ initialization parameters
    "mo_num_conv", "int ", "-1", "number of molecular orbitals to use for convergence. default is -1 (use all)."
    "mo_occ", "list ", "[]", "list of molecular orbital occupation eigenvalues."
    "mo_occ_delta", "float ", "0.05", "delta value for initializing occupation numbers."
+
+
+Description
+--------------------------------
+
+In the :class:`Init_occ_workflow` class,
+the initial occupation workflow is executed asynchronously (via :meth:`async_launch`).
+The workflow initializes molecular orbital occupations in ``fort.10`` for
+LRDMC optimization by setting occupation numbers and constraint flags (no job
+submission; runs locally).
+
+If the pkl file already exists and :attr:`init_occ_rerun` is :const:`False`,
+the operation is skipped. Otherwise, the workflow:
+
+- Reads ``fort.10`` with :class:`turbogenius.pyturbo.io_fort10.IO_fort10`,
+  selects MO indices from :attr:`mo_occ_thr` or :attr:`mo_num_conv`, and
+  optionally fixes occupied orbitals via :attr:`mo_occ_fixed_list` and
+  :attr:`mo_occ_fixed_occupied`.
+- Updates constraint and coefficient data (with :attr:`mo_occ_delta` for
+  non-fixed orbitals) and writes the modified fort.10 in place.
+- Persists state in a pkl file under the ``pkl`` directory.
+
+On success, the method returns (status, list of output file paths under the
+root directory, and an empty output-values dict).
+
+See also
+--------------------------------
+
+- :class:`turbogenius.pyturbo.io_fort10.IO_fort10` — fort.10 I/O used for
+  occupation and constraint updates.

source/_sources/03turboworkflows_manual/reference/workflow_jastrowcopy.rst

@@ -26,3 +26,28 @@ jastrowcopy parameters
    "jastrowcopy_fort10_to", "str ", "fort.10", "target fort.10 file to copy Jastrow factors to."
    "jastrowcopy_fort10_from", "str ", "fort.10_new", "source fort.10 file to copy Jastrow factors from."
    "jastrowcopy_twist_average", "bool ", "False", "if True, perform twist-averaged Jastrow copying."
+
+
+Description
+--------------------------------
+
+In the :class:`Jastrowcopy_workflow` class,
+the Jastrow copy workflow is executed asynchronously (via :meth:`async_launch`).
+The workflow copies Jastrow factors from one fort.10 file to another (no job
+submission; runs locally).
+
+If the pkl file already exists and :attr:`jastrowcopy_rerun` is
+:const:`False`, the operation is skipped. Otherwise, the workflow:
+
+- Calls :func:`turbogenius.tools_genius.copy_jastrow` with
+  :attr:`jastrowcopy_fort10_to`, :attr:`jastrowcopy_fort10_from`, and
+  :attr:`jastrowcopy_twist_average` to copy Jastrow factors in place.
+- Persists state in a pkl file under the ``pkl`` directory.
+
+On success, the method returns (status, list of output file paths under the
+root directory, and an empty output-values dict).
+
+See also
+--------------------------------
+
+- :func:`turbogenius.tools_genius.copy_jastrow` — Jastrow copy routine.

source/_sources/03turboworkflows_manual/reference/workflow_lrdmc.rst

@@ -50,3 +50,54 @@ lrdmc parameters
    "lrdmc_force_calc_flag", "bool", "False", "if True, compute energy and force, if False, compute only energy"
    "lrdmc_pw_regularization", "float", "0.0", "if it is > 0.0, the Pathak-Wager regularization is turned on."
    "lrdmc_maxtime", "int", "172000", "maximum time (sec.)"
+
+
+Description
+--------------------------------
+
+In the :class:`LRDMC_workflow` class, the LRDMC (Lattice Regularized
+Diffusion Monte Carlo) workflow is executed asynchronously (via
+:meth:`async_launch`). The workflow runs LRDMC in a continuation loop (up to
+:attr:`lrdmc_max_continuation` runs). For each continuation index
+:math:`i_{\mathrm{cont}}`:
+
+**test run (icont = 0)**
+
+- Uses fixed trial steps (:attr:`lrdmc_trial_steps`) to produce energy and
+  error-bar data. Optionally enforces a minimum trial length when
+  :attr:`lrdmc_safe_trial_steps` is :const:`True` (40 blocks plus warmup).
+- No step estimation is performed.
+- Results are used by the next run to estimate required LRDMC steps.
+
+**production run (icont ≥ 1)**
+
+- Loads the previous run's results from the corresponding pkl file and reads
+  the number of MCMC steps from ``fort.12`` (with twist-averaging adjustment
+  when :attr:`lrdmc_twist_average` is enabled).
+- If the current error bar is below 1.1 × :attr:`lrdmc_target_error_bar`, the
+  workflow exits early and returns the current energy and error (target
+  achieved).
+- Otherwise, estimates the total steps required to reach
+  :attr:`lrdmc_target_error_bar` via
+  :math:`N_{\mathrm{total}} \propto (\sigma / E_{\mathrm{target}})^2`, then
+  sets the *additional* steps for this run to
+  :math:`\max(N_{\mathrm{total}} - N_{\mathrm{done}}, 1)`.
+- Estimates runtime and builds a :class:`LRDMC_genius` instance with the
+  (additional) ``lrdmcsteps``, generates input, and submits the job.
+
+For each run, the workflow waits for job submission and completion (using
+:func:`asyncio.sleep`), fetches output files (e.g. ``fort.11``, ``fort.12``,
+``out_fn_*``, ``parminimized.d``), computes energy and forces with the
+configured bin block and warmup blocks, stores results, and persists state
+in pkl files under the ``pkl`` directory.
+
+If all continuation pkl files already exist and :attr:`lrdmc_rerun` is
+:const:`False`, the calculation is skipped. On success, the method returns
+(status, list of output file paths, and an output-values dict containing
+``"energy"`` and ``"error"``).
+
+See also
+--------------------------------
+
+- :class:`turbogenius.lrdmc_genius.LRDMC_genius` — LRDMC driver used for
+  input generation and result handling.

source/_sources/03turboworkflows_manual/reference/workflow_lrdmc_ext.rst

@@ -51,3 +51,37 @@ LRDMC extrapolation parameters
    "lrdmc_pw_regularization", "float ", "0.0", "if it is > 0.0, the Pathak-Wager regularization is turned on."
    "lrdmc_maxtime", "int ", "172000", "maximum time (sec.)"
    "degree_poly", "int ", "2", "degree of polynomial for extrapolation."
+
+
+Description
+--------------------------------
+
+In the :class:`LRDMC_ext_workflow` class, the LRDMC extrapolation workflow
+is executed asynchronously (via :meth:`async_launch`). The workflow runs LRDMC
+at multiple time step (alat) values and extrapolates the energy to the
+:math:`a \to 0` limit using polynomial fitting.
+
+The workflow:
+
+- For each value in :attr:`lrdmc_alat_list`, creates a subdirectory
+  ``alat_{value}``, copies :attr:`lrdmc_input_files` (e.g. ``fort.10``,
+  ``pseudo.dat``) into it, and launches an :class:`LRDMC_workflow` instance
+  with that alat. All alat runs are launched concurrently with
+  :func:`asyncio.gather`.
+- After all runs complete, collects energies and errors from each alat
+  directory, writes ``evsa.in`` and ``evsa.gnu``, and runs ``funvsa.x`` to
+  fit energy vs. :math:`a^2` with a polynomial of degree :attr:`degree_poly`.
+- Reads the extrapolated energy and error (constant term) from ``evsa.out``,
+  stores them in ``output_values["energy"]`` and ``output_values["error"]``,
+  and generates a plot ``Energy_vs_alat.png``.
+
+No pkl-based skip logic is applied at the top level; each inner
+:class:`LRDMC_workflow` uses its own continuation and pkl state. On success,
+the method returns (status, list of output file paths under the root
+directory, and an output-values dict containing the extrapolated
+``"energy"`` and ``"error"``).
+
+See also
+--------------------------------
+
+- :class:`LRDMC_workflow` — inner workflow used for each alat value.

source/_sources/03turboworkflows_manual/reference/workflow_lrdmcopt.rst

@@ -61,3 +61,49 @@ LRDMCopt parameters
    "lrdmcopt_twist_average", "bool ", "False", "flag for twist average"
    "lrdmcopt_kpoints", "list ", "[]", "Monkhorst-Pack k-grids, [kx,ky,kz,nx,ny,nz], kx,ky,kz for grids, nx,ny,nz for shift=0, noshift=1."
    "lrdmcopt_maxtime", "int ", "172000", "maximum time (sec.)"
+
+
+Description
+--------------------------------
+
+In the :class:`LRDMCopt_workflow` class, the LRDMC optimization workflow is
+executed asynchronously (via :meth:`async_launch`). The workflow runs LRDMC
+optimization in a continuation loop (up to
+:attr:`lrdmcopt_max_continuation` runs). For each continuation index
+:math:`i_{\mathrm{cont}}`:
+
+**test run (icont = 0)**
+
+- Uses fixed trial parameters (:attr:`lrdmcopt_trial_optsteps`,
+  :attr:`lrdmcopt_trial_steps`) to produce energy and error-bar data.
+- No step estimation is performed.
+- Results are used by the next run to estimate required LRDMC steps.
+
+**production run (icont ≥ 1)**
+
+- Loads the previous run's results from the corresponding pkl file.
+- Estimates the LRDMC steps required to reach
+  :attr:`lrdmcopt_target_error_bar` via
+  :math:`N_{\mathrm{steps}} \propto (\sigma / E_{\mathrm{target}})^2`.
+- Applies a minimum-step floor using :attr:`lrdmcopt_minimum_blocks` and
+  :attr:`lrdmcopt_warmupblocks`.
+- Estimates total runtime and builds a :class:`LRDMCopt_genius` instance with
+  the estimated ``steps`` and fixed :attr:`lrdmcopt_production_optsteps`,
+  then generates input and submits the job.
+
+For each run, the workflow waits for job submission and completion (using
+:func:`asyncio.sleep`), fetches output files (e.g. ``fort.10``, ``fort.11``,
+``fort.12``, ``out_fn_opt_*``, ``parminimized.d``), stores and plots results,
+and for :math:`i_{\mathrm{cont}} > 0` computes parameter averages discarding
+an initial fraction (:attr:`lrdmcopt_optwarmupsteps_ratio`). State is
+persisted in pkl files under the ``pkl`` directory.
+
+If all continuation pkl files already exist and :attr:`lrdmcopt_rerun` is
+:const:`False`, the calculation is skipped. On success, the method returns
+(status, list of output file paths, and an empty output-values dict).
+
+See also
+--------------------------------
+
+- :class:`turbogenius.lrdmc_opt_genius.LRDMCopt_genius` — LRDMC optimization
+  driver used for input generation and result handling.

source/_sources/03turboworkflows_manual/reference/workflow_makefort10.rst

@@ -42,3 +42,30 @@ makefort10 parameters
    "same_phase_up_dn", "bool ", "False", "forced phase_up == phase_dn. valid only for gamma point. it is automatically detected for other points."
    "neldiff", "int ", "0", "difference in number of up and down electrons."
    "symmetry", "bool ", "True", "if false, nosym=.true., meaning that no symmetry is used."
+
+
+Description
+--------------------------------
+
+In the :class:`Makefort10_workflow` class,
+the makefort10 workflow is executed asynchronously (via :meth:`async_launch`).
+The workflow generates a fort.10 wavefunction file from a structure file
+using the makefort10.x binary with specified basis sets and Jastrow factors
+(no job submission; runs locally via :meth:`Makefort10_genius.run_all`).
+
+If the pkl file already exists and :attr:`makefort10_rerun` is :const:`False`,
+the calculation is skipped. Otherwise, the workflow:
+
+- Builds a :class:`Makefort10_genius` instance from the constructor parameters
+  (structure file, supercell, basis sets, Jastrow type, phase, etc.) and calls
+  :meth:`run_all` to generate fort.10 and related files.
+- Persists state in a pkl file under the ``pkl`` directory.
+
+On success, the method returns (status, list of output file paths under the
+root directory, and an empty output-values dict).
+
+See also
+--------------------------------
+
+- :class:`turbogenius.makefort10_genius.Makefort10_genius` — makefort10
+  driver used for generation.

source/_sources/03turboworkflows_manual/reference/workflow_prep.rst

@@ -47,3 +47,33 @@ DFT parameters
    "dft_independent_kpoints", "bool ", "False", "flag for independent k-point calculation"
    "dft_thr_lindep", "float ", "1.0e-13", "inverse of the condition number of basis sets. prep cuts the redundancy."
    "dft_kpoints", "list ", "[1, 1, 1, 0, 0, 0]", "Monkhorst-Pack k-grids, [kx,ky,kz,nx,ny,nz], kx,ky,kz for grids, nx,ny,nz for shift=0, noshift=1."
+
+
+Description
+--------------------------------
+
+In the :class:`DFT_workflow` class, the DFT (prep) workflow is executed
+asynchronously (via :meth:`async_launch`). The workflow runs a single DFT
+calculation using the prep.x binary from TurboRVB, with support for
+twist-averaged boundary conditions and k-point sampling.
+
+If the pkl file already exists and :attr:`dft_rerun` is :const:`False`, the
+calculation is skipped. Otherwise, the workflow:
+
+- Builds a :class:`DFT_genius` instance from the constructor parameters (grid
+  size, box, smearing, XC, twist averaging, etc.) and generates ``prep.input``.
+- Submits the job (prep-mpi.x or prep-serial.x), waits for submission and
+  completion using :func:`asyncio.sleep`, then fetches output files (e.g.
+  ``out_prep``, ``occupationlevels.dat``, ``EDFT_vsk.dat``, and optionally
+  ``fort.10_new`` or twist-averaging scratch files).
+- Persists state in a pkl file under the ``pkl`` directory.
+
+On success, the method returns (status, list of output file paths under the
+root directory, and an output-values dict with ``"energy"`` and ``"error"``
+set to :const:`None`).
+
+See also
+--------------------------------
+
+- :class:`turbogenius.prep_genius.DFT_genius` — DFT/prep driver used for
+  input generation.