Metadata-Version: 2.4
Name: ioNERDSS
Version: 2.0
Summary: Package for preparing NERDSS inputs and analysing outputs.
Author-email: Yue Moon Ying <yying7@jh.edu>, Samuel L Foley <sfoley13@jh.edu>, "Zixiu (Hugh) Liu" <zliu140@jhu.edu>, Sikao Guo <sikaoguo@gmail.com>, Mankun Sang <msang2@jhu.edu>
License: GPL-3.0
Keywords: NERDSS Simulation,Model Setup,Analysis Tools
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.26.4
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: tqdm
Requires-Dist: PyQt6
Requires-Dist: pyqtgraph
Requires-Dist: PyOpenGL
Requires-Dist: biopython
Requires-Dist: scipy<2,>=1.13.1
Requires-Dist: scikit-learn
Requires-Dist: requests
Requires-Dist: ipympl
Requires-Dist: networkx
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: proaffinity
Requires-Dist: numpy==1.26.4; extra == "proaffinity"
Requires-Dist: scipy==1.13.1; extra == "proaffinity"
Requires-Dist: torch==2.2.2; extra == "proaffinity"
Requires-Dist: torchvision==0.17.2; extra == "proaffinity"
Requires-Dist: torchaudio==2.2.2; extra == "proaffinity"
Requires-Dist: torch_geometric==2.3.0; extra == "proaffinity"
Requires-Dist: scikit-learn>=1.5.0; extra == "proaffinity"
Requires-Dist: transformers==4.38; extra == "proaffinity"
Requires-Dist: tokenizers==0.15.2; extra == "proaffinity"
Requires-Dist: huggingface-hub>=0.33.2; extra == "proaffinity"
Requires-Dist: safetensors>=0.5.3; extra == "proaffinity"
Requires-Dist: accelerate>=0.26; extra == "proaffinity"
Provides-Extra: ovito-rendering
Requires-Dist: ovito; extra == "ovito-rendering"
Requires-Dist: imageio; extra == "ovito-rendering"
Requires-Dist: Pillow; extra == "ovito-rendering"
Provides-Extra: jupyter
Requires-Dist: jupyter; extra == "jupyter"
Requires-Dist: jupyterlab; extra == "jupyter"
Requires-Dist: ipykernel; extra == "jupyter"
Requires-Dist: ipywidgets; extra == "jupyter"
Provides-Extra: docs
Requires-Dist: furo; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Provides-Extra: all
Requires-Dist: pytest; extra == "all"
Requires-Dist: pytest-cov; extra == "all"
Requires-Dist: ovito; extra == "all"
Requires-Dist: imageio; extra == "all"
Requires-Dist: Pillow; extra == "all"
Requires-Dist: jupyter; extra == "all"
Requires-Dist: jupyterlab; extra == "all"
Requires-Dist: ipykernel; extra == "all"
Requires-Dist: ipywidgets; extra == "all"
Requires-Dist: furo; extra == "all"
Requires-Dist: nbsphinx; extra == "all"
Requires-Dist: ioNERDSS[proaffinity]; extra == "all"
Dynamic: license-file

# ionerdss
[![Documentation Status](https://readthedocs.org/projects/ionerdss/badge/?version=latest)](https://ionerdss.readthedocs.io/en/latest/?badge=latest)
[![Run Unit Tests](https://github.com/JohnsonBiophysicsLab/ionerdss/actions/workflows/unittest.yml/badge.svg?branch=main&event=push)](https://github.com/JohnsonBiophysicsLab/ionerdss/actions/workflows/unittest.yml)
![PyPI](https://img.shields.io/pypi/v/ioNERDSS.svg)
![PyPI - Downloads](https://img.shields.io/pypi/dm/ioNERDSS.svg)
![PyPI - Wheel](https://img.shields.io/pypi/wheel/ioNERDSS.svg)

**ionerdss** is a Python library that provides user‐friendly tools for setting up and analyzing output from the [NERDSS](https://github.com/JohnsonBiophysicsLab/NERDSS) reaction‐diffusion simulator.

---

## Installation

### 1. From PyPI (Recommended)

Requires Python 3.9 or later.

```bash
pip install ioNERDSS
```
To include optional features, you can specify them during installation:
```bash
# Example: Install with ODE solver and rendering tools
pip install "ioNERDSS[ode,ovito_rendering]"
```

### 2. For Development (from GitHub)

**Quick Start (Clone and Test):**
```bash
# Requires Python 3.9+
git clone https://github.com/JohnsonBiophysicsLab/ionerdss.git
cd ionerdss
pip install -e ".[test,jupyter]"  # Essential dev dependencies
pytest
```

**Detailed Setup for Contributors:**

If you want to contribute to development, work with examples, or need a specific environment setup:

**Prerequisites:**
*   [Git](https://git-scm.com/)
*   Python 3.9+
*   Your choice of environment manager: `conda`, `venv`, etc.
*   Optionally, [uv](https://github.com/astral-sh/uv) for faster performance

**Setup Instructions:**

1.  **Clone the repository:**
    ```bash
    git clone https://github.com/JohnsonBiophysicsLab/ionerdss.git
    cd ionerdss
    ```

2.  **Create and activate an environment:**

    *   **Using `conda` (Recommended for full environment):**
        ```bash
        conda env create -f env/environment.yml
        conda activate ionerdss-dev
        ```
    *   **Using `uv` and `venv` (Fastest):**
        ```bash
        python -m venv .venv
        source .venv/bin/activate  # On Windows: .venv\Scripts\activate
        uv pip install -r env/requirements-dev.txt
        ```
    *   **Using `pip` and `venv`:**
        ```bash
        python -m venv .venv
        source .venv/bin/activate  # On Windows: .venv\Scripts\activate
        pip install -r env/requirements-dev.txt
        ```

This installs `ionerdss` in editable mode with testing and Jupyter dependencies for typical development.

**For comprehensive development** (including heavy rendering and documentation tools):
```bash
pip install -e ".[all]"
```

---

## Running Tests

To run the unit tests locally, ensure you have installed the development environment (which includes `pytest` and `pytest-cov`).

Then, from the project root folder, run:
```bash
pytest
```

---

## Usage

```python
import ionerdss as ion

# Create a PDB model from structure
model = ion.PDBModel(pdb_id="1abc")
model.generate_model()

# Run analysis on simulation data
analysis = ion.Analysis("path/to/simulation/data")
analysis.plot_time_evolution()
```

## Examples

The `examples/` directory contains hands-on Jupyter notebooks demonstrating real molecular systems:

- **`Homo-3mer-5VA4.ipynb`** - 3-component homogeneous assembly
- **`Hetero-30mer-4YD9.ipynb`** - 30-component heterogeneous system  
- **`Homo-720mer-6MX4.ipynb`** - Large 720-component viral capsid
- **`book_chapter_example_system_1.ipynb`** - Comprehensive tutorial example

To run the examples locally:
```bash
git clone https://github.com/JohnsonBiophysicsLab/ionerdss.git
cd ionerdss
pip install -e ".[jupyter]"  # Install with Jupyter support
jupyter lab examples/
```

For additional tutorials, see the [online documentation](https://ionerdss.readthedocs.io/en/latest/ionerdss_tutorials.html).

### Run a quick trial with our server
Go to the [NERDSS server](http://52.15.142.249:5000/).

---

## Documentation
- **User Guide:** [ionerdss user guide](https://ionerdss.readthedocs.io/en/latest/ionerdss_documentation_v1_1.html).
- **API Reference:** [API](https://ionerdss.readthedocs.io/en/latest/ionerdss.html).

You can also build the docs locally using Sphinx:
```bash
# Ensure you are in your activated environment
pip install -e ".[docs]"  # Install documentation dependencies
sphinx-apidoc -o website/source ionerdss
cd website
make html
```
Then open `website/build/html/index.html` in your browser.

---

## Docker Development Environment

For isolated development with Jupyter Lab:
```bash
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 Lab accessible at `http://localhost:8888`.

---

## License
This project is licensed under the GPL‐3.0 License.
