pyneuroml.tune package#

Package for tuning NeuroML based models.

This uses the neurotune package (https://neurotune.readthedocs.io/en/latest/) to provide a framework for tuning NeuroML models using the evolutional computation algorithms from the inspyred (aarongarrett/inspyred) package.

Please note that this is a work in progress. For clarifications, please contact the development team on GitHub.

pyneuroml.tune.NeuroMLTuner module#

A Neurotune based model optimizer for NeuroML models.

This module provides the run_optimisation function that pyNeuroML users can use to optimise their NeuroML models. It uses the evolutionary computation framework provided by Neurotune, which is based on the Inspyred optimisation library’s Evolutionary Computation class inspyred.ec.EvolutionaryComputation:

It currently supports the jNeuroML and Neuron (via jNeuroML) simulators.

This module also provides the pynml-tune command line utility. Please see the output of pynml-tune -h for more information on pynml-tune.

pyneuroml.tune.NeuroMLTuner.run_2stage_optimization(prefix, neuroml_file, target, parameters, max_constraints_1, max_constraints_2, min_constraints_1, min_constraints_2, delta_constraints, weights_1, weights_2, target_data_1, target_data_2, sim_time, dt, population_size_1, population_size_2, max_evaluations_1, max_evaluations_2, num_selected_1, num_selected_2, num_offspring_1, num_offspring_2, mutation_rate, num_elites, simulator, nogui, show_plot_already, seed, known_target_values, save_to_file_1=False, save_to_file_scatter_1=False, save_to_file_hist_1=False, save_to_file_output_1=False, save_to_file_2=False, save_to_file_scatter_2=False, save_to_file_hist_2=False, save_to_file_output_2=False, dry_run=False, extra_report_info={}, num_parallel_evaluations=1, cleanup=True)#

Run a two stage optimisation.

This wraps around the run_optimisation function to allow a two stage optimisation so parameters can be tuned in two sets. For example, it may be useful to first tune the passive membrane properties of a cell, and then move on to the active entities.

In order to mark parameters as being optimised in the first stage, please set their maximum and minimum constraints for the second tuning stage as ‘x’ (instead of providing values). The tuner will then use fitted values from the first tuning for these parameters in the second stage.

Parameters:

  • prefix (str) – prefix for tuning test files

  • neuroml_file (str) – path to main NeuroML file containing the model

  • target (str) – id of target NeuroML component in model (usually Network)

  • parameters (list(str)) – list of parameters to adjust

  • max_constraints_1 (list(float)) – maximum values allowed for parameters for stage 1 tuning

  • min_constraints_1 (list(float)) – minimum values allowed for parameters for stage 1 tuning

  • max_constraints_2 (list(float, 'x')) – maximum values allowed for parameters for stage 2 tuning

  • min_constraints_2 (list(float, 'x') to judge fitness against for stage 1 tuning) – minimum values allowed for parameters for stage 2 tuning

  • delta_constraints (float) – value in [0, 1) that allows re-scaling of the maximum/minimum constraints of values fitted in stage 1 being used for stage 2

  • weights_1 (dict) – weights to assign to each target name/value pair for stage 1 tuning

  • weights_2 (dict) – weights to assign to each target name/value pair for stage 2 tuning

  • target_data_1 (dict) – name/value pairs for properties extracted from data for stage 1 tuning

  • target_data_2 (dict) – name/value pairs for properties extracted from data for stage 2 tuning

  • sim_time (float) – simulation duration

  • dt (float) – simulation timestep

  • population_size_1 (int) – size of population for stage 1 tuning

  • population_size_2 (int) – size of population for stage 2 tuning

  • max_evaluations_1 (int) – number of maximum evaluations for stage 1 tuning

  • max_evaluations_2 (int) – number of maximum evaluations for stage 2 tuning

  • num_selected_1 (int) – number selected in each evolution for stage 1 tuning

  • num_selected_2 (int) – number selected in each evolution for stage 2 tuning

  • num_offspring_1 (int) – number of off sprint in each evolution for stage 1 tuning

  • num_offspring_2 (int) – number of off sprint in each evolution for stage 2 tuning

  • mutation_rate (float) – the mutation rate for each evolution

  • num_elites (int) – number of elites

  • simulator (str) – simulator to use, currently supported values “jNeuroML”, “jNeuroML_NEURON”

  • nogui (bool) – toggle jNeuroML GUI

  • show_plot_already (bool) – whether plots should be shown as generated

  • seed (int) – seed value

  • known_target_values (dict) – known values of target parameters

  • save_to_file_1 (str or bool) – file name to store stage 1 fitness plot to, False not to save

  • save_to_file_scatter_1 (str or bool) – file name to store stage 1 scatter plot to, False to not save

  • save_to_file_hist_1 (str or bool) – file name to store stage 1 histogram plot to , False to not save

  • save_to_file_output_1 (str or bool) – file name to store stage 1 output plot to, False to not save

  • save_to_file_2 (str or bool) – file name to store stage 2 fitness plot to, False not to save

  • save_to_file_scatter_2 (str or bool) – file name to store stage 2 scatter plot to, False to not save

  • save_to_file_hist_2 (str or bool) – file name to store stage 2 histogram plot to , False to not save

  • save_to_file_output_2 (str or bool) – file name to store stage 2 output plot to, False to not save

  • dry_run (bool) – only print setup information, do not run the optimisation

  • extra_report_info (dict) – any extra tag/value pairs to be included in the report

  • num_parallel_evaluations (int) – number of parallel evaluations

  • cleanup (bool) – remove temporary files after completion

Returns:

a report of the optimisation in a dictionary.

pyneuroml.tune.NeuroMLTuner.run_optimisation(**kwargs: Any) → dict | None#

Run an optimisation.

The list of parameters here matches the output of pynml-tune -h:

Parameters:

  • prefix (str) – prefix for tuning test files

  • neuroml_file (str) – path to main NeuroML file containing the model

  • target (str) – id of target NeuroML component in model (usually Network)

  • parameters (list(str)) – list of parameters to adjust

  • max_constraints (list(float)) – maximum values allowed for parameters

  • min_constraints (list(float)) – minimum values allowed for parameters

  • target_data (dict) – name/value pairs for properties extracted from data to judge fitness against

  • weights (dict) – weights to assign to each target name/value pair

  • known_target_values (dict) – known values of target parameters

  • sim_time (float) – simulation duration

  • dt (float) – simulation timestep

  • population_size (int) – size of population for optimisation

  • max_evaluations (int) – number of maximum evaluations

  • num_selected (int) – number selected in each evolution

  • num_offspring (int) – number of off sprint in each evolution

  • mutation_rate (float) – the mutation rate for each evolution

  • num_elites (int) – number of elites

  • seed (int) – seed value

  • simulator (str) – simulator to use, currently supported values “jNeuroML”, “jNeuroML_NEURON”

  • nogui (bool) – toggle jNeuroML GUI

  • show_plot_already (bool) – whether plots should be shown as generated

  • save_to_file (str or bool) – file name to store fitness plot to, False not to save

  • save_to_file_scatter (str or bool) – file name to store scatter plot to, False to not save

  • save_to_file_hist (str or bool) – file name to store histogram plot to , False to not save

  • save_to_file_output (str or bool) – file name to store output plot to, False to not save

  • dry_run (bool) – only print setup information, do not run the optimisation

  • extra_report_info (dict) – any extra tag/value pairs to be included in the report

  • num_parallel_evaluations (int) – number of parallel evaluations

  • cleanup (bool) – remove temporary files after completion

Returns:

a report of the optimisation in a dictionary.

pyneuroml.tune.NeuroMLController module#

A Neurotune controller specific to NeuroML.

Please see https://neurotune.readthedocs.io/en/latest/architecture.html for more information on controllers in Neurotune.

class pyneuroml.tune.NeuroMLController.NeuroMLController(ref, neuroml_file, target, sim_time=1000, dt=0.05, simulator='jNeuroML', generate_dir='./', num_parallel_evaluations=1, cleanup=True)#

Bases: object

A Neurotune controller specific to NeuroML.

Please see https://neurotune.readthedocs.io/en/latest/architecture.html for more information on controllers in Neurotune.

run(candidates, parameters)#

Run simulation for each candidate.

This run method will loop through each candidate and run the simulation corresponding to its parameter values. It will populate an array called traces with the resulting voltage traces for the simulation and return it.

Parameters:

  • candidates (list) – candidate simulations

  • parameters (list) – parameters for simulations

Returns:

list of [time, voltage] values

run_individual(sim_var, show=False, cleanup=None)#

Run an individual simulation.

pyneuroml.tune.NeuroMLController.run_individual(sim_var, reference, neuroml_file, nml_doc, still_included, generate_dir, target, sim_time, dt, simulator, cleanup=True, show=False)#

Run an individual simulation.

The candidate data has been flattened into the sim_var dict. The sim_var dict contains parameter:value key value pairs, which are applied to the model before it is simulated.

Parameters:

  • sim_var

  • reference

  • neuroml_file (str) – path to main NeuroML model file

  • nml_doc (NeuroMLDocument or str) – NeuroMLDocument or its str export

  • still_included

  • generate_dir (str) – directory to generate simulation NeuroML file in

  • target (str) – id of target NeuroML component

  • sim_time (float) – length of simulation

  • dt (float) – simulation time step

  • simulator (str) – simulator to use (“jNeuroML”, “jNeuroML_NEURON”)

  • cleanup (bool) – toggle if temporary files should be removed after simulation

  • show (bool)

Returns:

list of simulation times and voltages at each time: [time, volts]

pyneuroml.tune.NeuroMLSimulation module#

class pyneuroml.tune.NeuroMLSimulation.NeuroMLSimulation(reference, neuroml_file, target, sim_time=1000, dt=0.05, simulator='jNeuroML', generate_dir='./', cleanup=True, nml_doc=None)#

Bases: object

A class for running a single instance of a NeuroML model by generating a LEMS file and using pyNeuroML to run in a chosen simulator

go()#

Run the simulation.

show()#

Plot the result of the simulation once it’s been intialized using matplotlib.