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.Simulation(work_dir: str)[source]

Bases: object

Class for handling NERDSS simulation configurations and running simulations.

work_dir

The working directory for the simulation.

Type:

str

add_interface_state(mol_name: str, interface_name: str, states: List[str]) → None[source]

Adds states to a specified interface of a molecule.

Parameters:

  • mol_name (str) – The name of the molecule.

  • interface_name (str) – The name of the interface.

  • states (List[str]) – List of single-character state names.

Raises:

  • FileNotFoundError – If the molecule file does not exist.

  • ValueError – If no valid states are provided.

calculate_progress_percentage(sim_subdir: str) → int[source]

Calculates the progress percentage of a running simulation.

Parameters:

sim_subdir (str) – The directory of the simulation.

install_nerdss(nerdss_path: str | None = None) → None[source]

Installs the NERDSS package.

Parameters:

nerdss_path (str) – The path to install NERDSS. If None, uses the current directory.

modify_inp_file(modifications: Dict[str, Any], filename: str = 'parms.inp') → None[source]

Modifies the parameters of the parms.inp file. If isSphere and sphereR are provided, removes the WaterBox line and adds the new lines accordingly. If WaterBox is provided, removes isSphere and sphereR if they exist.

Parameters:

  • modifications (Dict[str, Any]) – A dictionary containing parameter modifications.

  • filename (str) – The name of the input file to modify. Defaults to “parms.inp”.

modify_mol_file(mol_name: str, modifications: Dict[str, Any]) → None[source]

Modifies the parameters of an existing .mol file.

Parameters:

  • mol_name (str) – The name of the molecule to modify.

  • modifications (Dict[str, Any]) – A dictionary containing parameter modifications.

Raises:

FileNotFoundError – If the specified molecule file does not exist.

print_inp_file(file_name: str = 'parms.inp') → None[source]

Prints the contents of the parms.inp file.

Parameters:

file_name (str) – The name of the input file to print. Defaults to “parms.inp”.

print_mol_parameters(mol_name: str) → None[source]

Prints all parameters of a given .mol file.

Parameters:

mol_name (str) – The name of the molecule to display.

Raises:

FileNotFoundError – If the specified molecule file does not exist.

pull_mol_file_information(file: str)[source]

Extracts molecular configuration information from a .mol-style input file into a dictionary.

Parameters:

filestr

Path to the input .mol file containing molecular relationship and configuration information.

Returns:

dict

A dictionary where keys are molecular attribute names (e.g., “mass”, “COM”, “D” for example) and values are either strings or lists of floats depending on the format in the file.

Example:

Given a section of a .mol file, the output might look like: {

“mass”: “1.0”, “COM”: [0.0, 0.0, 1.0], “D” = [13.0, 13.0, 13.0]

}

pull_parameter_file_information(file: str)[source]

Parses a simulation input file and extracts parameter, boundary, and molecule information into a dictionary.

Parameters:

filestr

Path to the input file containing the simulation parameters and configuration data.

Returns:

dict

A dictionary containing key-value pairs from the parameters, boundaries, and molecules blocks. - Keys are parameter names (e.g., “dt”, “runtime”). - Values are strings, floats, or lists of floats depending on the format of the line in the file.

Example:

Given an input file, the function might return: {

“nItr”: “10000”, “timeStep”: “0.1”, ‘WaterBox’ = [100, 100, 100],

}

pull_reaction_information(file: str)[source]

Extracts reaction information from a given input file and returns it as a dictionary.

The function parses a file (e.g., “parms.inp”) to extract details about reactions within a specific block labeled by “start reactions” and “end reactions”. For each reaction, the function captures relevant information and organizes it into a dictionary, where each key corresponds to a reaction equation (e.g., “A <-> B”) and its associated parameters.

Reaction details are stored as nested dictionaries, with the reaction equation as the outer key, and each parameter as an inner key-value pair.

Parameters:

filestr

The path to the input file containing the reaction information.

Returns:

dict

A dictionary where each key is a reaction equation (e.g., “A <-> B”) and the value is another dictionary containing parameters and values associated with that reaction. The parameters may include things like exclusion conditions and numerical values for reaction conditions.

Example:

Given an input file containing reaction data, the function will return a dictionary like: {

“A <-> B”: {

“norm1”: [1.0, 2.0, 3.0], “sigma”: “1.20302012”

}, “C -> D”: {

“onRate”: “0”

}

}

Notes:

  • The function assumes the input file contains structured reaction information in blocks marked by “start reactions” and “end reactions”.

  • Each reaction line may contain additional parameters, which are processed as key-value pairs.

  • Lines with “exclude” are treated specially, storing them in the dictionary under the respective reaction.

run_new_simulations(sim_indices: List[int] | None = None, sim_dir: str | None = None, nerdss_dir: str | None = None, parallel: bool = False, coordinate: bool = False, progress: bool = True, verbose=True) → None[source]

Runs NERDSS simulations based on the given parameters.

Parameters:

  • sim_indices (List[int], optional) – List of simulation indices to run. If None, runs one simulation with index = 1.

  • sim_dir (str, optional) – Directory where simulation results should be stored. Defaults to self.work_dir/nerdss_output.

  • nerdss_dir (str, optional) – Directory where NERDSS is installed. Defaults to self.work_dir/NERDSS.

  • parallel (bool, optional) – Whether to run simulations in parallel. Defaults to False.

Notes

FIXME: Doesn’t work on Fedora OS using Jupyter notebook. Doesn’t test on other OS. Doesn’t test using Python script.

run_restart_simulations(sim_indices: List[int] | None = None, sim_dir: str | None = None, nerdss_dir: str | None = None, restart_from: str = '', restart_sim_name: str = 'restart_sim', parallel: bool = False) → None[source]

Runs NERDSS simulations from a restart file.

Parameters:

  • sim_indices (List[int], optional) – List of simulation indices to restart. If None, restarts one simulation with index = 1.

  • sim_dir (str, optional) – Directory where restarted simulation results should be stored. Defaults to self.work_dir/nerdss_output.

  • nerdss_dir (str, optional) – Directory where NERDSS is installed. Defaults to self.work_dir/NERDSS.

  • restart_from (str) – Path to the directory containing the restart file.

  • restart_sim_name (str) – Name of the folder where restarted simulations will be stored.

  • parallel (bool, optional) – Whether to run simulations in parallel. Defaults to False.

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)