pyneuroml.runners module#
Util methods related to running models.
File: pyneuroml/utils/runners.py
Copyright 2024 NeuroML contributors
- 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