ionerdss package

Subpackages

Module contents

ionerdss: A user-friendly toolkit for setting up NERDSS simulations and analyzing results. ================================================

Documentation is available in the docstrings and online at https://ionerdss.readthedocs.io/en/

__version__ — SciPy version string

class ionerdss.Analyzer(root_dir: str | Path)[source]

Bases: object

Main analysis controller.

Usage:

analyzer = Analyzer(“./my_data”) analyzer.plot.free_energy()

compute_free_energy(sim: Simulation, temperature: float = 1.0) → DataFrame[source]

Computes free energy for a simulation from transition matrix file.

compute_size_distribution(sim: Simulation) → DataFrame[source]

Computes size distribution for a simulation from transition matrix file.

get_simulation(index_or_id: int | str) → Simulation[source]

Retrieves a simulation by index or ID.

load_simulations(simulations: List[int | str] | None = None, time_frame: Tuple[float, float] | None = None) → List[Simulation][source]

Compatibility method to retrieve simulations.

class ionerdss.ODEPipelineConfig(t_span: Tuple[float, float] = (0.0, 10.0), initial_concentrations: Dict[str, float] | None = None, solver_method: str = 'BDF', atol: float = 0.0001, plot: bool = True, plot_species_indices: List[int] | None = None, plot_sample_points: int = 1000, save_csv: bool = True, species_labels: Dict[int, str] | None = None)[source]

Bases: object

Configuration for ODE pipeline calculations.

t_span

Time span for integration [start, end] (default: [0.0, 10.0])

Type:

Tuple[float, float]

initial_concentrations

Initial concentrations for species as dict {species_name: concentration} If None, assumes first complex (monomer) at 1.0, others at 0.0

Type:

Dict[str, float] | None

solver_method

ODE solver method (default: “BDF” for stiff systems)

Type:

str

atol

Absolute tolerance for solver (default: 1e-4)

Type:

float

plot

Whether to generate plots (default: True)

Type:

bool

plot_species_indices

Indices of species to plot. If None, plots all (default: None)

Type:

List[int] | None

plot_sample_points

Number of points for plotting (default: 1000)

Type:

int

save_csv

Whether to save results to CSV (default: True)

Type:

bool

species_labels

Custom labels for species in plots (default: None)

Type:

Dict[int, str] | None

atol: float = 0.0001
initial_concentrations: Dict[str, float] | None = None
plot: bool = True
plot_sample_points: int = 1000
plot_species_indices: List[int] | None = None
save_csv: bool = True
solver_method: str = 'BDF'
species_labels: Dict[int, str] | None = None
t_span: Tuple[float, float] = (0.0, 10.0)
class ionerdss.System(workspace_path: str, pdb_id: str | None = None, units: Units | None = None)[source]

Bases: object

Complete molecular system containing all components and registries.

workspace_path

Path to workspace directory.

pdb_id

PDB identifier for this system.

units

Unit system used throughout the system.

molecule_types

Registry of molecule type definitions.

molecule_instances

Registry of molecule instances.

interface_types

Registry of interface type definitions.

interface_instances

Registry of interface instances.

classmethod from_dict(data: Dict[str, Any]) → System[source]

Create system from dictionary representation.

Parameters:

data – Dictionary containing system data.

Returns:

New System instance.

classmethod from_json(filepath: str | Path) → System[source]

Load system from JSON file.

Parameters:

filepath – Path to JSON file.

Returns:

New System instance.

get_summary() → Dict[str, Any][source]

Get summary statistics of the system.

Returns:

Dictionary with system statistics.

to_dict() → Dict[str, Any][source]

Convert system to dictionary representation.

Returns:

Dictionary containing complete system data.

to_json(filepath: str | Path) → None[source]

Save system to JSON file.

Parameters:

filepath – Path to output JSON file.

validate_system() → Dict[str, List[str]][source]

Validate system integrity.

Returns:

Dictionary with ‘errors’ and ‘warnings’ lists.

ionerdss.build_system_from_pdb(source: str, workspace_path: str | None = None, fetch_format: str | None = None, molecule_counts: Dict[str, int] | None = None, **hyperparams_kwargs) → System[source]

Build ionerdss System from PDB structure (simplified API).

This is a convenience function that combines PDBModelBuilder initialization and system building into a single call. All hyperparameter options can be passed as keyword arguments.

Parameters:

  • source – PDB ID (e.g., “4v6x”) or path to PDB/mmCIF file.

  • workspace_path – Workspace directory path. Defaults to “{source}_dir”.

  • fetch_format – Format for downloading structures (‘pdb’ or ‘mmcif’). If None, uses hyperparameter default (usually ‘bioassembly1’).

  • molecule_counts – Molecule counts for NERDSS export. Default 10 per type.

  • **hyperparams_kwargs –

    Any PDBModelHyperparameters field as keyword arguments. Common options:

    • interface_detect_distance_cutoff: float (default 0.6)

    • generate_nerdss_files: bool (default True)

    • nerdss_water_box: list[float] (default [100, 100, 100])

    • ode_enabled: bool (default False)

    • ode_time_span: tuple[float, float]

    • ode_solver_method: str

    • ode_plot: bool

    • ode_save_csv: bool

Returns:

Complete System object ready for simulation.

Examples

>>> # Simple usage with PDB ID
>>> from ionerdss import build_system_from_pdb
>>> system = build_system_from_pdb("4v6x")

>>> # With custom parameters
>>> system = build_system_from_pdb(
...     source="4v6x",
...     workspace_path="my_workspace",
...     interface_detect_distance_cutoff=1.0,
...     nerdss_water_box=[500, 500, 500],
...     ode_enabled=True,
...     ode_time_span=(0.0, 10.0)
... )

>>> # From local file
>>> system = build_system_from_pdb(
...     source="/path/to/structure.cif",
...     ode_enabled=True
... )
ionerdss.build_system_from_plat(solid_type: str, radius: float, sigma: float, output_nerdss=True, output_dir='DEFAULT') → Tuple[System, List[ReactionRule]][source]

Build a System containing the Platonic solid definition and its reactions. Default to also outpt nerdss files in a default directory

Parameters:

  • solid_type (str) – The platonic solid type [“cube”, “dode”, “icos”, “octa”, “tetr”]

  • radius (float) – The radius of the circumscribed sphere (nm)

  • sigma (float) – Distance between two binding sites (nm)

  • output_nerdss (bool) – Whether to output nerdss files

  • output_dir (str) – The directory to output nerdss files to; “DEFAULT” will use the default directory, which is {solid_type}_dir

Returns:

A tuple containing:

  • A System object populated with the MoleculeType and InterfaceTypes

  • A list of ReactionRule objects defining the binding interactions

Return type:

Tuple[System, List[ReactionRule]]

ionerdss.platonic_solid_generator

alias of PlatonicSolidsModel

ionerdss.run_ode_pipeline(complex_reaction_system: Any, output_dir: Path, config: ODEPipelineConfig | Dict | None = None, filename_prefix: str = 'ode_results') → Tuple[ndarray, ndarray, List[str], Dict[str, Path]][source]

Run complete ODE pipeline: calculate and save results.

This is the main convenience function that combines calculation and saving.

Parameters:

  • complex_reaction_system – The reaction system from PDB model

  • output_dir – Directory to save results

  • config – ODE pipeline configuration

  • filename_prefix – Prefix for output files

Returns:

Tuple of (time, concentrations, species_names, saved_files)