pyneuroml.pynml module#
Python wrapper around jnml command. (Thanks to Werner van Geit for an initial version of a python wrapper for jnml.)
For convenience and backward compatibility, this also includes various helper/utility methods that are defined in other modules in the package. But please try and use these from their defined locations as these imports will gradually be removed from here in the future.
- exception pyneuroml.pynml.NMLFileTypeError#
Bases:
RuntimeError
A custom file type error to use for failing file checks.
- class pyneuroml.pynml.StringIO(initial_value='', newline='\n')#
Bases:
_TextIOBase
Text I/O implementation using an in-memory buffer.
The initial_value argument sets the value of object. The newline argument is like the one of TextIOWrapper’s constructor.
- close()#
Close the IO object.
Attempting any further operation after the object is closed will raise a ValueError.
This method has no effect if the file is already closed.
- closed#
- getvalue()#
Retrieve the entire contents of the object.
- line_buffering#
- newlines#
- read(size=-1, /)#
Read at most size characters, returned as a string.
If the argument is negative or omitted, read until EOF is reached. Return an empty string at EOF.
- readable()#
Returns True if the IO object can be read.
- readline(size=-1, /)#
Read until newline or EOF.
Returns an empty string if EOF is hit immediately.
- seek(pos, whence=0, /)#
Change stream position.
- Seek to character offset pos relative to position indicated by whence:
0 Start of stream (the default). pos should be >= 0; 1 Current position - pos must be 0; 2 End of stream - pos must be 0.
Returns the new absolute position.
- seekable()#
Returns True if the IO object can be seeked.
- tell()#
Tell the current file position.
- truncate(pos=None, /)#
Truncate size to pos.
The pos argument defaults to the current file position, as returned by tell(). The current file position is unchanged. Returns the new absolute position.
- writable()#
Returns True if the IO object can be written.
- write(s, /)#
Write string to file.
Returns the number of characters written, which is always equal to the length of the string.
- pyneuroml.pynml.cell_info(cell: Cell) str #
Provide information on a NeuroML Cell instance:
morphological information:
Segment information:
parent segments
segment location, extents, diameter
segment length
segment surface area
segment volume
Segment group information:
included segments
biophysical properties:
channel densities
specific capacitances
- Parameters:
cell (Cell) – cell object to investigate
- Returns:
string of cell information
- pyneuroml.pynml.cells_info(nml_file_name: str) str #
Provide information about the cells in a NeuroML file.
- Parameters:
nml_file_name (str) – name of NeuroML v2 file
- Returns:
information on cells (str)
- pyneuroml.pynml.confirm_file_exists(filename: str) None #
Check if a file exists, exit if it does not.
- Parameters:
filename (str) – the filename to check
- pyneuroml.pynml.confirm_file_type(filename: str, file_exts: List[str], root_tag: str | None = None, error_str: str | None = None, sys_error: bool = False) None #
Confirm that a file exists and is of the provided type.
First we rely on file extensions to test for type, since this is the simplest way. If this test fails, we read the full file and test the root tag if one has been provided.
- Parameters:
filename (str) – filename to confirm
file_exts (list of strings) – list of valid file extensions, without the leading dot
root_tag (str) – root tag for file, used if extensions do not match
error_str (string (optional)) – an optional error string to print along with the thrown exception
- Raises:
NMLFileTypeError – if file does not have one of the provided extensions
- pyneuroml.pynml.confirm_lems_file(filename: str, sys_error: bool = False) None #
Confirm that file exists and is a LEMS file before proceeding with processing.
- Parameters:
filename (list of strings) – Names of files to check
sys_error (bool) – toggle whether function should exit or raise exception
- pyneuroml.pynml.confirm_neuroml_file(filename: str, sys_error: bool = False) None #
Confirm that file exists and is a NeuroML file before proceeding with processing.
- Parameters:
filename (str) – Names of files to check
sys_error (bool) – toggle whether function should exit or raise exception
- pyneuroml.pynml.convert_to_swc(nml_file_name, add_comments=False, target_dir=None)#
Find all <cell> elements and create one SWC file for each
- pyneuroml.pynml.convert_to_units(nml2_quantity: str, unit: str) float #
Convert a NeuroML2 quantity to provided unit.
- Parameters:
nml2_quantity (str) – NeuroML2 quantity to convert
unit (str) – unit to convert to
- Returns:
converted value (float)
- pyneuroml.pynml.evaluate_component(comp_type: ComponentType, req_variables: Dict[str, str] = {}, parameter_values: Dict[str, str] = {}) Dict[str, str] #
Expand a (simple) ComponentType and evaluate an instance of it by giving parameters & required variables
This is used in MOOSE NeuroML reader: BhallaLab/moose-core
Note that this is still a WIP.
- Parameters:
comp_type (neuroml.ComponentType) – component type to evaluate
req_variables (dict) – dictionary holding variables and their values
parameter_values (dict) – dictionary holding parameters and their values
- Returns:
dict of conditional derived variables and their calculated values
- Return type:
dict
- pyneuroml.pynml.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.pynml.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.pynml.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.pynml.extract_lems_definition_files(path: str | None | TemporaryDirectory = None) str #
Extract the NeuroML2 LEMS definition files to a directory and return its path.
This function can be used by other LEMS related functions that need to include the NeuroML2 LEMS definitions.
If a path is provided, the folder is created relative to the current working directory.
If no path is provided, for repeated usage for example, the files are extracted to a temporary directory using Python’s tempfile.mkdtemp function.
Note: in both cases, it is the user’s responsibility to remove the created directory when it is no longer required, for example using. the shutil.rmtree() Python function.
- Parameters:
path (str or None) – path of directory relative to current working directory to extract to, or None
- Returns:
directory path
- pyneuroml.pynml.generate_interactive_plot(xvalues: List[float], yvalues: List[float], title: str, labels: List[str] | None = None, linestyles: List[str] | None = None, linewidths: List[int] | List[float] | None = None, markers: List[str] | List[int] | None = None, markersizes: List[int] | List[float] | None = None, plot_bgcolor: str | None = None, modes: List[str] | None = None, xaxis: str | None = None, yaxis: str | None = None, legend_title: str | None = None, xaxis_color: str = '#fff', yaxis_color: str = '#fff', xaxis_width: float | int = 1, yaxis_width: float | int = 1, xaxis_mirror: str | bool = False, yaxis_mirror: str | bool = False, xaxis_spikelines: bool = False, yaxis_spikelines: bool = False, grid: bool = True, logx: bool = False, logy: bool = False, layout: dict | None = None, show_interactive: bool = True, save_figure_to: str | None = None) None #
Utility function to generate interactive plots using Plotly.
This function can be used to generate graphs with multiple plot lines. For example, to plot two metrics you can use:
generate_interactive_plot(xvalues=[[ax1, ax2, ax3], [bx1, bx2, bx3]], yvalues=[[ay1, ay2, ay3], [by1, by2, by3]], labels=["metric 1", "metric 2"])
Please note that while plotting multiple plots, you should take care to ensure that the number of x values and y values for each metric correspond. These lists are passed directly to Plotly for plotting without additional sanity checks.
A number of options are provided for convenience to allow plotting of multiple traces in the same plot and modification of common layout options. A layout dict can also be passed instead, which will overwrite any individually set options. If you need more customisation, please look at the source code of this method to write your own.
See the plotly documentation for more information: https://plotly.com/python-api-reference/generated/plotly.graph_objects.scatter.html
- Parameters:
xvalues (list of lists) – X values
yvalues (lists of lists) – Y values
title (str) – title of plot
labels (list of strings) – labels for each plot (default: None)
modes (str) – modes of individual plots: “markers”, “lines”, “lines+markers”: default “lines+markers”
linestyles (list strings) – list of line styles (default: None)
linewidths (list of floats/int) – list of line widths (default: None)
markers (list of plotly marker values. See: https://plotly.com/python-api-reference/generated/plotly.graph_objects.scatter.html#plotly.graph_objects.scatter.Marker.symbol) – list of markers (default: None)
markersizes (list of ints/floats) – list of marker sizes (default: None)
plot_bgcolor (str) – background color of plotting area b/w axes See https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html#plotly.graph_objects.Figure
xaxis (str) – label of X axis (default: None)
yaxis (str) – label of Y axis (default: None)
legend_title (str) – title of legend
xaxis_color (str) – color of xaxis
yaxis_color (str) – color of yaxis
xaxis_width (int/float) – width of xaxis
yaxis_width (int/float) – width of yaxis
xaxis_mirror (bool/str) – xaxis mirror options: https://plotly.com/python/reference/layout/xaxis/#layout-xaxis-mirror
yaxis_mirror (bool/str) – yaxis mirror options https://plotly.com/python/reference/layout/xaxis/#layout-xaxis-mirror
xaxis_spikelines (bool/str) – toggle spike lines on x axis https://plotly.com/python/hover-text-and-formatting/#spike-lines
yaxis_spikelines (bool/str) – toggle spike lines on x axis https://plotly.com/python/hover-text-and-formatting/#spike-lines
grid (boolean) – enable/disable grid (default: True)
logx (boolean) – should the x axis be in log scale (default: False)
logy (boolean) – should the y ayis be in log scale (default: False)
layout (dict) – plot layout properties: these will overwrite all other layout options specified See: https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html#plotly.graph_objects.Figure.update_layout
show_interactive (bool) – toggle whether interactive plot should be opened (default: True)
save_figure_to (str) – location to save generated figure to (default: None) Requires the kaleido package to be installed. See for supported formats: https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html#plotly.graph_objects.Figure.write_image Note: you can also save the file from the interactive web page.
- pyneuroml.pynml.generate_lemsgraph(lems_file_name: str, verbose_generate: bool = True) bool #
Generate LEMS graph using jNeuroML
- Parameters:
lems_file_name (str) – LEMS file to parse
verbose_generate (bool) – whether or not jnml should be run with verbosity output
- Returns bool:
True of jnml ran without errors, exits without a return if jnml fails
- pyneuroml.pynml.generate_nmlgraph(nml2_file_name: str, level: int = 1, engine: str = 'dot', **kwargs) None #
Generate NeuroML graph.
- Parameters:
nml2_file_name (str) – NML file to parse
level (int) – level of graph to generate (default: ‘1’)
engine (str) – graph engine to use (default: ‘dot’)
kwargs – other key word agruments to pass to GraphVizHandler See the GraphVizHandler in NeuroMLlite for information on permissible arguments: NeuroML/NeuroMLlite
- pyneuroml.pynml.generate_plot(xvalues: List[List[float]], yvalues: List[List[float]], title: str, labels: List[str] | None = None, colors: List[str] | None = None, linestyles: List[str] | None = None, linewidths: List[str] | None = None, markers: List[str] | None = None, markersizes: List[str] | None = None, xaxis: str | None = None, yaxis: str | None = None, xlim: List[float] | None = None, ylim: List[float] | None = None, show_xticklabels: bool = True, show_yticklabels: bool = True, grid: bool = False, logx: bool = False, logy: bool = False, font_size: int | None = None, bottom_left_spines_only: bool = False, cols_in_legend_box: int = 3, legend_position: str | None = 'best', show_plot_already: bool = True, animate: bool = False, animate_duration: int = 5, animate_writer: Tuple[str, List[str]] = ('pillow', []), save_figure_to: str | None = None, title_above_plot: bool = False, verbose: bool = False, close_plot: bool = False, interactive_legend: bool = True) Axes | None #
Utility function to generate plots using the Matplotlib library.
This function can be used to generate graphs with multiple plot lines. For example, to plot two metrics you can use:
generate_plot(xvalues=[[ax1, ax2, ax3], [bx1, bx2, bx3]], yvalues=[[ay1, ay2, ay3], [by1, by2, by3]], labels=["metric 1", "metric 2"])
Please note that while plotting multiple plots, you should take care to ensure that the number of x values and y values for each metric correspond. These lists are passed directly to Matplotlib for plotting without additional sanity checks.
Please see the Matplotlib documentation for the complete list of available styles and colours: - https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.plot.html - https://matplotlib.org/stable/gallery/index.html
Added in version 1.2.15:
animate
interactive_legend
- Parameters:
xvalues (list of lists) – X values
yvalues (lists of lists) – Y values
title (str) – title of plot
labels (list of strings) – labels for each plot (default: None)
colors (list of strings) – colours for each plot (default: None)
linestyles (list strings) – list of line styles (default: None)
linewidths (list of floats) – list of line widths (default: None)
markers (list strings) – list of markers (default: None)
markersizes (list of floats) – list of marker sizes (default: None)
xaxis (str) – label of X axis (default: None)
yaxis (str) – label of Y axis (default: None)
xlim (tuple of (float, float) or individual arguments: (left=float), (right=float)) –
left and right extents of x axis (default: None)
See https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.xlim.html
ylim (tuple of (float, float) or individual arguments: (top=float), (bottom=float)) –
top and bottom extents of y axis (default: None)
See https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.ylim.html
show_xticklabels (boolean) – whether labels should be shown on xtics (default: True)
show_yticklabels (boolean) – whether labels should be shown on ytics (default: True)
grid (boolean) – enable/disable grid (default: False)
logx (boolean) – should the x axis be in log scale (default: False)
logy (boolean) – should the y ayis be in log scale (default: False)
font_size (float) – font size
bottom_left_spines_only (boolean) – enable/disable spines on right and top (default: False) (a spine is the line noting the data area boundary)
cols_in_legend_box (float) – number of columns to use in legend box (default: 3)
legend_position (str) –
position of legend: See: https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html
Extra options:
”outer right” places the legend on the right, but outside the axes box
”bottom center” places the legend on the bottom, below the figure
Note that if labels is None, a legend is not shown
show_plot_already (boolean) – if plot should be shown when created (default: True)
animate (boolean) – if plot should be animated (default: False)
animate_duration (int) – approx duration (seconds) of the animation. animate should be True (default: 5)
animate_writer (tuple) –
writer for saving animation (default:
("pillow", []))
See: https://matplotlib.org/stable/users/explain/animations/animations.html#saving-animations
format :
writer=( "writer name", ["extra args list"])
example :
writer=( "imagemagick", ["-quality", "100"])
save_figure_to (str) – location to save generated figure/animation to (default: None)
title_above_plot (boolean) – enable/disable title above the plot (default: False)
verbose (boolean) – enable/disable verbose logging (default: False)
close_plot (bool) – call
pyplot.close()
to close plot after plotting, this is always done if using animationinteractive_legend (bool) – enable clicking on legend to toggle plot lines when using the matplotlib UI
- Returns:
matplotlib.axes.Axes object if plot is not closed, else None
- Raises:
ValueError – if the dimensions of xvalues/yvalues and option arguments colors/labels/linestyles/linewidths/markers/markersizes do not match
- pyneuroml.pynml.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.pynml.get_lems_model_with_units() Model #
Get a LEMS model with NeuroML core dimensions and units.
- Returns:
a lems.model.model.Model that includes NeuroML dimensions and units.
- pyneuroml.pynml.get_path_to_jnml_jar() str #
Get the path to the jNeuroML jar included with PyNeuroML.
- Returns:
path of jar file
- pyneuroml.pynml.get_standalone_lems_model(nml_doc_fn: str) Model #
Get the complete, expanded LEMS model.
This function takes a NeuroML2 file, includes all the NeuroML2 LEMS definitions in it and generates the complete, standalone LEMS model.
- Parameters:
nml_doc_fn (str) – name of NeuroML file to expand
- Returns:
complete LEMS model
- pyneuroml.pynml.get_value_in_si(nml2_quantity: str) float | None #
Get value of a NeuroML2 quantity in SI units
- Parameters:
nml2_quantity (str) – NeuroML2 quantity to convert
- Returns:
value in SI units (float)
- pyneuroml.pynml.list_exposures(nml_doc_fn: str, substring: str = '') dict[Component, List[Exposure]] | None #
List exposures in a NeuroML model document file.
This wraps around lems.model.list_exposures to list the exposures in a NeuroML2 model. The only difference between the two is that the lems.model.list_exposures function is not aware of the NeuroML2 component types (since it’s for any LEMS models in general), but this one is.
- Parameters:
nml_doc_fn – NeuroML2 file to list exposures for
substring (str) – substring to match for in component names
- Returns:
dictionary of components and their exposures.
The returned dictionary is of the form:
- pyneuroml.pynml.list_recording_paths_for_exposures(nml_doc_fn: str, substring: str = '', target: str = '') List[str] #
List the recording path strings for exposures.
This wraps around lems.model.list_recording_paths to list the recording paths in the given NeuroML2 model. The only difference between the two is that the lems.model.list_recording_paths function is not aware of the NeuroML2 component types (since it’s for any LEMS models in general), but this one is.
- Parameters:
nml_doc_fn – NeuroML2 file to list recording paths for
substring (str) – substring to match component ids against
- Returns:
list of recording paths
- pyneuroml.pynml.nml2_to_png(nml2_file_name: str, max_memory: str = '400M', verbose: bool = True) None #
Generate the PNG representation of a NeuroML model using jnml
- Parameters:
nml2_file_name (str) – name of NeuroML2 file to generate PNG for
max_memory (str) – maximum memory allowed for use by the JVM
verbose (bool) – toggle whether jnml should print verbose information
- pyneuroml.pynml.nml2_to_svg(nml2_file_name: str, max_memory: str = '400M', verbose: bool = True) None #
Generate the SVG representation of a NeuroML model using jnml
- Parameters:
nml2_file_name (str) – name of NeuroML2 file to generate SVG for
max_memory (str) – maximum memory allowed for use by the JVM
verbose (bool) – toggle whether jnml should print verbose information
- pyneuroml.pynml.quick_summary(nml2_doc: NeuroMLDocument) str #
Get a quick summary of the NeuroML2 document
NOTE: You should prefer nml2_doc.summary(show_includes=False)
- Parameters:
nml2_doc (NeuroMLDocument) – NeuroMLDocument to fetch summary for
- Returns:
summary string
- pyneuroml.pynml.read_lems_file(lems_file_name: str, include_includes: bool = False, fail_on_missing_includes: bool = False, debug: bool = False) Model #
Read LEMS file using PyLEMS. See WARNING below.
WARNING: this is a general function that uses PyLEMS to read any files that are valid LEMS even if they are not valid NeuroML. Therefore, this function is not aware of the standard NeuroML LEMS definitions.
To validate NeuroML LEMS files which need to be aware of the NeuroML standard LEMS definitions, please use the validate_neuroml2_lems_file function instead.
- pyneuroml.pynml.read_neuroml2_file(nml2_file_name: str, include_includes: bool = False, verbose: bool = False, already_included: list | None = None, optimized: bool = False, check_validity_pre_include: bool = False, fix_external_morphs_biophys: bool = False) NeuroMLDocument #
Read a NeuroML2 file into a nml.NeuroMLDocument
- Parameters:
nml2_file_name (str) – file of NeuroML 2 file to read
include_includes (bool) – toggle whether files included in NML file should also be included/read
verbose (bool) – toggle verbosity
already_included (list) – list of files already included
optimized (bool) – toggle whether the HDF5 loader should optimise the document
check_validity_pre_include (bool) – check each file for validity before including
fix_external_morphs_biophys (bool) – if a cell element has a morphology (or biophysicalProperties) attribute, as opposed to a subelement morphology/biophysicalProperties, substitute the external element into the cell element for ease of access
- Returns:
nml.NeuroMLDocument object containing the read NeuroML file(s)
- pyneuroml.pynml.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.pynml.reload_standard_dat_file(file_name: str) Tuple[dict, list] #
Reload a datafile as usually saved by jLEMS, etc. First column is time (in seconds), multiple other columns.
- Parameters:
file_name (str) – name of data file to load
- Returns:
tuple of (data, column names)
- pyneuroml.pynml.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.pynml.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.pynml.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.pynml.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.pynml.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.pynml.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.pynml.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.pynml.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.pynml.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
- pyneuroml.pynml.split_nml2_quantity(nml2_quantity: str) Tuple[float, str] #
Split a NeuroML 2 quantity into its magnitude and units
- Parameters:
nml2_quantity – NeuroML2 quantity to split
- Returns:
a tuple (magnitude, unit)
- pyneuroml.pynml.summary(nml2_doc: NeuroMLDocument | None = None, verbose: bool = False) None #
Wrapper around nml_doc.summary() to generate the pynml-summary command line tool.
- Parameters:
nml2_doc (NeuroMLDocument) – NeuroMLDocument object or name of NeuroML v2 file to get summary for.
verbose (bool) – toggle verbosity
- pyneuroml.pynml.validate_neuroml1(nml1_file_name: str, verbose_validate: bool = True, return_string: bool = False) bool | Tuple[bool, str] #
Validate a NeuroML v1 file.
NOTE: NeuroML v1 is deprecated. Please use NeuroML v2. This functionality will be dropped in the future.
- Parameters:
nml1_file_name (str) – name of NeuroMLv1 file to validate
verbose_validate (bool (default: True)) – whether jnml should print verbose information while validating
return_string (bool) – toggle to enable or disable returning the output of the jnml validation
- Returns:
Either a bool, or a tuple (bool, str): True if jnml ran without errors, false if jnml fails; along with the message returned by jnml
- pyneuroml.pynml.validate_neuroml2(nml2_file_name: str, verbose_validate: bool = True, max_memory: str | None = None, return_string: bool = False) bool | Tuple[bool, str] #
Validate a NeuroML2 file using jnml.
- Params nml2_file_name:
name of NeuroML 2 file to validate
- Parameters:
verbose_validate (bool (default: True)) – whether jnml should print verbose information while validating
max_memory (str) – maximum memory the JVM should use while running jnml
return_string (bool) – toggle to enable or disable returning the output of the jnml validation
- Returns:
Either a bool, or a tuple (bool, str): True if jnml ran without errors, false if jnml fails; along with the message returned by jnml
- pyneuroml.pynml.validate_neuroml2_lems_file(nml2_lems_file_name: str, max_memory: str = '400M') bool #
Validate a NeuroML 2 LEMS file using jNeuroML.
Note that this uses jNeuroML and so is aware of the standard NeuroML LEMS definitions.
TODO: allow inclusion of other paths for user-defined LEMS definitions (does the -norun option allow the use of -I?)
- Parameters:
nml2_lems_file_name (str) – name of file to validate
max_memory (str) – memory to use for the Java virtual machine
- Returns:
True if valid, False if invalid
- pyneuroml.pynml.version_info(detailed: bool = False)#
Print version information.
- Parameters:
detailed (bool) – also print information about installed simulation engines
- pyneuroml.pynml.write_lems_file(lems_model: Model, lems_file_name: str, validate: bool = False) None #
Write a lems_model.Model to file using pyLEMS.
- Parameters:
lems_model (lems_model.Model) – LEMS model to write to file
lems_file_name (str) – name of file to write to
validate (bool) – toggle whether written file should be validated
- pyneuroml.pynml.write_neuroml2_file(nml2_doc: NeuroMLDocument, nml2_file_name: str, validate: bool = True, verbose_validate: bool = False, hdf5: bool = False) bool | Tuple[bool, str] | None #
Write a NeuroMLDocument object to a file using libNeuroML.
- Parameters:
nml2_doc (NeuroMLDocument) – NeuroMLDocument object to write to file
nml2_file_name (str) – name of file to write to
validate (bool) – toggle whether the written file should be validated
verbose_validate (bool) – toggle whether the validation should be verbose
hdf5 (bool) – write to HDF5 file