pyneuroml.runners module#

Util methods related to running models.

File: pyneuroml/utils/runners.py

pyneuroml.runners.execute_command_in_dir(command: str, directory: str, verbose: bool = False, prefix: str = 'Output: ', env: Mapping | None = None) → Tuple[int, str]#

Execute a command in specific working directory

Parameters:

command (str) – command to run
directory (str) – directory to run command in
verbose (bool) – toggle verbose output
prefix (str) – string to prefix console output with
env (Mapping) – environment variables to be used

pyneuroml.runners.execute_command_in_dir_with_realtime_output(command: str, directory: str, verbose: bool = False, prefix: str = 'Output: ', env: str | None = None) → bool#

Run a command in a given directory with real time output.

NOTE: this has only been tested on Linux.

Parameters:

command (str) – command to run
directory (str) – directory to run command in
verbose (bool) – toggle verbose output
prefix (str) – string to prefix output with
env (str) – environment variables to be used

pyneuroml.runners.execute_multiple_in_dir(num_parallel: int | None, cmds_spec: List[Dict[Any, Any]]) → List[Tuple[int, str]]#

Wraper around execute_command_in_dir to allow running commands in parallel using ppft

Parameters:

num_parallel (None or int) – number of simulations to run in parallel, if None, ppft will auto-detect
cmds_spec –
list with keyword arguments to execute_command_in_dir
```
[
    {
        "kwarg1": value
    }
]
```

Returns:

list of tuples returned from execute_command_in_dir

Return type:

list

pyneuroml.runners.generate_sim_scripts_in_folder(engine: str, lems_file_name: str, root_dir: str | None = None, run_dir: str | None = None, generated_files_dir_name: str | None = None, *engine_args: Any, **engine_kwargs: Any) → str#

Generate simulation scripts in a new folder.

This method copies the model files and generates the simulation engine specific files (runner script for NEURON and mod files, for example) for the provided engine in a new folder. This is useful when running simulations on remote systems like a cluster or NSG which may not have the necessary dependencies installed to generate these scripts. One can then copy the folder to the remote system and run simulations there.

While copying the model files is not compulsory, we do it to ensure that there’s a clear correspondence between the set of model files and the generated simulation files generated from them. This is also allows easy inspection of model files for debugging.

Added in version 1.0.14.

Parameters:

engine (str) – name of engine: suffixes of the run_lems_with functions
lems_file_name (str) – name of LEMS simulation file
root_dir (str) – directory in which LEMS simulation file lives Any included files must be relative to this main directory
run_dir (str) –
directory in which model files are copied and backend specific files are generated.

By default, this is the directory that the command is run from (“.”)

It is good practice to separate directories where simulations are run from the source of the model/simulations.
generated_files_dir_name (str) – name of folder to move generated files to if not provided, a _generated suffix is added to the main directory that is created
engine_args – positional args to be passed to the engine runner function
engine_kwargs – keyword args to be be passed to the engine runner function

Returns:

name of directory that was created

Return type:

str

pyneuroml.runners.reload_saved_data(lems_file_name: str, base_dir: str = '.', t_run: datetime = datetime.datetime(1900, 1, 1, 0, 0), plot: bool = False, show_plot_already: bool = True, simulator: str | None = None, reload_events: bool = False, verbose: bool = False, remove_dat_files_after_load: bool = False) → dict | Tuple[dict, dict]#

Reload data saved from previous LEMS simulation run.

Parameters:

lems_file_name (str) – name of LEMS file that was used to generate the data
base_dir (str) – directory to run in
t_run (datetime) – time of run
plot (bool) – toggle plotting
show_plot_already (bool) – toggle if plots should be shown
simulator (str) – simulator that was used to generate data
reload_event (bool) – toggle whether events should be loaded
verbose (bool) – toggle verbose output
remove_dat_files_after_load (bool) – toggle if data files should be deleted after they’ve been loaded

TODO: remove unused vebose argument (needs checking to see if is being used in other places)

pyneuroml.runners.run_jneuroml(pre_args: str, target_file: str, post_args: str, max_memory: str = '400M', exec_in_dir: str = '.', verbose: bool = False, report_jnml_output: bool = True, exit_on_fail: bool = False, return_string: bool = False) → Tuple[bool, str] | bool#

Run jnml with provided arguments.

Parameters:

pre_args (list of strings) – pre-file name arguments
target_file (str) – LEMS or NeuroML file to run jnml on
max_memory (str) – maximum memory allowed for use by the JVM Note that the default value of this can be overridden using the JNML_MAX_MEMORY_LOCAL environment variable
exec_in_dir (str) – working directory to execute LEMS simulation in
verbose (bool) – toggle whether jnml should print verbose information
report_jnml_output (bool) – toggle whether jnml output should be printed
exit_on_fail (bool) – toggle whether command should exit if jnml fails
return_string (bool) – toggle whether the output string should be returned

Returns:

either a bool, or a Tuple (bool, str) depending on the value of return_string: True of jnml ran successfully, False if not; along with the output of the command

pyneuroml.runners.run_jneuroml_with_realtime_output(pre_args: str, target_file: str, post_args: str, max_memory: str = '400M', exec_in_dir: str = '.', verbose: bool = False, exit_on_fail: bool = True) → bool#

Run jnml with provided arguments with realtime output.

NOTE: this has only been tested on Linux.

Parameters:

pre_args (list of strings) – pre-file name arguments
target_file (str) – LEMS or NeuroML file to run jnml on
max_memory (bool) – maximum memory allowed for use by the JVM
exec_in_dir (str) – working directory to execute LEMS simulation in
verbose (bool) – toggle whether jnml should print verbose information
exit_on_fail (bool) – toggle whether command should exit if jnml fails

pyneuroml.runners.run_lems_with(engine: str, *args: Any, **kwargs: Any)#

Run LEMS with specified engine.

Wrapper around the many run_lems_with_* methods. The engine should be the suffix, for example, to use run_lems_with_jneuroml_neuron, engine will be jneuroml_neuron.

All kwargs are passed as is to the function. Please see the individual function documentations for information on arguments.

Parameters:

engine (string (valid names are methods)) – engine to run with
args – postional arguments to pass to run function
kwargs – named arguments to pass to run function

Returns:

return value of called method

pyneuroml.runners.run_lems_with_eden(lems_file_name: str, load_saved_data: bool = False, reload_events: bool = False, verbose: bool = False) → bool | dict | Tuple[dict, dict]#

Run LEMS file with the EDEN simulator

Parameters:

lems_file_name (str) – name of LEMS file to run
load_saved_data (bool) – toggle whether any saved data should be loaded
reload_events (bool) – toggle whether events should be reloaded
verbose (bool) – toggle whether to print verbose information

pyneuroml.runners.run_lems_with_jneuroml(lems_file_name: str, paths_to_include: list = [], max_memory: str = '400M', skip_run: bool = False, nogui: bool = False, load_saved_data: bool = False, reload_events: bool = False, plot: bool = False, show_plot_already: bool = True, exec_in_dir: str = '.', verbose: bool = False, exit_on_fail: bool = True, cleanup: bool = False) → bool | dict | Tuple[dict, dict]#

Parse/Run a LEMS file with jnml.

Tip: set skip_run=True to only parse the LEMS file but not run the simulation.

Parameters:

lems_file_name (str) – name of LEMS file to run
paths_to_include (list(str)) – additional directory paths to include (for other NML/LEMS files, for example)
max_memory (bool) – maximum memory allowed for use by the JVM
skip_run (bool) – toggle whether run should be skipped, if skipped, file will only be parsed
nogui (bool) – toggle whether jnml GUI should be shown
load_saved_data (bool) – toggle whether any saved data should be loaded
reload_events (bool) – toggle whether events should be reloaded
plot (bool) – toggle whether specified plots should be plotted
show_plot_already (bool) – toggle whether prepared plots should be shown
exec_in_dir (str) – working directory to execute LEMS simulation in
verbose (bool) – toggle whether jnml should print verbose information
exit_on_fail (bool) – toggle whether command should exit if jnml fails
cleanup (bool) – toggle whether the directory should be cleaned of generated files after run completion

pyneuroml.runners.run_lems_with_jneuroml_brian2(lems_file_name: str, paths_to_include: List[str] = [], max_memory: str = '400M', skip_run: bool = False, nogui: bool = False, load_saved_data: bool = False, reload_events: bool = False, plot: bool = False, show_plot_already: bool = True, exec_in_dir: str = '.', verbose: bool = False, exit_on_fail: bool = True, cleanup: bool = False) → bool | dict | Tuple[dict, dict]#

Run LEMS file with the NEURON simulator

Tip: set skip_run=True to only parse the LEMS file but not run the simulation.

Parameters:

lems_file_name (str) – name of LEMS file to run
paths_to_include (list(str)) – additional directory paths to include (for other NML/LEMS files, for example)
max_memory (bool) – maximum memory allowed for use by the JVM
skip_run (bool) – toggle whether run should be skipped, if skipped, file will only be parsed
nogui (bool) – toggle whether jnml GUI should be shown
load_saved_data (bool) – toggle whether any saved data should be loaded
reload_events (bool) – toggle whether events should be reloaded
plot (bool) – toggle whether specified plots should be plotted
show_plot_already (bool) – toggle whether prepared plots should be shown
exec_in_dir (str) – working directory to execute LEMS simulation in
verbose (bool) – toggle whether jnml should print verbose information
exit_on_fail (bool) – toggle whether command should exit if jnml fails
cleanup (bool) – toggle whether the directory should be cleaned of generated files after run completion

pyneuroml.runners.run_lems_with_jneuroml_netpyne(lems_file_name: str, paths_to_include: List[str] = [], max_memory: str = '400M', skip_run: bool = False, nogui: bool = False, num_processors: int = 1, load_saved_data: bool = False, reload_events: bool = False, plot: bool = False, show_plot_already: bool = True, exec_in_dir: str = '.', only_generate_scripts: bool = False, only_generate_json: bool = False, verbose: bool = False, exit_on_fail: bool = True, return_string: bool = False, cleanup: bool = False) → bool | Tuple[bool, str] | dict | Tuple[dict, dict]#

Run LEMS file with the NEURON simulator

Tip: set skip_run=True to only parse the LEMS file but not run the simulation.

Parameters:

lems_file_name (str) – name of LEMS file to run
paths_to_include (list(str)) – additional directory paths to include (for other NML/LEMS files, for example)
max_memory (bool) – maximum memory allowed for use by the JVM
skip_run (bool) – toggle whether run should be skipped, if skipped, file will only be parsed
nogui (bool) – toggle whether jnml GUI should be shown
num_processors (int) – number of processors to use for running NetPyNE
load_saved_data (bool) – toggle whether any saved data should be loaded
reload_events (bool) – toggle whether events should be reloaded
plot (bool) – toggle whether specified plots should be plotted
show_plot_already (bool) – toggle whether prepared plots should be shown
exec_in_dir (str) – working directory to execute LEMS simulation in
only_generate_scripts (bool) – toggle whether only the runner script should be generated
verbose (bool) – toggle whether jnml should print verbose information
exit_on_fail (bool) – toggle whether command should exit if jnml fails
return_string (bool) – toggle whether command output string should be returned
cleanup (bool) – toggle whether the directory should be cleaned of generated files after run completion

Returns:

either a bool, or a Tuple (bool, str) depending on the value of return_string: True of jnml ran successfully, False if not; along with the output of the command. If load_saved_data is True, it returns a dict with the data

pyneuroml.runners.run_lems_with_jneuroml_neuron(lems_file_name: str, paths_to_include: List[str] = [], max_memory: str = '400M', skip_run: bool = False, nogui: bool = False, load_saved_data: bool = False, reload_events: bool = False, plot: bool = False, show_plot_already: bool = True, exec_in_dir: str = '.', only_generate_scripts: bool = False, compile_mods: bool = True, verbose: bool = False, exit_on_fail: bool = True, cleanup: bool = False, realtime_output: bool = False) → bool | dict | Tuple[dict, dict]#

Run LEMS file with the NEURON simulator

Tip: set skip_run=True to only parse the LEMS file but not run the simulation.

Parameters:

lems_file_name (str) – name of LEMS file to run
paths_to_include (list(str)) – additional directory paths to include (for other NML/LEMS files, for example)
max_memory (bool) – maximum memory allowed for use by the JVM
skip_run (bool) – toggle whether run should be skipped, if skipped, file will only be parsed
nogui (bool) – toggle whether jnml GUI should be shown
load_saved_data (bool) – toggle whether any saved data should be loaded
reload_events (bool) – toggle whether events should be reloaded
plot (bool) – toggle whether specified plots should be plotted
show_plot_already (bool) – toggle whether prepared plots should be shown
exec_in_dir (str) – working directory to execute LEMS simulation in
only_generate_scripts (bool) – toggle whether only the runner script should be generated
compile_mods (bool) – toggle whether generated mod files should be compiled
verbose (bool) – toggle whether jnml should print verbose information
exit_on_fail (bool) – toggle whether command should exit if jnml fails
cleanup (bool) – toggle whether the directory should be cleaned of generated files after run completion
realtime_output (bool) – toggle whether realtime output should be shown

pyneuroml.runners.run_multiple_lems_with(num_parallel: int | None, sims_spec: Dict[Any, Any])#

Run multiple LEMS simulation files in a pool.

Uses the ppft module.

Parameters:

num_parallel (None or int) – number of simulations to run in parallel, if None, ppft will auto-detect
sims_spec (dict) –
dictionary with simulation specifications

Each key of the dict should be the name of the LEMS file to be simulated, and the keys will be dictionaries that contain the arguments and key word arguments to pass to the run_lems_with method:
```
{
    "LEMS1.xml": {
            "engine": "name of engine",
            "args": ("arg1", "arg2"),
            "kwargs": {
                "kwarg1": value
            }
}
```
Note that since the name of the simulation file and the engine are already explicitly provided, these should not be included again in the args/kwargs

Returns:

dict with results of runs, depending on given arguments:

{
    "LEMS1.xml": <results>
}

Return type:

dict