Skip to content

Commit d34c92f

Browse files
kousuke-nakanokousuke-nakano
authored
Merge pull request #16 from kousuke-nakano/update.turbogenius
Update TurboGenius manual
2 parents 13d564c + 2085406 commit d34c92f

29 files changed

Lines changed: 2202 additions & 4 deletions

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,3 +136,6 @@ tar_all_tutorials.sh
136136
*.pptx
137137
file/
138138
99archived/
139+
140+
# editor backup files
141+
*~

‎source/_sources/02turbogenius_manual/00index.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. G-Turbo manual documentation master file, created by
2+
sphinx-quickstart on Thu Jan 24 00:11:17 2019.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
TurboGenius manual
7+
===========================================
8+
9+
.. figure:: /_static/07logo/logo2.png
10+
:width: 600px
11+
12+
TurboGenius is a Python package designed to fully control *ab initio* quantum Monte Carlo (QMC) calculations using a Python script, which allows one to perform high-throughput calculations combined with TurboRVB.
13+
14+
.. toctree::
15+
:maxdepth: 1
16+
17+
./getting_started/00index.rst
18+
../02turbogenius_tutorial/00index.rst
19+
./reference/00index.rst
20+
./appendix/00index.rst
21+

‎source/_sources/02turbogenius_manual/appendix/00index.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Appendix
2+
======================================================
3+
4+
.. figure:: /_static/07logo/logo2.png
5+
:width: 600px
6+
7+
Here are examples of various calculations with TurboRVB.
8+
9+
.. toctree::
10+
:maxdepth: 3
11+
12+
./trouble_shooting/tutorial.rst
13+

‎source/_sources/02turbogenius_manual/appendix/trouble_shooting/tutorial.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. _turbogeniustutorial_trouble_shooting:
2+
3+
Trouble shooting
4+
======================================================
5+
6+
TBD

‎source/_sources/02turbogenius_manual/getting_started/00index.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Getting started
2+
===========================================
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
./02installation.rst
8+
./03basic_workflow.rst

‎source/_sources/02turbogenius_manual/getting_started/02installation.rst‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
.. TurboRVB_manual documentation master file, created by
2+
sphinx-quickstart on Thu Jan 24 00:11:17 2019.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
.. _turbogenius_installation:
7+
8+
Installation of TurboGenius
9+
======================================================
10+
11+
The following is an instruction to install TurboGenius.
12+
If you have any problem on the installation, please visit `TurboGenius Discussions <https://github.com/kousuke-nakano/turbogenius/discussions>`__ and please post your problem.
13+
14+
Prerequisites
15+
--------------------------------------------
16+
17+
Before installing the packages, ensure you have the following prerequisites:
18+
19+
* TurboRVB
20+
* Python 3.8 or later
21+
* Conda (optional, recommended for Python environment management)
22+
23+
TurboGenius also depends on the following Python packages, which will be automatically installed during the installation process:
24+
25+
* numpy (version 1.x)
26+
* pandas
27+
* matplotlib
28+
* trexio
29+
* trexio-tools
30+
* basis-set-exchange
31+
* ase
32+
* pymatgen
33+
* click
34+
* tqdm
35+
* psutil
36+
* pytest (for developers)
37+
* setuptools_scm (for developers)
38+
39+
To run the tutorials, the users also need to install the following software:
40+
41+
* PySCF
42+
43+
44+
TurboRVB installation
45+
--------------------------------------------
46+
47+
See our documents for installation of TurboRVB :ref:`turborvb_installation`.
48+
49+
50+
51+
TurboGenius installation
52+
--------------------------------------------
53+
54+
Let's make a conda environment to install turbogenius (if you prefer)
55+
56+
.. code-block:: bash
57+
58+
% conda create -n turborvb python=3.8
59+
% conda activate turborvb
60+
61+
Please download the source codes from the GitHub repository.
62+
63+
.. code-block:: bash
64+
65+
% cd ~/applications
66+
% git clone https://github.com/kousuke-nakano/turbogenius.git
67+
68+
Let's install turbogenius via pip
69+
70+
.. code-block:: bash
71+
72+
% cd turbogenius
73+
% pip install -e . # Install in development mode
74+
75+
Test if it works.
76+
77+
.. code-block:: bash
78+
79+
% turbogenius --help
80+
81+
If you see the help output, TurboGenius has been successfully installed!
82+
83+
84+
Troubleshooting
85+
--------------------------------------------
86+
87+
Common issues and solutions:
88+
89+
1. If the help output is not shown, and the following error messages are produced instead:
90+
91+
.. code-block:: plain
92+
93+
$ turbogenius --help
94+
Traceback (most recent call last):
95+
File "/envs/turborvb/lib/python3.11/site-packages/turbogenius/pyturbo/utils/env.py", line 46, in <module>
96+
os.path.dirname(subprocess.check_output(cmd, shell=True, env=sys_env))
97+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98+
File "/envs/turborvb/lib/python3.11/subprocess.py", line 466, in check_output
99+
return run(*popenargs, stdout=PIPE, timeout=timeout, check=True,
100+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
101+
File "/envs/turborvb/lib/python3.11/subprocess.py", line 571, in run
102+
raise CalledProcessError(retcode, process.args,
103+
subprocess.CalledProcessError: Command 'which readalles.x' returned non-zero exit status 1.
104+
105+
During handling of the above exception, another exception occurred:
106+
107+
Traceback (most recent call last):
108+
File "/envs/turborvb/bin/turbogenius", line 3, in <module>
109+
from turbogenius.turbo_genius_cli import cli
110+
File "/envs/turborvb/lib/python3.11/site-packages/turbogenius/__init__.py", line 11, in <module>
111+
from . import *
112+
File "/envs/turborvb/lib/python3.11/site-packages/turbogenius/correlated_sampling_genius.py", line 21, in <module>
113+
from turbogenius.pyturbo.vmc import VMC
114+
File "/envs/turborvb/lib/python3.11/site-packages/turbogenius/pyturbo/__init__.py", line 10, in <module>
115+
from . import *
116+
File "/envs/turborvb/lib/python3.11/site-packages/turbogenius/pyturbo/lrdmc.py", line 20, in <module>
117+
from turbogenius.pyturbo.namelist import Namelist
118+
File "/envs/turborvb/lib/python3.11/site-packages/turbogenius/pyturbo/namelist.py", line 23, in <module>
119+
from turbogenius.pyturbo.utils.utility import get_str_variable_type_auto
120+
File "/envs/turborvb/lib/python3.11/site-packages/turbogenius/pyturbo/utils/utility.py", line 29, in <module>
121+
from .env import pyturbo_root
122+
File "/envs/turborvb/lib/python3.11/site-packages/turbogenius/pyturbo/utils/env.py", line 50, in <module>
123+
raise ValueError(
124+
ValueError: Set TURBORVB_ROOT (e.g., export TURBORVB_ROOT=XXX in ~.bashrc)
125+
126+
it occurs when TurboRVB is not installed or the executables of TurboRVB are not included in the command search paths. Please make sure that you have installed TurboRVB following the inststruction :ref:`turborvb_installation`. Then, add the directory to the ``PATH`` environment variable where the TurboRVB executables are installed, or set it to ``TURBORVB_ROOT`` as shown in the error message.
127+
128+
2. **Python environment issues**
129+
130+
If you have problems with the Python environment:
131+
132+
* Ensure you're using the correct Python version
133+
* Try creating a fresh conda environment
134+
* Check that pip is up to date: ``pip install --upgrade pip``
135+
136+
For additional help, please visit the discussion forums linked above or open an issue on the respective GitHub repositories.

‎source/_sources/02turbogenius_manual/getting_started/03basic_workflow.rst‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
Basic workflow
2+
======================================================
3+
4+
.. figure:: /_static/02basic_workflow/workflow_detailed.jpeg
5+
:scale: 70%
6+
7+
------------------------------
8+
Reference link
9+
------------------------------
10+
1. Preparation
11+
12+
- :ref:`turbogeniustutorial_subcommand_makefort10`
13+
14+
2. Conversion
15+
16+
- :ref:`turbogeniustutorial_subcommand_convertfort10mol`
17+
18+
3. DFT
19+
20+
- :ref:`turbogeniustutorial_subcommand_prep`
21+
22+
4. VMC optimization
23+
24+
- :ref:`turbogeniustutorial_subcommand_vmcopt`
25+
26+
5. VMC calculation
27+
28+
- :ref:`turbogeniustutorial_subcommand_vmc`
29+
30+
6. LRDMC calculation
31+
32+
- :ref:`turbogeniustutorial_subcommand_lrdmc`
33+
34+
A. convert JDFT wavefunction to JsAGPs one
35+
36+
- :ref:`turbogeniustutorial_subcommand_convertwf`
37+
38+
B. Correlated sampling
39+
40+
- :ref:`turbogeniustutorial_subcommand_correlated-sampling`

‎source/_sources/02turbogenius_manual/reference/00index.rst‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
Reference guide
2+
======================================================
3+
4+
Here are references for formats of input file, executions, and scripts with TurboRVB.
5+
6+
.. toctree::
7+
:maxdepth: 1
8+
9+
01general_description.rst
10+
subcommands/convertfort10.rst
11+
subcommands/convertfort10mol.rst
12+
subcommands/convertpfaff.rst
13+
subcommands/convertwf.rst
14+
subcommands/correlated-sampling.rst
15+
subcommands/lrdmc.rst
16+
subcommands/lrdmcopt.rst
17+
subcommands/makefort10.rst
18+
subcommands/plotorb.rst
19+
subcommands/prep.rst
20+
subcommands/readforward.rst
21+
subcommands/view.rst
22+
subcommands/vmc.rst
23+
subcommands/vmcopt.rst
24+
subcommands/writestr.rst
25+

‎source/_sources/02turbogenius_manual/reference/01general_description.rst‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
General description
2+
===========================================
3+
4+
``TurboGenius`` has a very useful command line tool that allows us
5+
to manipulate input and output files very efficiently. One of the most
6+
useful function of the command line tool is its `helper`. To see this, please
7+
try to type the following command:
8+
9+
.. code-block:: bash
10+
11+
% turbogenius --help
12+
Usage: turbogenius [OPTIONS] COMMAND [ARGS]...
13+
14+
Options:
15+
--help Show this message and exit.
16+
17+
Commands:
18+
convertfort10 convertfort10_genius
19+
convertfort10mol convertfort10mol_genius
20+
convertpfaff readforward_genius
21+
convertwf convert wavefunction
22+
correlated-sampling correlated_sampling_genius
23+
lrdmc lrdmc_genius
24+
lrdmcopt lrdmc_genius
25+
makefort10 makefort10_genius
26+
prep prep_genius
27+
vmc vmc_genius
28+
vmcopt vmcopt_genius
29+
30+
You can easily see what commands are implemented in ``TurboGenius``.
31+
Please type the following command to see what options are implemented for each command,
32+
33+
e.g., vmcopt:
34+
35+
.. code-block:: bash
36+
37+
% turbogenius vmcopt --help
38+
Usage: turbogenius vmcopt [OPTIONS]
39+
40+
Options:
41+
-post Postprocess
42+
-r Run a program
43+
-g Generate an input file
44+
-vmcoptsteps INTEGER Specify vmcoptsteps
45+
-optwarmup INTEGER Specify optwarmupsteps
46+
-steps INTEGER Specify steps per one iteration
47+
-bin INTEGER Specify bin_block
48+
-warmup INTEGER Specify warmupblocks
49+
-nw INTEGER Specify num_walkers
50+
-maxtime INTEGER Specify maxtime
51+
-optimizer TEXT Specify optimizer, sr or lr
52+
-learn FLOAT Specify learning_rate
53+
-reg FLOAT Specify regularization
54+
-opt_onebody flag for opt_onebody
55+
-opt_twobody flag for opt_twobody
56+
-opt_det_mat flag for opt_det_mat
57+
-opt_jas_mat flag for opt_jas_mat
58+
-opt_det_basis_exp flag for opt_det_basis_exp
59+
-opt_jas_basis_exp flag for opt_jas_basis_exp
60+
-opt_det_basis_coeff flag for opt_det_basis_coeff
61+
-opt_jas_basis_coeff flag for opt_jas_basis_coeff
62+
-twist flag for twist_average
63+
-kpts INTEGER... kpts, Specify Monkhorst-Pack grids and shifts,
64+
[nkx,nky,nkz,kx,ky,kz]
65+
-plot flag for plotting graph
66+
-log TEXT logger level, DEBUG, INFO, ERROR
67+
--help Show this message and exit.
68+
69+
In the following reference, we describe the usage, the commandline options, the corresponding TurboRVB commands, the input and output files, and further information of each subcommand.

‎source/_sources/02turbogenius_manual/reference/02command.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Subcommand reference
2+
===========================================
3+
4+
.. toctree::
5+
:maxdepth: 1
6+
7+
./subcommands/convertfort10.rst
8+
./subcommands/convertfort10mol.rst
9+
./subcommands/convertpfaff.rst
10+
./subcommands/convertwf.rst
11+
./subcommands/correlated-sampling.rst
12+
./subcommands/lrdmc.rst
13+
./subcommands/lrdmcopt.rst
14+
./subcommands/makefort10.rst
15+
./subcommands/plotorb.rst
16+
./subcommands/prep.rst
17+
./subcommands/readforward.rst
18+
./subcommands/view.rst
19+
./subcommands/vmc.rst
20+
./subcommands/vmcopt.rst
21+
./subcommands/writestr.rst

0 commit comments

Comments
 (0)