1. Installation

1.1. Dependencies

Installing non-Python dependencies may be done by

sudo apt-get update -y
sudo apt-get install -y python3 python3-pip  # Install python3 and pip
sudo apt-get install -y libopenmpi-dev       # Install MPI development headers
sudo apt-get install -y libhdf5-openmpi-dev  # Install MPI-enabled HDF5
sudo apt-get install -y pkg-config           # Install pkg-config, required for h5py install
sudo apt-get install -y curl wget

Warning

There might be memory leaks when using HyMD with OpenMPI 4.1.1. Therefore, using a newer version of OpenMPI is recommended. See Issue #186 for more details.

Installing Python dependencies may be done by

python3 -m pip install --upgrade pip
CC="mpicc" HDF5_MPI="ON" python3 -m pip install --no-binary=h5py h5py
python3 -m pip install mpi4py numpy cython

Warning

If MPI-enabled HDF5 and h5py can not be installed, limited support for serial HDF5 is available. Note that having MPI-enabled file IO is highly recommended, and simulation performance under serial HDF5 will potentially be very low.

Example dependency install on Ubuntu (apt) using serial HDF5:

sudo apt-get update -y
sudo apt-get install -y python3 python3-pip  # Install python3 and pip
sudo apt-get install -y libopenmpi-dev       # Install MPI development headers
sudo apt-get install -y libhdf5-serial-dev   # Install serial HDF5
sudo apt-get install -y curl wget

python3 -m pip install h5py mpi4py numpy cython

Running parallel simulations without a MPI-enabled HDF5 library available necessitates the use of the --disable-mpio argument to HyMD, see Command line arguments. Note that due to the way HyMD is built, a working MPI compiler is required even if all intended simulations are serial.

1.2. Installing HyMD

HyMD may be installed using pip by

python3 -m pip install hymd

1.3. Install in docker

A docker image with build essentials setup is available at dockerhub with tag mortele/hymd,

docker pull mortele/hymd:latest
docker run -it mortele/hymd
/app$ python3 -m pip install hymd

# Grab example input files
/app$ curl -O https://raw.githubusercontent.com/Cascella-Group-UiO/HyMD-tutorial/main/ideal_chain/ideal_chain.toml
/app$ curl -O https://raw.githubusercontent.com/Cascella-Group-UiO/HyMD-tutorial/main/ideal_chain/ideal_chain.HDF5

# Run simulation
/app$ python3 -m hymd ideal_chain.toml ideal_chain.HDF5 --verbose

1.4. Run interactively in Google Colaboratory

A Google Colaboratory jupyter notebook is setup here with a working HyMD fully installed and executable in the browser. We do not recommend running large-scale simulations in colab for pretty obvious reasons.

1.5. Common issues

1.5.1. Numpy errors while importing the Fortran force kernels

RuntimeError: module compiled against API version 0xe but this version of numpy is 0xd

Traceback (most recent call last):

  (...)

File "/..../HyMD/hymd/__init__.py", line 2, in <module>
  from .main import main  # noqa: F401
File "/..../HyMD/hymd/main.py", line 10, in <module>
  from .configure_runtime import configure_runtime
File "/..../hymd/configure_runtime.py", line 12, in <module>
  from .input_parser import read_config_toml, parse_config_toml
File "/..../HyMD/hymd/input_parser.py", line 12, in <module>
  from .force import Bond, Angle, Dihedral, Chi
File "/..../HyMD/hymd/force.py", line 8, in <module>
  from force_kernels import (  # noqa: F401
ImportError: numpy.core.multiarray failed to import

can normally be fixed by updating numpy versions,

python3 -m pip install -U numpy

1.5.2. Error building pfft-python due to missing curl/wget

Building wheel for pfft-python (setup.py) ... error
ERROR: Command errored out with exit status 1:
command: /usr/bin/python3 -u -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-install-fr6nt9m4/pfft-python/setup.py'"'"'; __file__='"'"'/tmp/pip-install-fr6nt9m4/pfft-python/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' bdist_wheel -d /tmp/pip-wheel-ne5et1y_
cwd: /tmp/pip-install-fr6nt9m4/pfft-python/
Complete output (56 lines):
running bdist_wheel
running build
running build_py

  (...)

curl -L -o /tmp/pip-install-fr6nt9m4/pfft-python/depends/..//depends/pfft-1.0.8-alpha3-fftw3-2don2d.tar.gz https://github.com/rainwoodman/pfft/releases/download/1.0.8-alpha3-fftw3-2don2d/pfft-1.0.8-alpha3-fftw3-2don2d.tar.gz
/tmp/pip-install-fr6nt9m4/pfft-python/depends/install_pfft.sh: 19: curl: not found
wget -P /tmp/pip-install-fr6nt9m4/pfft-python/depends/..//depends/ https://github.com/rainwoodman/pfft/releases/download/1.0.8-alpha3-fftw3-2don2d/pfft-1.0.8-alpha3-fftw3-2don2d.tar.gz
/tmp/pip-install-fr6nt9m4/pfft-python/depends/install_pfft.sh: 26: wget: not found
Failed to get https://github.com/rainwoodman/pfft/releases/download/1.0.8-alpha3-fftw3-2don2d/pfft-1.0.8-alpha3-fftw3-2don2d.tar.gz
Please check curl or wget
You can also download it manually to /tmp/pip-install-fr6nt9m4/pfft-python/depends/..//depends/
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/tmp/pip-install-fr6nt9m4/pfft-python/setup.py", line 86, in <module>
    setup(
  File "/usr/lib/python3/dist-packages/setuptools/__init__.py", line 144, in setup
    return distutils.core.setup(**attrs)
  File "/usr/lib/python3.8/distutils/core.py", line 148, in setup

  (...)

  File "/tmp/pip-install-fr6nt9m4/pfft-python/setup.py", line 56, in build_extensions
    build_pfft(self.pfft_build_dir, self.mpicc, ' '.join(self.compiler.compiler_so[1:]))
  File "/tmp/pip-install-fr6nt9m4/pfft-python/setup.py", line 28, in build_pfft
    raise ValueError("could not build fftw; check MPICC?")
ValueError: could not build fftw; check MPICC?
----------------------------------------
ERROR: Failed building wheel for pfft-python
Running setup.py clean for pfft-python
Failed to build pfft-python

can be fixed by installing either curl or wget

apt-get install -y curl wget

1.5.3. Error running parallel HyMD without MPI-enabled h5py

Traceback (most recent call last):
  File "/usr/local/Cellar/python@3.9/3.9.8/Frameworks/Python.framework/Versions/3.9/lib/python3.9/runpy.py", line 197, in _run_module_as_main
Traceback (most recent call last):
  File "/usr/local/Cellar/python@3.9/3.9.8/Frameworks/Python.framework/Versions/3.9/lib/python3.9/runpy.py", line 197, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/usr/local/Cellar/python@3.9/3.9.8/Frameworks/Python.framework/Versions/3.9/lib/python3.9/runpy.py", line 87, in _run_code
    return _run_code(code, main_globals, None,
  File "/usr/local/Cellar/python@3.9/3.9.8/Frameworks/Python.framework/Versions/3.9/lib/python3.9/runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "/usr/local/lib/python3.9/site-packages/hymd/__main__.py", line 2, in <module>
    exec(code, run_globals)
  File "/usr/local/lib/python3.9/site-packages/hymd/__main__.py", line 2, in <module>
    main()
  File "/usr/local/lib/python3.9/site-packages/hymd/main.py", line 64, in main
    with h5py.File(args.input, "r", **_kwargs) as in_file:
  File "/usr/local/lib/python3.9/site-packages/h5py/_hl/files.py", line 502, in __init__
    with h5py.File(args.input, "r", **_kwargs) as in_file:
    fapl = make_fapl(driver, libver, rdcc_nslots, rdcc_nbytes, rdcc_w0,
  File "/usr/local/lib/python3.9/site-packages/h5py/_hl/files.py", line 166, in make_fapl
    fapl = make_fapl(driver, libver, rdcc_nslots, rdcc_nbytes, rdcc_w0,
  File "/usr/local/lib/python3.9/site-packages/h5py/_hl/files.py", line 166, in make_fapl
    set_fapl(plist, **kwds)
  File "/usr/local/lib/python3.9/site-packages/h5py/_hl/files.py", line 52, in _set_fapl_mpio
    set_fapl(plist, **kwds)
  File "/usr/local/lib/python3.9/site-packages/h5py/_hl/files.py", line 52, in _set_fapl_mpio
    raise ValueError("h5py was built without MPI support, can't use mpio driver")
ValueError: h5py was built without MPI support, can't use mpio driver

Can be fixed by installing a MPI-enabled h5py through

python3 -m pip uninstall -y h5py
HDF5_MPI="ON" python3 -m pip install --no-binary=h5py h5py