Try NERDSS / ioNERDSS online
Try NERDSS / ioNERDSS on the webserver at nerdssdemo.org without local installation.
ionerdss is a Python library for building NERDSS-ready models from structures, running simulation workflows, and analyzing simulation outputs.
Installation
Recommended: Install in an isolated environment We strongly recommend installing ioNERDSS in an isolated environment using a package manager like conda or mamba to avoid conflicts with existing Python libraries.
Using Conda
# Create a new environment with Python 3.10 or later
conda create -n ionerdss python=3.10
conda activate ionerdss
1. From PyPI
Requires Python 3.10 or later.
pip install ioNERDSS
To include optional features:
pip install "ioNERDSS[jupyter]"
pip install "ioNERDSS[simularium]"
Movies of NERDSS runs (ionerdss.render_trajectory_movie) need no extra. The ovito_rendering extra only serves the deprecated visualize_trajectory_ovito.
On an HPC cluster, read step 4 before installing: the OVITO extras resolve differently there, and the environment belongs on scratch rather than in your home directory.
The ODE pipeline does not require a separate extra; it is included in the main package install.
proaffinity is the exception: it needs an environment of its own, set up in step 3 below.
2. For development
git clone https://github.com/JohnsonBiophysicsLab/ionerdss.git
cd ionerdss
pip install -e ".[test,jupyter]"
pytest
For the full contributor environment:
pip install -e ".[all]"
[all] covers everything except simularium (install it separately, as above) and proaffinity, which needs its own environment (step 3).
3. Binding affinity prediction (ProAffinity-GNN)
ProAffinity-GNN pins numpy 1.x and torch 2.2, which cannot share an environment with the numpy 2 that OVITO 3.16 and later need. Installed alongside the rest, either OVITO is held back to 3.15 and its slower software ray tracer or, depending on install order, one of the two is quietly broken, so it goes in an environment of its own and ioNERDSS calls into that environment when it needs a binding energy. Only a PDB path, the chain pairs and the resulting energies cross between them.
Set it up once:
conda env create -f env/proaffinity/environment.yml
export IONERDSS_PROAFFINITY_PYTHON="$(conda info --base)/envs/ionerdss-proaffinity/bin/python"
Without a checkout of this repository:
conda create -y -n ionerdss-proaffinity python=3.10
conda run -n ionerdss-proaffinity pip install "ioNERDSS[proaffinity]"
export IONERDSS_PROAFFINITY_PYTHON="$(conda info --base)/envs/ionerdss-proaffinity/bin/python"
Add that export to your shell profile to make it stick. You never activate the environment yourself -- with the variable set, predict_affinity=True works from your normal environment:
system = build_system_from_pdb(source="8erq", predict_affinity=True)
Affinity prediction also needs the ADFR suite. See docs/Proaffinity.md for that, for the venv and cluster variants, and for pointing at the environment explicitly instead of using the variable.
4. On an HPC cluster (Rockfish and other Slurm systems)
Nothing below needs root or a GPU, and all of it runs on a login node.
Build the environment on scratch, not in your home directory. [all] is several GB once OVITO and Qt land, and the ProAffinity sidecar adds several more in torch and model weights -- more than most home quotas allow. Send pip's cache and temporary directory there too, or the build will fill your home quota even when the environment itself does not live there.
module load anaconda # whatever `module avail conda` offers
export PIP_CACHE_DIR=/scratch/$USER/.cache/pip
export TMPDIR=/scratch/$USER/tmp && mkdir -p "$TMPDIR"
conda create -y -p /scratch/$USER/envs/ionerdss python=3.12
conda activate /scratch/$USER/envs/ionerdss
pip install "ioNERDSS[all]"
Substitute your cluster's scratch path -- on Rockfish that is your ~/scratch4-<PI> or ~/data-<PI> space. Python 3.10 through 3.13 all work for this environment; the ProAffinity sidecar below is the one piece that needs 3.10-3.12.
OVITO resolves to 3.15 on RHEL/Rocky 8 clusters, by design. OVITO 3.16 pins a PySide6 whose Linux wheels require glibc 2.34, and RHEL/Rocky 8 -- Rockfish included -- ships glibc 2.28. ioNERDSS therefore asks for ovito>=3.15 rather than >=3.16, so pip installs OVITO 3.15.5 with PySide6 6.9.3 there and takes 3.16 on newer systems. To see which side of that line you are on:
python -c "import platform; print(platform.libc_ver())"
If that prints 2.34 or newer you get OVITO 3.16 and its OpenGL renderer; below that you get 3.15 and the software ray tracer. Both render without a display.
If the install fails with No matching distribution found for PySide6, you are on ioNERDSS 2.2.3, which floors OVITO at 3.16 and so cannot resolve on glibc 2.28 at all:
pip install -U "ioNERDSS[all]"
If you have to stay on an older ioNERDSS, install the rendering extras by hand instead: pip install "ovito<3.16" imageio Pillow.
Rendering needs no display. render_trajectory_movie draws frames with numpy and Pillow, so it runs on a compute node as it stands. The deprecated visualize_trajectory_ovito also renders without X11, in a child process; where OVITO 3.15 is what resolved, its frames come from a CPU ray tracer, so give such a job a few cores and expect it to be slower than a desktop OpenGL render:
srun -n 1 -c 8 --pty bash # or the equivalent in your sbatch script
Notebooks. Register the environment as a Jupyter kernel so your cluster's notebook portal can find it:
python -m ipykernel install --user --name ionerdss --display-name "ioNERDSS"
ProAffinity. The sidecar environment belongs on scratch as well, for the same quota reason:
conda create -y -p /scratch/$USER/envs/ionerdss-proaffinity python=3.10
conda run -p /scratch/$USER/envs/ionerdss-proaffinity pip install "ioNERDSS[proaffinity]"
export IONERDSS_PROAFFINITY_PYTHON=/scratch/$USER/envs/ionerdss-proaffinity/bin/python
Put that export in your ~/.bashrc and in any sbatch script, since batch jobs do not inherit your login shell's environment. See docs/Proaffinity.md for the ADFR suite, which prediction also requires.
To run simulations for structures generated from ioNERDSS you will also need to install NERDSS.
NERDSS installation instructions - NERDSS Github
Usage
import ionerdss as ion
system = ion.build_system_from_pdb(
source="6bno",
workspace_path="6bno_dir",
# 6BNO-specific: with the defaults the actin filament mis-assembles in NERDSS
interface_detect_distance_cutoff=1.0,
nerdss_overlap_sep_limit=3.0,
ode_enabled=True,
count_transition=True, # the free-energy plot below reads the transition matrix
)
analyzer = ion.Analyzer("path/to/simulation/root")
analyzer.plot.free_energy()
Tutorials
Current examples live under tutorials/ and are the supported starting point for notebook-based workflows:
tutorials/quick_start_6bno.ipynbtutorials/ionerdss_tutorial_5l93.ipynbtutorials/ionerdss_tutorial_6bno.ipynbtutorials/ionerdss_dodecahedron_tutorial.ipynbtutorials/ionerdss_tutorial_pdb_validation.ipynbtutorials/troubleshoot_structure_validation.ipynbtutorials/ionerdss_tutorial_geometric_regularization.ipynbtutorials/ionerdss_tutorial_with_proaffinity_8y7s.ipynbtutorials/ionerdss_tutorial_simularium.ipynbtutorials/ionerdss_tutorial_trajectory_movie.ipynbtutorials/ionerdss_tutorial_ovito_gif.ipynb(deprecated)tutorials/additional_examples/1ihm.ipynbtutorials/additional_examples/4yd9.ipynb
Open them locally with Jupyter:
git clone https://github.com/JohnsonBiophysicsLab/ionerdss.git
cd ionerdss
pip install -e ".[jupyter]"
jupyter lab tutorials/
Hosted documentation and tutorial index:
- Docs: johnsonbiophysicslab.github.io/ionerdss
- Tutorials page: Tutorials
Run a quick trial with our server
Go to the NERDSS server.
Documentation
The documentation site is published with GitHub Pages from the website/ folder.
To preview it locally:
pip install -e ".[docs]"
mkdocs serve -f website/mkdocs.yml
Then open http://127.0.0.1:8000/.
Running tests
pytest
Docker development environment
Run these from the repository root. The image holds the ionerdss-dev conda environment from environment.yml, with ioNERDSS installed in editable mode from /app. The -v mount puts your checkout there, so the container runs the code you are editing and needs rebuilding only when dependencies change.
docker build --no-cache -t ionerdss_dev .
docker run -it --rm -v "$(pwd)":/app -p 8888:8888 ionerdss_dev
This creates a containerized environment with Jupyter Notebook accessible at http://localhost:8888.
License
This project is licensed under the GPL-3.0 License.
Release files for ioNERDSS 2.2.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ionerdss-2.2.5.tar.gz | 26.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ionerdss-2.2.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 53.7 MB
Release files / ionerdss-2.2.5.tar.gz
| Download URL | ionerdss-2.2.5.tar.gz |
|---|---|
| Size | 26.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
49887e401c252cc822d2ca3b7b853d4ed289ef98abe006415279f448983aafc7
|
|
BLAKE2b-256 checksum How to use checksums |
4d99d4fcde807fc7839b895739ff5a36ee8517fdd794d28f04c914520ab03340
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / ionerdss-2.2.5-py3-none-any.whl
| Download URL | ionerdss-2.2.5-py3-none-any.whl |
|---|---|
| Size | 26.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
67f12e36b9c4b1157262b81cbc558c68093b853710739d1000808e803f73d0c7
|
|
BLAKE2b-256 checksum How to use checksums |
1fdedfc6b1816240fc74bf47655c4631dd9846f3ac4ed4ace7b877f202b6752d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
