multiscale_run package

Subpackages

Submodules

multiscale_run.bloodflow_manager module

class multiscale_run.bloodflow_manager.MsrBloodflowManager(vasculature_path, parameters)

Bases: object

Manager class for handling bloodflow-related operations.

This class is responsible for managing bloodflow data and operations within a multiscale simulation. It provides methods for retrieving bloodflow segment points, flows, volumes, entry nodes, and more. It also handles loading vasculature data and applying boundary flows to entry nodes.

Attributes

entry_nodes (list): List of entry nodes for bloodflow simulation. boundary_flows (numpy.ndarray): Boundary flows for entry nodes. graph (PointVasculature): The vasculature graph.

Initialize the MsrBloodflowManager.

This method initializes an instance of the MsrBloodflowManager class by loading vasculature data and calculating various bloodflow-related parameters. It also sets the entry nodes and boundary flows for subsequent bloodflow simulations.

Parameters:

  • vasculature_path (str) – The path to the vasculature data file.

  • parameters (dict) – A dictionary containing parameters for bloodflow calculations.

get_boundary_flows()

Calculate boundary flows for entry nodes.

This method calculates the boundary flows for entry nodes based on the specified input flow rate and entry nodes. The calculated boundary flows are stored in the ‘boundary_flows’ attribute of the MsrBloodflowManager.

Note

  • This method requires that the vasculature graph and entry nodes have been initialized.

  • The calculated boundary flows are based on the input flow rate (‘input_v’) and the entry nodes in the vasculature graph.

  • The calculated boundary flows are stored in the ‘boundary_flows’ attribute.

get_entry_nodes()

Get bloodflow input nodes (entry nodes).

This method determines the bloodflow input nodes in the vasculature graph. It identifies these nodes based on criteria defined by the ‘parameters’ provided when initializing the MsrBloodflowManager.

Returns

list: A list of bloodflow input nodes as node IDs.

get_flows(idxs: list = None)

Get the flow in each vasculature segment.

This method retrieves the blood flow values associated with each vasculature segment in the loaded vasculature graph.

Parameters:

idxs (list, optional) – A list of indices to select specific segments from the flow array. If not provided, the full array is returned.

Returns:

An array containing the flow values for each vasculature segment, or a selection based on the provided indices.

Return type:

numpy.ndarray

get_seg_points(scale)

Get a series disjoint segments described by the extreme points

return: np.array(2*n_segments, 3)

get_vols()

Get the volume in each vasculature segment.

This method retrieves the volume values associated with each vasculature segment in the loaded vasculature graph.

Returns

numpy.ndarray: An array containing the volume values for each vasculature segment.

load_circuit(vasculature_path)

Load the vasculature circuit from a Sonata file.

This method loads the vasculature circuit from the specified Sonata file at ‘vasculature_path’ and prepares it for further bloodflow computations.

Parameters

vasculature_path (str or Path): The path to the Sonata file containing vasculature data.

Returns

None

Note

  • The loaded vasculature graph is stored in the ‘graph’ attribute of the MsrBloodflowManager.

  • This method prepares the vasculature graph by setting edge data and creating a MultiIndex for edge properties based on section and segment IDs.

property n_segs

Convenience function to return the number of segments

set_radii(idxs: list[int], vals: list[float]) → None

Set radii for vasculature sections.

This method allows you to set radii for specific vasculature sections identified by their indices.

Parameters:

  • idxs – A list of vasculature section indices to set the radii for.

  • vals – A list of radii corresponding to the specified vasculature sections.

Returns:

None

Note

  • The method calculates equivalent radii to distribute across the specified sections while maintaining volume.

  • The updated radii are stored in the vasculature graph’s edge properties.

update_static_flow()

Update flow and volume for quasi-static computation.

This method updates the flow and volume properties of the vasculature graph based on the provided boundary flows, blood viscosity, and base pressure. It is used for quasi-static blood flow computations.

Note

  • The method takes boundary flows, blood viscosity, and base pressure into account to compute updated flow and volume properties for the vasculature.

  • It is typically used in the context of multiscale simulations involving blood flow.

multiscale_run.cli module

This module provides the command line interface of the multiscale-run console-scripts entrypoint of the Python package (see setup.py)

The CLI provides the required commands to create a run simulations.

multiscale_run.cli.argument_parser()
multiscale_run.cli.check(**kwargs)

Check environment sanity

multiscale_run.cli.command(func)

Decorator for every command functions

multiscale_run.cli.compute(**kwargs)

Compute the simulation

multiscale_run.cli.edit_mod_files(**kwargs)

Clone the Neurodamus mod files library for local editing

  1. $ cp -r $NEURODAMUS_NEOCORTEX_ROOT ./mod

  2. $ build_neurodamus.sh

  3. Patch simulation.sbatch to override NEURODAMUS_NEOCORTEX_ROOT

  4. Write instructions to the console

multiscale_run.cli.index(**kwargs)

Show metabolism index information

Without arguments shows all indexes. With idx_name shows partial matches from both PIdx and UIdx. Output format: PIdx.name (current_index): description #old_index

multiscale_run.cli.init(directory, circuit, check=True, force=False, metabolism='standard')

Setup a new simulation

multiscale_run.cli.main(**kwargs)

Package script entry-point for the multiscale-run CLI utility.

Parameters:

kwargs – optional arguments passed to the argument parser.

multiscale_run.cli.post_processing(notebook: str, **kwargs) → Path

Execute a Jupyter notebook over the simulation results to generate an HTML document

Returns

Path to the created HTML report

multiscale_run.cli.stats(**kwargs)

Get some stats from a simulation

multiscale_run.config module

class multiscale_run.config.MsrConfig(path=None)

Bases: dict

MultiscaleRun configuration class

Multiscale run Config constructor

This class is composed from a chain of json files. We start from “config_path” which can be provided or deducted from the environment. We look for a file named: <config_path>/simulation_config.json. This provides the first hook. We load the file as a dict (child) and look recursively if there is a “parent_config_path” marked. In that case, we add that dict as parent and merge them using the priority rules of utils.merge_dicts.

All the paths are PosixPaths at the end. There is no check if the paths really exist except for the various config paths.

Parameters:

path –

The path to the top configuration:

  • if None, then a file “simulation_config.json” is expected to be found in the current working directory.

  • otherwise, if this is a pathlib.Path instance pointing to a directory, then a file “simulation_config.json” is expected to be found in this directory.

  • Otherwise, if this is a pathlib.Path instance to a file, it is considered to be the JSON file to load.

property bloodflow_dt

Bloodflow dt. It is a multiple of neurodamus dts.

check(schema: Path = None)

Validate this configuration instance in regard to the MultiscaleRun SONATA extension data schema.

Parameters:

  • schema – If specified, overwrites the default path to

  • Schema (the JSON)

  • configuration. (file used to validate the)

Raises:

MsrConfigSchemaError – If ‘simulation_config’ section is not valid.

compute_multiscale_run_ndts()

Compute MultiscaleRun n dts based on the active simulators

Calculates the number of Neurodamus dts required to synchronize simulations.

conn_dt(conn)

Get the time step for a connection synchronization.

Parameters:

conn – Connection object with src_simulator and dest_simulator attributes.

Returns:

The connection’s synchronization time step in milliseconds. None: If the connection is not active.

Return type:

float

conn_ndts(conn)

Get the number of Neurodamus dts for a connection synchronization.

Parameters:

conn – Connection object with src_simulator and dest_simulator attributes.

Returns:

Number of Neurodamus dts for connection sync (custom value or LCM of source/dest ndts). None: If the connection is not active.

Return type:

int

classmethod default(**kwargs)

Create a MsrConfig instance based on the default circuit. If keywords arguments are specified, then initialize a simulation by calling multiscale_run.cli.init(**kwargs).

Returns:

configuration using the default circuit

Return type:

MsrConfig

dt_info() → str

Info about the various dts of the simulation. If the simulator is inactive its dt is none.

Returns:

A string containing the a str with DTS information.

Return type:

str

Example

>>> dt_info_str = config.dt_info()
>>> print(dt_info_str)
is_bloodflow_active()

Convenience function to check if a bloodflow is active

is_conn_active(conn)

Check if a connection is active.

Parameters:

conn – Connection object with src_simulator and dest_simulator attributes.

Returns:

True if both source and destination simulators are active.

Return type:

bool

is_manager_active(manager_name: str)

Convenience function to check if a manager is active

is_metabolism_active()

Convenience function to check if a metabolism is active

is_steps_active()

Convenience function to check if a steps is active

items()

Generate key-value pairs from the configuration.

This method iterates over the configuration and generates key-value pairs, which can be used in various contexts where iteration is required.

Yields

Tuple: A tuple containing a key-value pair, where the first element is the key (attribute) and the second element is the corresponding value.

Example:

>>> for key, value in config.items():
...     print(key, value)
manager_dt(manager)

Get the time step for a specific manager.

Parameters:

manager (str) – The manager name (e.g., ‘neurodamus’, ‘metabolism’, ‘steps’).

Returns:

The manager’s time step in milliseconds. None: If the manager is not active.

Return type:

float

manager_idts(manager, idts)

Computes how many idts passed for a certain simulator the moment we are in time mesured in idts

manager_ndts(manager)

Get the number of Neurodamus dts for a specific manager.

Parameters:

manager (str) – The manager name (e.g., ‘neurodamus’, ‘metabolism’, ‘steps’).

Returns:

Number of Neurodamus dts for the manager (1 for neurodamus, configured value for others). None: If the manager is not active.

Return type:

int

property metabolism_dt

Metabolism dt. It is a multiple of neurodamus dts.

property multiscale_run_dt

Multiscale run dt. Computed based on the synchronization requirements.

Returns:

The MultiscaleRun time step in milliseconds, computed as ndts * neurodamus_dt.

Return type:

float

property neurodamus_dt

Neurodamus dt. Base time step for the NEURON simulator. This is the “unit of time” of the whole multiscale run. Every other dt is a multiple of this:

simulator_dt = ndts*neurodamus_dt

Returns:

The Neurodamus time step in milliseconds.

Return type:

float

Raises:

MsrConfigException – If ‘run.dt’ attribute is missing from config.

static pretty_print_conn(conn)

Generate a human-readable string representation of a connection.

Parameters:

conn – Connection object with src_simulator, dest_simulator, src_get_kwargs, and action attributes.

Returns:

Formatted string describing the connection.

Return type:

str

property steps_dt

Steps dt. It is a multiple of neurodamus dts.

values()

Generate values from the configuration.

This method iterates over the configuration and generates the values associated with each key. It can be used when you only need to access the values in the configuration.

Yields

Any: The value associated with a specific configuration key.

Example:

>>> for value in config.values():
...     print(value)
exception multiscale_run.config.MsrConfigException

Bases: Exception

General error for the config object

exception multiscale_run.config.MsrConfigSchemaError(ve: ValidationError)

Bases: MsrConfigException

For invalid configuration in regard to the JSON Schema

class multiscale_run.config.NamedCircuit(path, sbatch_parameters, config_transform=None)

Bases: NamedCircuit

Define an internal circuit available within the MultiscaleRun package. The circuit is defined through the following fields:

  • path: its path on the filesystem

  • sbatch_parameters: recommended SLURM parameters for the SBATCH script running its simulation

  • config_transform: optional callable to apply on the loaded simulation_config.json

Create new instance of NamedCircuit(path, sbatch_parameters, config_transform)

config()
Returns

Instance of MsrConfig based on this circuit

json()
Returns

the raw JSON representation of this circuit

multiscale_run.connection_manager module

class multiscale_run.connection_manager.MsrConnectionManager(config, managers)

Bases: object

Tracks connection matrices for various models, enabling efficient caching.

This class maintains various connection matrices used in the multiscale simulation, improving efficiency by caching them when necessary.

Parameters:

config (MsrConfig) – The multiscale run configuration.

Initialize the MsrConnectionManager with a given configuration.

Parameters:

  • config (MsrConfig) – The multiscale run configuration.

  • managers (dict) – Managers dictionary.

bloodflow2metabolism_sync(icon: int, con, action: str) → None

Syncs data from ‘MsrBloodflowManager’ (source) to ‘MsrMetabolismManager’ (destination).

Parameters:

  • sync_event – event tag. It specifies when this sync takes place in the main loop.

  • icon – connection index. Position in the array of connections. It is important because later connections override previous ones.

  • con (MsrConfig) – Connection object from the MsrConfig object.

  • action – Syncing scheme. Details in: process_syncs. Not all the actions need to be implemented for all the sync types.

Returns:

None

Raises:

NotImplementedError – If the action is not implemented.

connect_bloodflow2steps()

Volumes and flows fractions in tets.

This method calculates and stores volumes and flows fractions within tetrahedral elements and synchronization matrices.

Returns

None

connect_neurodamus2neurodamus()

Add some useful matrices that map ndam points, segments, sections, and neurons.

This method calculates and stores several matrices that provide mappings between various components of neuronal and segment data.

Returns

None

connect_neurodamus2steps()

Neuron volume fractions in tets.

This method calculates the neuron volume fractions within tetrahedral elements and stores the results in connection matrices.

Returns

None

neurodamus2bloodflow_sync(icon: int, con, action: str) → None

Syncs data from ‘MsrNeurodamusManager’ (source) to ‘MsrBloodflowManager’ (destination).

Parameters:

  • sync_event – event tag. It specifies when this sync takes place in the main loop.

  • icon – connection index. Position in the array of connections. It is important because later connections override previous ones.

  • con (MsrConfig) – Connection object from the MsrConfig object.

  • action – Syncing scheme. Details in: process_syncs. Not all the actions need to be implemented for all the sync types.

Returns:

None

Raises:

NotImplementedError – If the action is not implemented.

neurodamus2metabolism_sync(icon: int, con, action: str) → None

Syncs data from ‘MsrNeurodamusManager’ (source) to ‘MsrMetabolismManager’ (destination).

Parameters:

  • sync_event – event tag. It specifies when this sync takes place in the main loop.

  • icon – connection index. Position in the array of connections. It is important because later connections override previous ones.

  • con (MsrConfig) – Connection object from the MsrConfig object.

  • action – Syncing scheme. Details in: process_syncs. Not all the actions need to be implemented for all the sync types.

Returns:

None

Raises:

NotImplementedError – If the action is not implemented.

neurodamus2steps_sync(icon: int, con, action: str) → None

Syncs data from ‘MsrNeurodamusManager’ (source) to ‘MsrStepsManager’ (destination).

Parameters:

  • sync_event – event tag. It specifies when this sync takes place in the main loop.

  • icon – connection index. Position in the array of connections. It is important because later connections override previous ones.

  • con (MsrConfig) – Connection object from the MsrConfig object.

  • action – Syncing scheme. Details in: process_syncs. Not all the actions need to be implemented for all the sync types.

Returns:

None

Raises:

NotImplementedError – If the action is not implemented.

remove_gids(failed_cells: list[int])

Remove igids from the various connection matrices, metabolism and neurodamus

Parameters:

failed_cells – list of errors for the failed cells. None if the cell is working.

Returns:

None

steps2metabolism_sync(icon: int, con, action: str) → None

Syncs data from ‘MsrStepsManager’ (source) to ‘MsrMetabolismManager’ (destination).

Parameters:

  • sync_event – event tag. It specifies when this sync takes place in the main loop.

  • icon – connection index. Position in the array of connections. It is important because later connections override previous ones.

  • con (MsrConfig) – Connection object from the MsrConfig object.

  • action – Syncing scheme. Details in: process_syncs. Not all the actions need to be implemented for all the sync types.

Returns:

None

Raises:

NotImplementedError – If the action is not implemented.

sync(idts) → None

Process connections based on number of neurodamus time steps that passed

The sync event marks, in the main loop, when the particular series of connections syncs take place.

There are 3 ways to sync that may or may not be implemented depending on what was needed:

  • sum: the values from the source are added to the values of destination and inserted in destination

  • set: the values from the source override the values in destination

  • merge: in this case we consider source and destination as having the same level of priority.

It is appropriate when one simulator produces something and the other one consumes it. In formulae:

delta_val_src + delta_val_dest + previous_val = val

Since we usually do not have deltas, we can convert it to:

val_src + val_dest - previous_val = val

After, the val is set for both, source and destination. As a side effect, results are source <-> desitination swap invaritant (obviously not the case for the other schemes) apart from the fact that the sync may be done in different parts of the code

Parameters:

dest_manager_name – destination manager name.

Returns:

None

multiscale_run.metabolism_manager module

exception multiscale_run.metabolism_manager.MsrAbortSimulationException

Bases: Exception

This error should not be recoverable. Something went very wrong and continuing the simulation is meaningless

exception multiscale_run.metabolism_manager.MsrExcludeNeuronException

Bases: Exception

This error should be recoverable. We just want to kick the neuron out of the simulation because it is misbehaving

exception multiscale_run.metabolism_manager.MsrMetabManagerException

Bases: Exception

Generic Metabolism Manager Exception

class multiscale_run.metabolism_manager.MsrMetabolismManager(config, neuron_pop_name: str, ncs: list)

Bases: object

Wrapper to manage the metabolism model

Initialize the MsrMetabolismManager.

Parameters:

  • config – Full multiscale configuration object controlling metabolism behavior.

  • neuron_pop_name – Name of the neuron population to which these gids belong.

  • raw_gids – List of cell gids managed by this metabolism instance.

Concepts:
vm:

2D array of shape (ngids x nu0). Represents the dynamic state variables of the metabolism model. It is initialized from the model’s default u0 vector and updated over time.

u0:

The default initial state vector of the metabolism model. Defines the starting membrane and metabolic variables for a single cell before tiling to all gids. At t0 vm is essentially the per-gid copy of u0. After, vm evolves from that.

parameters:

2D array of shape (ngids nparams). Contains per-cell biophysical parameters controlling reaction rates, transport coefficients, volumes, scaling factors, etc. Starts from a default parameter vector and may be overridden by config.

Differently from vm it does not evolve in the metabolism model. However, it may change in neurodamus or other parts of the code.

constants:

A collection of dataclass-based, global immutable values used by the metabolism equations. These define universal physical constants, stoichiometric coefficients, geometry-independent factors, etc. They can be selectively overridden via the configuration.

They should not change during the simulation.

alive_gids()

Convenience function to report which gids are still alive.

All the gids present are still alive.

check_inputs(failed_cells: list[str]) → None

Run all configured input validations for parameters and vm.

  • Reads metabolism.checks from the config.

  • Delegates each individual check to _check_input.

  • Populates failed_cells with error messages for gids that fail.

If no checks are configured, returns immediately.

errors = {'abort_simulation': <class 'multiscale_run.metabolism_manager.MsrAbortSimulationException'>, 'exclude_neuron': <class 'multiscale_run.metabolism_manager.MsrExcludeNeuronException'>}
get_error(key: str)

Get exception class by error key.

get_parameters_idx(idx: str)

Get parameters slice

get_vm_idx(idx: str)

Get vm slice

property ndts
property ngids

Number of GIDs managed by this instance.

property raw_gids

List of raw GIDs from neuron connections.

reset_constants()

Override constant dataclass fields defined under metabolism.constants.

For each class name: - Retrieve the corresponding class from constants. - Ensure it is a dataclass. - Validate that all provided keys exist on the dataclass. - Convert list values to tuples. - Apply overrides via setattr.

Raises:

  • TypeError – if the target class is not a dataclass.

  • AttributeError – if an override key does not exist on the dataclass.

reset_parameters()

Initialize parameter vectors for all gids.

  • Builds the default parameter vector via initial_conditions.make_parameters().

  • Applies config overrides when metabolism.parameters is provided.

  • Tiles the parameter vector to (ngids, nparams) and stores it in self.parameters.

Automatic rule: If mito_scale is not explicitly set in the config, compute it per-gid using _get_GLY_a_and_mito_vol_frac() and override the corresponding column.

This resets biophysical parameters while allowing selective overrides.

reset_u0()

Initialize the initial input vector (u0) for all gids.

  • Builds the default u0 vector via initial_conditions.make_u0().

  • Applies per-model overrides if metabolism.u0 is present in the config.

  • Tiles the resulting vector to shape (ngids, nvars) and stores it in self.vm.

This resets the dynamic state variables to their initial values.

set_parameters_idxs(vals: list[float], idxs: list[str] | str)

Set one or more parameters slices equal to the vals list

set_vm_idxs(vals, idxs: list[str] | str)

Set one or more vm slices equal to the vals list

solve(idts: int, failed_cells: list) → None

Advance metabolism simulation to target time step.

Already failed cells are skipped.

Parameters:

  • idts – Target time step in neurodamus dt units to advance to.

  • failed_cells – List of errors for the failed cells. Cells that are alive have None as value here.

multiscale_run.neurodamus_manager module

class multiscale_run.neurodamus_manager.MsrNeurodamusManager(config)

Bases: object

Handles neurodamus and keeps track of what neurons are working.

Initialize the MsrNeurodamusManager with the given configuration.

Parameters:

config – The configuration for the neurodamus manager.

check_neuron_removal_status()

Check the status of neuron removal and raise an exception if all neurons were removed.

This method checks the number of neurons and removed GIDs and provides status messages and warnings. If all neurons were removed, it aborts the simulation.

gen_secs(nc: Cell_V6, filter=None)

Generator of filtered sections for a neuron.

This method generates filtered sections for a neuron based on the provided filter.

Parameters:

  • nc – A neuron to generate sections from.

  • filter – An optional list of attributes to filter sections by.

Yields:

Filtered sections for the neuron.

gen_segs(sec)

Generator of segments for a neuron section.

This method generates segments for a neuron section.

Parameters:

sec – A neuron section.

Yields:

Segments in the neuron section.

gen_to_be_removed_segs()

Generate the segments ids that need to be removed.

get_compartment_report_var(var: str)
get_nXsecMat()

Get the nXsecMat matrix.

This method calculates the nXsecMat matrix, which gives the fraction of neuron in a tet.

Returns

sparse.csr_matrix: The nXsecMat matrix.

get_nsecXnsegMat(pts)

Get the nsecXnsegMat matrix.

This method calculates the nsecXnsegMat matrix, which gives the fraction of neuron section in a tet.

Parameters:

pts – A list of neuron segment points.

Returns:

The nsecXnsegMat matrix.

Return type:

sparse.csr_matrix

get_seg_points(scale)

Get the segment points for all neurons.

This method retrieves the extreme points of every neuron segment, returning a consistent structure across ranks.

Parameters:

scale – A scale factor for the points.

Returns:

A list of lists of local points for each neuron segment.

Return type:

list

get_var(var: str, weight: str = None, filter=None)

Get variable values per segment weighted by a specific factor (e.g., area or volume).

This method retrieves variable values per segment, weighted by a specific factor (e.g., area or volume).

Parameters:

  • var – The variable to retrieve.

  • weight – The factor for weighting (e.g., “area” or “volume”).

  • filter – An optional list of attributes to filter segments by.

Returns:

An array containing the variable values per segment weighted by the specified factor.

Return type:

np.ndarray

get_vasc_radii()

Get vasculature radii generated by VascCouplingB.

This method retrieves vasculature radii generated by VascCouplingB.

Returns

Tuple: A tuple containing lists of vasculature IDs and radii.

get_vasculature_path()

Get the path to the vasculature generated by VascCouplingB.

Returns

str: The path to the vasculature.

gids(raw=False)

Convenience function to get the gids from ncs

set_managers()

Find useful node managers for neurons, astrocytes, and glio-vascular management.

This method sets the neuron_manager, astrocyte_manager, and glio_vascular_manager attributes based on available node managers.

Returns

None

set_var(var: str, vals: list[float], filter=None)

Set a variable to a specific value for all segments.

This method sets a variable to a specific value for all segments based on the provided filter.

Parameters:

  • var – The variable to set.

  • val – The value to set the variable to. 1 value per neuron. It should be the average.

  • filter – An optional list of attributes to filter segments by.

Returns:

None

solve(idts)
static stats()

Extract general statistics from a simulation

simulation_config.json is expected to be in the folder.

multiscale_run.preprocessor module

exception multiscale_run.preprocessor.MsrMeshError

Bases: MsrException

Generic Mesh Exception

class multiscale_run.preprocessor.MsrPreprocessor(config)

Bases: object

Preprocess manager for mesh generation in the Multi-Step Simulation Platform (MSP).

The MsrPreprocessor class is responsible for various preprocessing tasks related to mesh generation and node set configuration for simulations in the Multi-Step Simulation Platform (MSP). It provides methods for automatically generating node sets, extracting information from a circuit configuration, and generating and refining mesh files for simulations.

config

A configuration object that holds various settings and file paths for preprocessing tasks.

Note

  • This class works in the context of the MSP, which involves neuron and vasculature simulations.

  • It is used for creating the necessary input files for simulations, such as mesh files and node set configurations.

autogen_mesh(ndam_m=None, bf_m=None, pts=None)

Generate a STEPS mesh when it is missing based on neuron and vasculature points.

This method creates a STEPS mesh file if it doesn’t already exist. It uses neuron and vasculature points to generate the mesh. The scale parameter is set to 1 by default, as the code already accounts for rescaling.

Parameters:

  • ndam_m (object) – An object that provides neurodamus data, or None if not available.

  • bf_m (object) – An object that provides bloodflow data, or None if not available.

  • pts (list or array) – Additional custom points to include in the mesh, if provided.

Note

The method utilizes the neurodamus_manager and bloodflow_manager to obtain neuron and vasculature points. It scales the points slightly to generate a slightly larger mesh, and it logs the points used for the convex hull as well as the mesh generation process.

Example

>>> gen_mesh()
autogen_node_sets()

Generate node sets and save them as a JSON file.

This method generates node sets based on selected neurons and astrocytes and saves the configuration as a JSON file. Node sets are defined using a template, and the selected neuron and astrocyte IDs are included in the configuration.

Note

  • Node sets are generated according to the provided template.

  • The selected neuron and astrocyte IDs are included in the node sets configuration.

  • The resulting configuration is saved as a JSON file specified in ‘config.node_sets_path.’

Example

>>> gen_node_sets()
check_mesh()
extract_information_from_circuit()

Extract information from the circuit configuration.

This method is a helper function for generating node sets and is used to extract relevant information from the circuit configuration (ngv_config.json). It retrieves data about neurons and astrocytes based on the provided neuron population name and optional filtering criteria.

Sets Variables:

  • neuro_df (pandas DataFrame): DataFrame with information about selected neurons.

  • selected_neurons (numpy array): Array containing the selected neuron IDs.

  • selected_astrocytes (numpy array): Array containing the selected astrocyte IDs.

Note

  • The method reads the circuit configuration specified in the ‘config.circuit_path’.

  • It identifies astrocytes with valid endfeet and selected neurons based on the neuron population name.

  • The ‘filter_neuron’ flag determines whether to filter neurons connected to astrocytes.

  • Extracted data is stored in the class attributes ‘neuro_df,’ ‘selected_neurons,’ and ‘selected_astrocytes.’

Authors: Jean, Katta

property ntets

Count the total number of tets in the mesh

multiscale_run.reporter module

class multiscale_run.reporter.MsrReporter(config, gids: list[int], t_unit='ms')

Bases: object

A class for reporting multiscale simulation data.

Initializes the MsrReporter instance.

Parameters:

  • config (MsrConfig) – Configuration argument.

  • gids – List of gids.

  • n_bf_segs – number of bloodflow segments.

  • t_unit (optional) – Time unit. Defaults to “ms”.

init_files(simulator: str, dt: float, is_post_adv)

Initializes files for reporting.

pick_config_reports_section(simulator)

Selects the appropriate reports section from config.

Parameters:

simulator (str) – Simulator name.

Returns:

Reports configuration section.

Return type:

dict

record(idt: int, simulator: object, gids: list[int], is_post_adv: bool)

Records simulation data to HDF5 files.

Parameters:

  • idt (int) – Time step index.

  • simulator (object) – Simulator instance.

  • gids (list[int]) – List of GIDs to record.

  • is_post_adv (bool) – Whether this is a post-advancement record.

exception multiscale_run.reporter.MsrReporterException

Bases: Exception

multiscale_run.simulation module

This module provides an API to instantiate, init, and run simulations. It manipulates the “manager” classes and orchestrate the different models and pass data between them to perform the simulation

class multiscale_run.simulation.MsrSimulation(base_path=None)

Bases: object

compute()

Perform the actual simulation

finalize()
init()

Initialize the complete simulation setup.

Orchestrates warmup and initialization of all simulation components.

init_metabolism()

Initialize the metabolism simulator manager if active.

Creates metabolism manager only if metabolism is enabled in config.

init_multiscale_run()

Initialize multiscale run configuration and core components.

Sets up config, preprocessor, connection manager, and time tracking.

init_neurodamus()

Initialize the Neurodamus simulator manager.

Creates neurodamus manager, sets up logging, initializes failed cells tracking, and establishes neuron-to-neuron connections.

main()
static stats()

Get some stats from a simulation

sync()

Process syncs and cleanup (in case of recoverable failures)

warmup()

Instantiate the simulators in the proper and sensitive order.

Initializes MPI, imports neurodamus, and loads all manager modules.

multiscale_run.simulation.main()

multiscale_run.steps_manager module

class multiscale_run.steps_manager.MsrStepsManager(config)

Bases: object

Manages STEPS simulations and mesh operations.

Attributes

config: Configuration data for the simulation. mdl: The STEPS model. msh: The mesh for the simulation. ntets: Number of tetrahedra in the mesh. tet_vols: Array of tetrahedra volumes.

Initialize an instance of MsrStepsManager.

Parameters:

config – Configuration data for the simulation.

add_curr_to_conc(species_name: str, vals: list[float], idxs: list[int] = None)

Add membrane currents (from neurodamus for example) to STEPS concentrations.

This function updates concentrations of a specified species in the model using the provided membrane currents. It calculates the required change in concentration based on the input currents and time step and then adds this change to the existing concentrations. The function also ensures that concentrations remain non-negative and updates the concentrations for a specific set of tetrahedra.

Parameters:

  • species_name – The name of the species to be updated.

  • vals – The membrane currents (in mA).

  • idxs – An array of indices representing the tetrahedra to be updated. If not provided, all tetrahedra are updated.

Units:

  • Concentrations are in M/L.

  • curr is in mA.

  • tet_vols are in m^3.

Returns:

None

bbox()

Get the bounding box of the mesh.

Returns

tuple: A tuple containing the minimum and maximum coordinates of the mesh bounding box.

check_pts_inside_mesh_bbox(pts_list)

Check if the given points are inside the mesh bounding box.

Parameters:

pts_list (list of numpy.ndarray) – A list of NumPy arrays, where each array has a shape of (n, 3) representing the points to check.

Raises:

AssertionError – If the ratio of points inside the mesh bounding box is less than the specified ratio.

Returns:

None

get_nsegXtetMat(local_pts)

Get a matrix of section ratios in tetrahedra.

Parameters:

local_pts – Represent neuron segments.

Returns:

A sparse CSR matrix representing section ratios in tetrahedra.

Return type:

sparse.csr_matrix

get_tetXbfSegMat(pts)

Get a matrix of bloodflow segments in tetrahedra.

Parameters:

pts – Represent bloodflow segments.

Returns:

A sparse CSR matrix representing bloodflow segments in tetrahedra.

Return type:

sparse.csr_matrix

get_tetXtetInvMmat()

Get the inverse of the tetrahedra matrix for debugging.

Returns

sparse.csr_matrix: A sparse CSR matrix representing the inverse of the tetrahedra matrix.

get_tetXtetMat()

Get a matrix for measuring species dispersion in tetrahedra.

Returns

sparse.csr_matrix: A sparse CSR matrix for measuring species dispersion in tetrahedra.

get_tet_concs(species_name, idxs=None)

Get tetrahedra species concentrations.

Parameters:

  • species_name (str) – The name of the species.

  • idxs – An array of indices representing the tetrahedra to obtain concentrations from (optional).

Returns:

An array of species concentrations.

Return type:

numpy.ndarray

get_tet_counts(species_name, idxs=None)

Get tetrahedra species counts.

Parameters:

  • species – A species object.

  • idxs – An array of indices representing the tetrahedra to be counted (optional).

Returns:

An array of species counts.

Return type:

numpy.ndarray

get_tet_quantity(species_name, f, idxs=None)

Get a specific quantity for tetrahedra.

Parameters:

  • species_name (str) – The name of the species.

  • f – A function to obtain the quantity.

  • idxs – An array of indices representing the tetrahedra to obtain the quantity from (optional).

Returns:

An array of the specified quantity.

Return type:

numpy.ndarray

init_concentrations()

Initialize species concentrations.

This method initializes the concentrations of species based on the configuration.

init_mesh()

Initialize the mesh for the simulation.

Parameters:

mesh_path – The path to the mesh file or directory.

This method initializes the mesh by loading the mesh data from the specified file or directory.

init_sim()

Initialize the STEPS simulation.

This method initializes the STEPS model and solver, sets the initial concentrations, and prepares for simulations.

multiscale_run.utils module

exception multiscale_run.utils.MsrException

Bases: Exception

Custom exception class

class multiscale_run.utils.PyExprEval(config: dict)

Bases: object

Parse and evaluate Python expressions in a controlled environment

Parameters:

config – MultiscaleRun config. Can be a dict or an instance of multiscale_run.MsrConfig

property simple_eval

Get internal instance of simpleeval.SimpleEval

multiscale_run.utils.append_suffix(path: Path, suffix: str)

Append to path a suffix respecting file extensions

multiscale_run.utils.bbox(pts: ndarray)

Calculate the bounding box of a set of 3D points.

Parameters:

pts – An array of 3D points with shape (n, 3).

Returns:

An array containing the minimum and maximum coordinates of the bounding box.

The first element is the minimum coordinates, and the second element is the maximum coordinates.

Return type:

np.ndarray

Example:

pts = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
bbox(pts) # returns an array with the minimum and maximum coordinates of the bounding box.
multiscale_run.utils.cache_decorator(field_names, path=None, is_save: bool = None, is_load: bool = None, only_rank0: bool = False)

Caching system for parts of a class.

This decorator must be applied to a function that adds at least 1 field to a class. The specified field is cached in memory.

The function should not return any values at the moment.

Parameters:

  • field_names (str or list of str) – The name(s) of the field(s) to be cached.

  • path (str or Path, optional) – The path to the cache directory. Defaults to None.

  • is_save – If True, data is saved to the cache. Defaults to None.

  • is_load – If True, data is loaded from the cache. Defaults to None.

  • only_rank0 – If True, cache is only used on rank 0. Defaults to False.

Returns:

The wrapped method.

Return type:

function

Note

This decorator facilitates the caching of data in memory.

Example:

@cache_decorator("my_field", path="/cache", is_save=True, is_load=True)
def my_method(self, *args, **kwargs):
    # Your method implementation here
multiscale_run.utils.check_value(v: float, lb: float = -inf, hb: float = inf, leb: float = -inf, heb: float = inf, err: Exception = <class 'multiscale_run.utils.MsrException'>, msg: str = '')

Check if a value is within specified bounds and raising an exception if it’s not.

Parameters:

  • v – The value to be checked.

  • lb – The lower bound (default: negative infinity).

  • hb – The upper bound (default: positive infinity).

  • leb – The lower or equal bound (default: negative infinity).

  • heb – The higher or equal bound (default: positive infinity).

  • err – The exception class to be raised (default: MsrException).

  • msg – Error affix. For when deduction fails.

Raises:

MsrException – If the value is None, not floatable, NaN, or outside the specified bounds. Custom exception otherwise.

multiscale_run.utils.comm()

Returns The MPI communicator (mpi4py.MPI.Comm)

Copy links to dest_dir if it does not exist.

multiscale_run.utils.delete_cols(mat, indices)

Remove the columns denoted by indices from the matrix mat.

Parameters:

  • mat – The matrix (NumPy array or CSR sparse matrix).

  • indices – The indices of columns to be deleted.

Returns:

The modified matrix with specified columns removed.

Raises:

ValueError – If the input matrix is not a NumPy array or CSR sparse matrix.

Example:

new_matrix = delete_cols(matrix_or_sparse, [2, 4, 6])
multiscale_run.utils.delete_rows(mat, indices)

Remove the rows denoted by indices from the matrix mat.

Parameters:

  • mat – The matrix (NumPy array or CSR sparse matrix).

  • indices – The indices of rows to be deleted.

Returns:

The modified matrix with specified rows removed.

Raises:

ValueError – If the input matrix is not a NumPy array or CSR sparse matrix.

Example:

new_matrix = delete_rows(matrix_or_sparse, [2, 4, 6])
multiscale_run.utils.describe_obj(v, affix: str = '')

Inspect the structure and statistics of a variable and its contents.

This function provides a detailed view of the variable and its subcomponents, including lists, dictionaries, and NumPy arrays, along with their statistics (mean, min, max).

Parameters:

  • v – The variable to inspect.

  • affix – A prefix to add to the printed output for formatting.

Example:

inspect(my_data, "  ")
multiscale_run.utils.generate_cube_corners(a: ndarray, b: ndarray, n: int) → ndarray

Generate an array of n cube corner points between two given points a and b.

Parameters:

  • a – The lower corner of the cube.

  • b – The upper corner of the cube.

  • n – The number of corner points to generate.

Returns:

An array of n corner points.

Return type:

np.ndarray

Example:

generate_cube_corners([1, 1, 1], [2, 3, 3], 8)
# returns an array of 8 corner points within the specified cube.
multiscale_run.utils.get_resolved_value(d: dict, key: str, in_place: bool = False)

Get the value of a key, replacing ${token} placeholders with corresponding values in the same dictionary.

This function retrieves the value associated with the specified key in the input dictionary (d), and recursively resolves ${token} placeholders in the value using other key-value pairs in the same dictionary.

Parameters:

  • d – The input dictionary containing key-value pairs.

  • key – The key whose value needs to be retrieved and resolved.

  • in_place – If True, performs in-place substitution of values in the input dictionary. Defaults to False.

Returns:

The resolved value associated with the specified key.

Return type:

str

multiscale_run.utils.get_subs_d(d: dict) → dict

Recursively extracts and filters string key-value pairs from a nested dictionary.

This function traverses the input dictionary recursively, retaining only the key-value pairs where both the key and the value are strings. It returns a new dictionary with these filtered pairs.

Args: - d: The input dictionary to process.

Returns: dict: A new dictionary containing only string key-value pairs.

multiscale_run.utils.get_var_name(lvl: int = 1, pos: int = 0) → str

Get the name of a variable from the caller’s scope.

Parameters:

  • lvl – The number of levels up in the call stack to look for the variable name (default: 1).

  • pos – The position of the variable in the calling function’s argument list (default: 0).

Returns:

The name of the variable.

multiscale_run.utils.heavy_duty_MPI_Gather(v: ndarray, root=0)

Optimized MPI gather wrapper for very big matrices and vectors

In particular, MPI fails when the final vector is longer than an INT32. Here we avoid this problem without sacrificing performance by sending one custom object per rank.

Parameters:

  • np.ndarray – it can be a 1 or 2D array of ints or floats

  • root (int, optional) – MPI root

Returns:

1 or 2D array of ints or floats

Return type:

np.ndarray

multiscale_run.utils.json_sanitize(obj)

Convenience function to convert recursively posix paths in a dict to make it json-able

multiscale_run.utils.load_json(path, base_subs_d=None) → dict

Convenience function to load json files.

Parameters:

path (Path or str) – path that should be extracted.

Returns:

dict from the json

multiscale_run.utils.log_stats(vec: list[float], lb: float = -inf, hb: float = inf, leb: float = -inf, heb: float = inf, msg: str = '')
multiscale_run.utils.logs_decorator(wrapped)

Decorator for logging function execution details.

This decorator logs the start and end of a function’s execution, its memory usage, and elapsed time.

Parameters:

wrapped (callable) – The function to be wrapped by the decorator.

Returns:

The wrapped function.

Return type:

callable

Example:

@logs_decorator
def my_function(arg1, arg2):
    # Your function implementation here
    return result
multiscale_run.utils.merge_dicts(parent: dict, child: dict)

Merge dictionaries recursively (in case of nested dicts) giving priority to child over parent for ties. Values of matching keys must match or a TypeError is raised.

Parameters:

  • parent – parent dict

  • child – child dict (priority)

Returns:

merged dict following the rules listed before

Return type:

dict

Example:

>>> parent = {"A":1, "B":{"a":1, "b":2}, "C": 2}
>>> child = {"A":2, "B":{"a":2, "c":3}, "D": 3}
>>> merge_dicts(parent, child)
{"A":2, "B":{"a":2, "b":2, "c":3}, "C": 2, "D": 3}
multiscale_run.utils.mpi()

Returns The mpi4py.MPI module

multiscale_run.utils.ppf(n)

Pretty Print of float

Parameters:

n (float) – float

Returns:

str

Return type:

str

multiscale_run.utils.print_once(*args, **kwargs)

Print only once among ranks

multiscale_run.utils.pushd(path)

Change the current working directory within the scope of a Python with statement

Parameters:

path – the directory to jump into

multiscale_run.utils.pushtempd(wrapped)

Callable decorator changing the current working directory to a temporary directory during the execution of the wrapped function.

Parameters:

wrapped – the function wrapped by the decorator.

multiscale_run.utils.rank()

Returns MPI rank of the current process (int)

multiscale_run.utils.rank0()

Returns True if the current process has MPI rank 0, False otherwise

multiscale_run.utils.rank_print(*args, **kwargs)

Print with rank information.

Parameters:

  • *args – Variable length positional arguments for print.

  • **kwargs – Variable length keyword arguments for print.

Note

This function appends the rank of the process to the output.

Example:

rank_print("Hello, World!")
multiscale_run.utils.remove_elems(v: list, to_be_removed: set) → list

Convenience function: removes elements from a list based on their indices.

Parameters:

  • v – The list from which elements will be removed.

  • to_be_removed – an iterable containing the indices of elements to be removed.

Returns:

A list with elements removed based on the provided indices.

multiscale_run.utils.remove_path(path)

Remove a directory at the specified path (rank 0 only).

Parameters:

path (str or Path) – The path to the directory to be removed.

Note

This function is intended for use on rank 0 in a parallel or distributed computing context. It attempts to remove the specified directory and ignores FileNotFoundError if the directory does not exist.

Example:

remove_path("/path/to/directory")
multiscale_run.utils.replace_values(obj: dict | list | str, replacements: dict)

Recursively replaces values in a dictionary, list, or string based on a replacement dictionary.

Parameters:

  • obj – object that needs the replacements

  • replacements – dictionary of string replacements

Returns:

the modified object

multiscale_run.utils.resolve_replaces(d: dict, base_subs_d: dict = None) → None

Resolve ${token} placeholders in string values of a nested dictionary, using specified substitution values.

This function processes a nested dictionary (d) and applies token substitution to string values. It first extracts and filters string key-value pairs from the dictionary, then resolves ${token} placeholders in those values using a combination of the original dictionary and additional base substitution values.

Parameters:

  • d – The input nested dictionary to process.

  • base_subs_d – Additional base substitution values. Defaults to an empty dictionary.

Returns:

The function performs in-place substitution on the input dictionary (d).

Return type:

None

multiscale_run.utils.size()

Returns The size of the MPI communicator (int)

multiscale_run.utils.stats(v)

Return some useful object stats if appropriate (used for debugging)

Parameters:

v (any) – any object

Returns:

some useful stats (if appropriate)

Return type:

str

multiscale_run.utils.strtobool(val)

Convert a string representation of truth to true (1) or false (0). True values are ‘y’, ‘yes’, ‘t’, ‘true’, ‘on’, and ‘1’; false values are ‘n’, ‘no’, ‘f’, ‘false’, ‘off’, and ‘0’. Raises ValueError if ‘val’ is anything else.

multiscale_run.utils.timesteps(end: float, step: float)

Timestep generator

Includes the end point

Example:

>>> timesteps(1, 0.2)
[0.2, 0.4, ..., 1.0]

Module contents

Source

multiscale_run.rst