mirror of https://github.com/QMCPACK/qmcpack.git
348 lines
17 KiB
ReStructuredText
348 lines
17 KiB
ReStructuredText
.. _installation:
|
||
|
||
Nexus Installation
|
||
==================
|
||
|
||
Installation of Nexus can be accomplished by
|
||
setting a single environment variable, provided a
|
||
working python environment exists.
|
||
|
||
.. _ via a single download from ``qmcpack.org``
|
||
|
||
Setting environment variables
|
||
-----------------------------
|
||
|
||
To make your Python installation (must be Python 2.x as 3.x is not supported)
|
||
aware of Nexus, simply set the PYTHONPATH environment variable. For example, in bash this would look like:
|
||
|
||
.. code-block:: rest
|
||
|
||
export PYTHONPATH=/your_download_path/nexus/lib:$PYTHONPATH
|
||
|
||
Add this to, *e.g.*, your .bashrc file to make Nexus available
|
||
in future sessions.
|
||
If you want to use the command line tools, add them to your path:
|
||
|
||
.. code-block:: rest
|
||
|
||
export PATH=/your_download_path/nexus/bin:$PATH
|
||
|
||
Both of these environment variables can be set automatically by the ``install`` script packaged with Nexus. To use the installer, instead of performing the manual installation above, simply type the following at the command line:
|
||
|
||
::
|
||
|
||
/your_download_path/nexus/install
|
||
|
||
If you want the Nexus binaries to reside a location different than ``/your_download_path/nexus/bin``, simply provide this path to the installer:
|
||
|
||
::
|
||
|
||
/your_download_path/nexus/install /some/other/location
|
||
|
||
Installing Python dependencies
|
||
------------------------------
|
||
|
||
In addition to the standard Python installation, the ``numpy`` module
|
||
must be installed for Nexus to function at a basic level. To realize the
|
||
full range of functionality available, it is recommended that the
|
||
``scipy``, ``matplotlib``, ``h5py``, ``pydot``, ``spglib``, ``pycifrw``,
|
||
``cif2cell`` and ``seekpath`` modules be installed as well. Many of
|
||
these packages are already available in various supercomputing
|
||
environments.
|
||
|
||
On a Debian-based Linux system, such as Ubuntu, installation of
|
||
these python modules is easily accomplished by invoking the following at the
|
||
command line:
|
||
|
||
::
|
||
|
||
sudo apt install python3-numpy
|
||
sudo apt install python3-scipy python3-matplotlib python3-h5py
|
||
sudo apt install python3-pydot
|
||
sudo apt install python3-pip
|
||
|
||
To install the Python modules on other platforms (as well as those not
|
||
listed with ``apt`` above on Debian systems), try ‘pip3‘:
|
||
|
||
::
|
||
|
||
pip3 install --user numpy
|
||
pip3 install --user scipy
|
||
pip3 install --user matplotlib
|
||
pip3 install --user h5py
|
||
pip3 install --user pydot
|
||
pip3 install --user spglib
|
||
pip3 install --user PyCifRW
|
||
pip3 install --user cif2cell
|
||
pip3 install --user seekpath
|
||
|
||
The purpose of each library is described below:
|
||
|
||
**numpy** Needed throughout Nexus for array computation. Nexus will not
|
||
function without NumPy.
|
||
|
||
**scipy** Used by the ``qmc-fit`` executable to perform least squares
|
||
fits to QMCPACK DMC energies vs. timestep to perform extrapolation to
|
||
zero timestep.
|
||
|
||
**matplotlib** Needed to view plots of QMCPACK data generated by the
|
||
``qmca`` and ``qmc-fit`` executables.
|
||
|
||
**h5py** Needed by the ``qdens`` tool to postprocess QMCPACK densities.
|
||
|
||
**pydot** Used to plot simulation workflow diagrams.
|
||
|
||
**spglib** Used to find crystalline primitive cells and perform k-point
|
||
symmetrization.
|
||
|
||
**PyCifRW** Needed to read ``.cif`` crystal structure files.
|
||
|
||
**seekpath** Used to find high symmetry lines in reciprocal space for
|
||
excited state calculations with QMCPACK.
|
||
|
||
Of course, to run full calculations, the simulation codes and converters
|
||
involved must be installed as well. These include a modified version of
|
||
Quantum Espresso (``pw.x``, ``pw2qmcpack.x``, optionally
|
||
``pw2casino.x``), QMCPACK (``qmcpack``, ``qmcpack_complex``,
|
||
``convert4qmc``, ``wfconvert``, ``ppconvert``), SQD (``sqd``, packaged
|
||
with QMCPACK), VASP, and/or GAMESS. Complete coverage of this task is
|
||
beyond the scope of the current document, but please see :ref:`install-code`.
|
||
|
||
Testing your Nexus installation
|
||
-------------------------------
|
||
|
||
Nexus is packaged with an extensive suite of tests that can be run with
|
||
either the ``nxs-test`` executable packaged with Nexus or with
|
||
``pytest``. If you have installed Nexus, the ``nxs-test`` tool should be
|
||
in your ``PATH``. Installation is successful if all tests pass:
|
||
|
||
::
|
||
|
||
>nxs-test
|
||
|
||
1/64 versions................................ Passed 0.24 sec
|
||
2/64 required_dependencies................... Passed 0.00 sec
|
||
3/64 nexus_imports........................... Passed 0.08 sec
|
||
4/64 testing................................. Passed 0.07 sec
|
||
5/64 execute................................. Passed 0.00 sec
|
||
6/64 memory.................................. Passed 0.00 sec
|
||
7/64 plotting................................ Passed 0.00 sec
|
||
8/64 superstring............................. Passed 0.00 sec
|
||
9/64 generic................................. Passed 0.00 sec
|
||
10/64 developer............................... Passed 0.00 sec
|
||
11/64 unit_converter.......................... Passed 0.00 sec
|
||
12/64 periodic_table.......................... Passed 0.00 sec
|
||
13/64 numerics................................ Passed 0.03 sec
|
||
14/64 grid_functions.......................... Passed 2.28 sec
|
||
15/64 fileio.................................. Passed 0.01 sec
|
||
16/64 hdfreader............................... Passed 0.01 sec
|
||
17/64 xmlreader............................... Passed 0.00 sec
|
||
18/64 structure............................... Passed 1.01 sec
|
||
19/64 physical_system......................... Passed 0.04 sec
|
||
20/64 basisset................................ Passed 0.03 sec
|
||
21/64 pseudopotential......................... Passed 0.81 sec
|
||
22/64 nexus_base.............................. Passed 0.00 sec
|
||
23/64 machines................................ Passed 1.73 sec
|
||
24/64 simulation.............................. Passed 0.41 sec
|
||
25/64 bundle.................................. Passed 0.01 sec
|
||
26/64 project_manager......................... Passed 4.12 sec
|
||
27/64 settings................................ Passed 0.02 sec
|
||
28/64 vasp_input.............................. Passed 0.02 sec
|
||
29/64 pwscf_input............................. Passed 0.04 sec
|
||
30/64 pwscf_postprocessor_input............... Passed 0.00 sec
|
||
31/64 gamess_input............................ Passed 0.01 sec
|
||
32/64 pyscf_input............................. Passed 0.01 sec
|
||
33/64 quantum_package_input................... Passed 0.02 sec
|
||
34/64 qmcpack_converter_input................. Passed 0.00 sec
|
||
35/64 qmcpack_input........................... Passed 0.22 sec
|
||
36/64 vasp_analyzer........................... Passed 0.03 sec
|
||
37/64 pwscf_analyzer.......................... Passed 0.02 sec
|
||
38/64 pwscf_postprocessor_analyzers........... Passed 0.00 sec
|
||
39/64 gamess_analyzer......................... Passed 0.00 sec
|
||
40/64 pyscf_analyzer.......................... Passed 0.00 sec
|
||
41/64 quantum_package_analyzer................ Passed 0.00 sec
|
||
42/64 qmcpack_converter_analyzers............. Passed 0.00 sec
|
||
43/64 qmcpack_analyzer........................ Passed 0.58 sec
|
||
44/64 vasp_simulation......................... Passed 0.04 sec
|
||
45/64 pwscf_simulation........................ Passed 0.01 sec
|
||
46/64 gamess_simulation....................... Passed 0.01 sec
|
||
47/64 pyscf_simulation........................ Passed 0.00 sec
|
||
48/64 quantum_package_simulation.............. Passed 0.01 sec
|
||
49/64 pwscf_postprocessor_simulations......... Passed 0.01 sec
|
||
50/64 qmcpack_converter_simulations........... Passed 0.01 sec
|
||
51/64 qmcpack_simulation...................... Passed 0.39 sec
|
||
52/64 nxs_redo................................ Passed 0.07 sec
|
||
53/64 nxs_sim................................. Passed 0.86 sec
|
||
54/64 qmca.................................... Passed 3.25 sec
|
||
55/64 qmc_fit................................. Passed 0.33 sec
|
||
56/64 qdens................................... Passed 0.46 sec
|
||
57/64 example_gamess_H2O...................... Passed 1.70 sec
|
||
58/64 example_pwscf_relax_Ge_T................ Passed 0.77 sec
|
||
59/64 example_qmcpack_H2O..................... Passed 0.83 sec
|
||
60/64 example_qmcpack_LiH..................... Passed 0.89 sec
|
||
61/64 example_qmcpack_c20..................... Passed 0.82 sec
|
||
62/64 example_qmcpack_diamond................. Passed 1.35 sec
|
||
63/64 example_qmcpack_graphene................ Passed 0.94 sec
|
||
64/64 example_qmcpack_oxygen_dimer............ Passed 0.80 sec
|
||
|
||
100% tests passed, 0 tests failed out of 64
|
||
|
||
Total test time = 25.45 sec
|
||
|
||
Only portions of Nexus consistent with your Python installed Python
|
||
libraries will be tested.
|
||
|
||
To run the tests with ``pytest`` (``pip install –user pytest``), enter
|
||
the unit test directory and simply invoke the ``pytest`` command:
|
||
|
||
::
|
||
|
||
>cd nexus/tests/unit/
|
||
>pytest
|
||
=========================== test session starts ============================
|
||
platform linux2 -- Python 2.7.15+, pytest-3.3.2, py-1.5.2, pluggy-0.6.0
|
||
|
||
collected 379 items
|
||
|
||
test_basisset.py ..... [ 1%]
|
||
test_bundle.py .. [ 1%]
|
||
test_developer.py .. [ 2%]
|
||
test_execute.py .. [ 2%]
|
||
test_fileio.py ....... [ 4%]
|
||
test_gamess_analyzer.py ... [ 5%]
|
||
test_gamess_input.py ....... [ 7%]
|
||
test_gamess_simulation.py ...... [ 8%]
|
||
test_generic.py ... [ 9%]
|
||
test_grid_functions.py ...................... [ 15%]
|
||
test_hdfreader.py .. [ 16%]
|
||
test_machines.py ...................... [ 21%]
|
||
test_memory.py .... [ 22%]
|
||
test_nexus_base.py ..... [ 24%]
|
||
test_nexus_imports.py . [ 24%]
|
||
test_numerics.py ............... [ 28%]
|
||
test_nxs_redo.py . [ 28%]
|
||
test_nxs_sim.py . [ 29%]
|
||
test_optional_dependencies.py ....... [ 30%]
|
||
test_periodic_table.py ... [ 31%]
|
||
test_physical_system.py ....... [ 33%]
|
||
test_plotting.py . [ 33%]
|
||
test_project_manager.py ........... [ 36%]
|
||
test_pseudopotential.py ...... [ 38%]
|
||
test_pwscf_analyzer.py ... [ 39%]
|
||
test_pwscf_input.py ... [ 39%]
|
||
test_pwscf_postprocessor_analyzers.py ... [ 40%]
|
||
test_pwscf_postprocessor_input.py ..... [ 41%]
|
||
test_pwscf_postprocessor_simulations.py ...... [ 43%]
|
||
test_pwscf_simulation.py ...... [ 45%]
|
||
test_pyscf_analyzer.py .. [ 45%]
|
||
test_pyscf_input.py .... [ 46%]
|
||
test_pyscf_simulation.py ..... [ 48%]
|
||
test_qdens.py . [ 48%]
|
||
test_qmc_fit.py . [ 48%]
|
||
test_qmca.py ........... [ 51%]
|
||
test_qmcpack_analyzer.py ...... [ 53%]
|
||
test_qmcpack_converter_analyzers.py .... [ 54%]
|
||
test_qmcpack_converter_input.py .......... [ 56%]
|
||
test_qmcpack_converter_simulations.py .................. [ 61%]
|
||
test_qmcpack_input.py ............ [ 64%]
|
||
test_qmcpack_simulation.py ...... [ 66%]
|
||
test_quantum_package_analyzer.py .. [ 66%]
|
||
test_quantum_package_input.py .... [ 67%]
|
||
test_quantum_package_simulation.py ...... [ 69%]
|
||
test_required_dependencies.py . [ 69%]
|
||
test_settings.py .. [ 70%]
|
||
test_simulation.py ........................................ [ 80%]
|
||
test_structure.py ................................. [ 89%]
|
||
test_superstring.py ....... [ 91%]
|
||
test_testing.py .... [ 92%]
|
||
test_unit_converter.py ... [ 93%]
|
||
test_vasp_analyzer.py .... [ 94%]
|
||
test_vasp_input.py ....... [ 96%]
|
||
test_vasp_simulation.py ....... [ 97%]
|
||
test_versions.py ..... [ 99%]
|
||
test_xmlreader.py ... [100%]
|
||
|
||
======================= 379 passed in 17.18 seconds ========================
|
||
|
||
Assessing Test Coverage (Developer Topic)
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Code coverage can be assessed by using the ``coverage`` tool
|
||
(``pip install –user coverage``):
|
||
|
||
::
|
||
|
||
>cd nexus/bin/
|
||
>coverage run nxs-test
|
||
...
|
||
>coverage report | grep nexus/lib
|
||
|
||
nexus/lib/basisset.py 631 375 41%
|
||
nexus/lib/bundle.py 191 68 64%
|
||
nexus/lib/debug.py 12 6 50%
|
||
nexus/lib/developer.py 261 97 63%
|
||
nexus/lib/execute.py 13 2 85%
|
||
nexus/lib/fileio.py 957 373 61%
|
||
nexus/lib/gamess.py 102 20 80%
|
||
nexus/lib/gamess_analyzer.py 305 149 51%
|
||
nexus/lib/gamess_input.py 597 167 72%
|
||
nexus/lib/generic.py 817 173 79%
|
||
nexus/lib/grid_functions.py 1192 435 64%
|
||
nexus/lib/hdfreader.py 215 61 72%
|
||
nexus/lib/machines.py 1887 463 75%
|
||
nexus/lib/memory.py 60 7 88%
|
||
nexus/lib/nexus.py 297 140 53%
|
||
nexus/lib/nexus_base.py 74 11 85%
|
||
nexus/lib/numerics.py 756 372 51%
|
||
nexus/lib/periodic_table.py 1505 24 98%
|
||
nexus/lib/physical_system.py 427 73 83%
|
||
nexus/lib/plotting.py 22 7 68%
|
||
nexus/lib/project_manager.py 234 37 84%
|
||
nexus/lib/pseudopotential.py 1225 559 54%
|
||
nexus/lib/pwscf.py 198 73 63%
|
||
nexus/lib/pwscf_analyzer.py 634 316 50%
|
||
nexus/lib/pwscf_data_reader.py 132 120 9%
|
||
nexus/lib/pwscf_input.py 1261 563 55%
|
||
nexus/lib/pwscf_postprocessors.py 434 56 87%
|
||
nexus/lib/pyscf_analyzer.py 3 0 100%
|
||
nexus/lib/pyscf_input.py 181 26 86%
|
||
nexus/lib/pyscf_sim.py 57 8 86%
|
||
nexus/lib/qmcpack.py 344 146 58%
|
||
nexus/lib/qmcpack_analyzer.py 457 104 77%
|
||
nexus/lib/qmcpack_analyzer_base.py 327 137 58%
|
||
nexus/lib/qmcpack_converters.py 507 83 84%
|
||
nexus/lib/qmcpack_input.py 3605 1439 60%
|
||
nexus/lib/qmcpack_method_analyzers.py 198 64 68%
|
||
nexus/lib/qmcpack_property_analyzers.py 205 97 53%
|
||
nexus/lib/qmcpack_quantity_analyzers.py 2070 1789 14%
|
||
nexus/lib/qmcpack_result_analyzers.py 285 142 50%
|
||
nexus/lib/quantum_package.py 253 141 44%
|
||
nexus/lib/quantum_package_analyzer.py 3 0 100%
|
||
nexus/lib/quantum_package_input.py 338 164 51%
|
||
nexus/lib/simulation.py 1019 169 83%
|
||
nexus/lib/structure.py 3830 2055 46%
|
||
nexus/lib/superstring.py 311 199 36%
|
||
nexus/lib/testing.py 409 67 84%
|
||
nexus/lib/unit_converter.py 121 4 97%
|
||
nexus/lib/vasp.py 94 15 84%
|
||
nexus/lib/vasp_analyzer.py 548 73 87%
|
||
nexus/lib/vasp_input.py 906 412 55%
|
||
nexus/lib/versions.py 335 50 85%
|
||
nexus/lib/xmlreader.py 260 54 79%
|
||
|
||
The first column is the total number of statements, the second is the
|
||
number not yet covered by the tests and the third is the percent
|
||
covered. By translating the first and second columns into totals reveals
|
||
that overall coverage is currently about 61%.
|
||
|
||
To obtain an annotated view of the statements in the source that are not
|
||
yet covered, run:
|
||
|
||
::
|
||
|
||
>coverage html
|
||
|
||
Open ``htmlcov/index.html`` in a browser to view the report. More
|
||
information regarding the ``coverage`` tool can be found at
|
||
https://coverage.readthedocs.io/en/v4.5.x/.
|