Nexus Installation

Installation of Nexus can be accomplished by setting a single environment variable, provided a working python environment exists.

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:

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:

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 Helpful Links for Installing Electronic Structure Codes.

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/.