hnn_core.parallel_backends.MPIBackend#

class hnn_core.parallel_backends.MPIBackend(n_procs: None | int = None, mpi_cmd: str = 'mpiexec', use_hwthreading_if_found: bool = True, sensible_default_cores: bool = True, override_hwthreading_option: None | bool = None, override_oversubscribe_option: None | bool = None, verbose: bool = False, autoload_mpi_library: bool = True, mpi_lib_path: None | str | Path = None)[source]#

The MPIBackend class.

Parameters:
n_procsNone | int

The number of MPI processes requested by the user. Defaults to ‘None’, in which case it will attempt to detect the number of cores (including hardware-threads) and start parallel simulation over all of them.

mpi_cmdstr

The name of the mpi launcher executable. Will use ‘mpiexec’ (openmpi) by default.

use_hwthreading_if_foundbool

Specifies whether the class should try to detect hardware-threading, and, if it is found, then both use MPI’s ‘–use-hwthread-cpus’ option and change the number of CPU cores used. Defaults to ‘True’. Note that this is passed to an option of the same name in _determine_cores_hwthreading; see that function for more details.

sensible_default_coresbool

Whether to decrease the number of cores returned in a “reasonable manner”, such that it balances speed with the user experience. Specifically, this means that if the number of available cores is greater than some threshold (default 12), the threshold number of cores will be used instead of the total. If the number of cores is greater than 2 but less than the threshold (default 12), then the number of cores used will be subtracted by 1, so that there is a core left unused for the sake of the OS. Defaults to ‘True’. Note that this is passed to an option of the same name in _determine_cores_hwthreading

override_hwthreading_optionNone | bool

Force use of MPI’s ‘–use-hwthread-cpus’ support if changed from its default value of ‘None’. By default, ‘–use-hwthread-cpus’ is only passed if the above argument ‘use_hwthreading_if_found’ is ‘True’ and if hardware-threading is detected. If this argument is set to ‘True’, then ‘–use-hwthread-cpus’ will always be used, regardless of hardware-threading detection. If ‘False’, then ‘–use-hwthread-cpus’ will never be used.

override_oversubscribe_optionNone | bool

Force use of MPI’s ‘–oversubscribe’ support if changed from its default value of ‘None’. By default, ‘–oversubscribe’ is only passed if the user specifies a custom number of cores via ‘n_procs’ and if that number exceeds the number of detected available cores. If this argument is set to ‘True’, then ‘–oversubscribe’ will always be used. If ‘False’, then ‘–oversubscribe’ will never be used.

verbosebool, default False

If True, prints progress messages and status updates to stdout.

autoload_mpi_librarybool, default=True

Whether to automatically locate the MPI library file shipped by the PyPI ‘openmpi’ package (if installed) and point NEURON to it via the ‘MPI_LIB_NRN_PATH’ environment variable. If True (the default) and the MPI library is found, ‘MPI_LIB_NRN_PATH’ will be overwritten if it has already been set in your environment. Forced to False if ‘mpi_lib_path’ is provided.

mpi_lib_pathNone | str | Path, default=None

Absolute path to a user-supplied MPI library file (NOT a directory) such as ‘/usr/lib/libmpi.so.40’ on Linux or ‘/usr/lib/libmpi.40.dylib’ on macOS that NEURON should load. This file path will be passed to NEURON via the ‘MPI_LIB_NRN_PATH’ environment variable. If provided, ‘autoload_mpi_library’ is forced to False and ‘MPI_LIB_NRN_PATH’ will be overwritten if it has already been set in your environment. Note that we do not validate the whether the file is correct or will work with NEURON.

Attributes:
n_procsint

The number of processes MPI will actually use (spread over cores). If 1 is specified or mpi4py could not be loaded, the simulation will be run with the JoblibBackend

mpi_cmdlist of str

The mpi command with number of procs and options to be passed to Popen

expected_data_lengthint

Used to check consistency between data that was sent and what MPIBackend received.

proc_queuethreading.Queue

A Queue object to hold process handles from Popen in a thread-safe way. There will be a valid process handle present the queue when a MPI simulation is running.

verbosebool, default False

If True, prints progress messages and status updates to stdout.

Methods

simulate(net, tstop, dt, n_trials[, ...])

Simulate the HNN model in parallel on all cores

terminate()

Terminate running simulation on this MPIBackend

simulate(net, tstop, dt, n_trials, postproc=False, baseline_correction=True)[source]#

Simulate the HNN model in parallel on all cores

Parameters:
netNetwork object

The Network object specifying how cells are connected.

tstopfloat

The simulation stop time (ms).

dtfloat

The integration time step of h.CVode (ms)

n_trialsint

Number of trials to simulate.

postprocbool, default=False

Deprecated. If True, smoothing (dipole_smooth_win) and scaling (dipole_scalefctr) values are read from the Network’s parameter file, and applied to the dipole objects before returning (the default Network parameter file, hnn_core/param/default.json, uses a smoothing value of 30 ms and a scaling factor of 3000). Note that this setting only affects the dipole waveforms, and not somatic voltages, possible extracellular recordings etc. The preferred way is to use the smooth() and scale() methods after the simulation is run instead.

baseline_correctionbool, default=True

Whether to apply the baseline correction after simulation (which correction is used depends on Network._model_variant). Defaults to True, applying the appropriate correction.

Returns:
dpllist of Dipole

The Dipole results from each simulation trial

terminate()[source]#

Terminate running simulation on this MPIBackend

Safe to call from another thread from the one simulate_dipole was called from.