The xolotl class¶

This document describes the "xolotl" class. This is a MATLAB class and the primary way you will interact with your simulations.

Properties¶

Every xolotl object has the following properties listen in this document. To access a property, use dot notation, i.e.:

x.verbosity

You can view all the properties of a xolotl object using the built-in properties command:

properties(xolotl)
% will display a list of properties

`approx_channels`¶

Default	Allowed values	Type
0	0, 1	double

approx_channels determines whether approximations to computing gating functions should be used. Look-up tables and approximations to the exponential function significantly increase computational speed, but decrease accuracy, especially at high temporal resolution in the data.

`closed_loop`¶

Default	Allowed values	Type
true	true, false	logical

closed_loop determines whether initial conditions should be reset before a new simulation. If closed_loop is true, successive simulations will use the current state of the xolotl object (e.g. the end state of the previous simulation if you run integrate twice in a row).

`dt` and `sim_dt`¶

Default	Allowed values	Type
.05	+ve numbers	double

dt value stores the fixed time step for outputs from simulation. Note that this is not the same as sim_dt. This value determines the number of time steps in the output vectors. If dt and sim_dt differ, the simulation vector is interpolated before being output -- useful for running ultra-high definition simulations but not saving all that data.

dt must be a integer multiple of sim_dt. If it is not, an error will be thrown.

`V_clamp`¶

Default	Allowed values	Type
NaN	matrix, vector, scalar	double

When V_clamp is not a NaN, xolotl will assume that you are running the simulation in voltage clamp mode. V_clamp must be either:

a vector as long as x.Children (the # of compartments)
a matrix of size (n_steps,n_compartments) where n_steps is the number of steps in the integration (which is x.t_end/x.sim_dt)

Incorrectly sized V_clamp will throw an error.

You cannot simultaneously inject current and voltage clamp any compartment.

`I_ext`¶

Default	Allowed values	Type
0	matrix, vector, scalar	double

I_ext must be either:

a vector as long as x.Children (the # of compartments)
a matrix of size (n_steps,n_compartments) where n_steps is the number of steps in the integration (which is x.t_end/x.sim_dt)

Incorrectly sized I_ext will throw an error.

You cannot simultaneously inject current and voltage clamp any compartment.

`stochastic_channels`¶

Default	Allowed values	Type
0	0, 1	double

When stochastic_channels is 0, it is assumed that there are sufficiently many channels of every conductance type, and that we can use a deterministic ODE to integrate the gating kinetics of every channel.

When stochastic_channels is 1, the deterministic ODE governing channel gating is replaced by a stochastic equation that is integrated using the Euler-Maruyama following the approximate Langevin formulation. With this flag, the size of the neuron determines the number of channels in every population, and thus determines the noise added onto the deterministic dynamics.

`solver_order`¶

Default	Allowed values	Type
0	0, 4	double

When solver_order is 0, standard solvers are used (exponential Euler). When it is 4, a Runge-Kutta 4th order method is used instead. This method is slower but more accurate.

`t_end`¶

Default	Allowed values	Type
5e3	+ve integers	double

Specify the time, in ms, for which to simulate. Make sure that t_end is an integer multiple of sim_dt

`output_type`¶

Default	Allowed values	Type
0	0,1,2	double

output_type determines if outputs from the integrate function should be separate matrices (0) or organized in a structure (1), or organized in a structure and enable spike-detection in C++ code (2). The 0 option is useful when you only want a few outputs or don't care about lots of variable names. The latter options are useful when it's important to keep all the output data organized. In addition, the 2 option saves memory at the expense of detail.

`temperature` and `temperature_ref`¶

temperature specifies the temperature at which you want to perform simulations. temperature_ref holds the "default" temperature so that $Q_{10}$ values can be used. These values only affect components that are temperature sensitive.

`verbosity`¶

Default	Allowed values	Type
-1	integers	int

verbosity is an integer that controls how verbose xolotl is when running simulations. Use this value to control verbosity from different components of xolotl. verbosity uses a prime basis given by:

Multiple of	Effect
2	hashing, integration, transpiling
3	mex compilation verbosity
5	core C++ integration
7	C++ mechanism verbosity
11	C++ conductance verbosity
13	C++ synapse verbosity
17	MATLAB-level loading

For example, if you wanted the code to be verbose about everything, simple use 0. If you want the code to be verbose about mex compilation and MATLAB-level loading, but nothing else, set verbosity = 17*3

`pref`¶

x.pref contains a structure that contains settings that determine the behaviour of some methods. You can change these settings temporarily by modifying this structure. To make these changes persist across sessions, edit the pref.m file.

You can also add your own data to x.pref, which your functions can use. This is a way to pass metadata and other data along with this model to other functions.

`Children`¶

Children contains a list of all compartments in the current xolotl model. xolotl only allows you to add objects of type "compartment" to it. Therefore, x.Children will give you a list of compartments in the model.

Methods¶

add¶

Syntax

x.add('compartment','comp_name')
x.add(compartment,'comp_name')
x.add('compartment','comp_name',...)
x.add(Compartment,'comp_name')

Description

Adds a cpplab object to a xolotl object. The add method is the most important way you construct models.

x.add('compartment','comp_name') adds a compartment to the xolotl object and names it comp_name.
x.add(compartment,'comp_name') adds a compartment object (a cpplab object) to the xolotl object x and names it comp_name. Note that compartment is a cpplab object sourced from the compartment.hpp C++ file, and can contain children and be extensively modified.
x.add('compartment','comp_name',...) adds a compartment to the xolotl object and names it comp_name. The compartment is then additionally configured using the parameters specified using Name Value syntax.
x.add(Compartment, 'comp_name') adds a pre-defined cpplab object of class "compartment" to the xolotl object and names it comp_name. You cannot pass additional name-value arguments using this syntax.

Technical Details

xolotl.add checks that the compartment being added has a legal name using checkCompartmentName. If so, it calls the add method in the cpplab superclass.

See Also

benchmark¶

Syntax

x.benchmark;

Description

performs a quick benchmarking of a given xolotl model. benchmark first varies the simulation time step, and measures how quickly the model integrates. It then varies t_end, and measures how fast it integrates at a fixed sim_dt.

It should produce a figure that looks something like this (the exact figure will depend on the model and your hardware):

checkCompartmentName¶

Syntax

TF = checkCompartmentName(self,comp_name)

Description

checkCompartmentName is used internally by xolotl to verify that the compartment name you are using is valid and legal. This method is called every time you add a compartment to a xolotl object.

Warning

Do not use checkCompartmentName, as it may be removed in a future release.

See Also

xolotl.add

checkTree¶

Syntax

x.checkTree

Description

This method checks that objects in the xolotl tree make sense and are contained by objects that are allowed to contain them

The following rules are enforced:

Object	Legal container
compartment	xolotl object
mechanism	any
conductance	compartment
synapse	compartment

This method is called in xolotl.transpile() before transpiling takes place

See Also

cleanup¶

Syntax

xolotl.cleanup
x.cleanup

Description

A static method that cleans up all transpiled C++ and compiled binary files.

Warning

Use of this method will trigger a warning every time it is called. You do not need to use this in normal use, but can call this to force a recompile, or to delete old and unused binaries.

See Also

compile¶

Syntax

x.compile

Description

compiles a executable binary form a transpiled C++ file. These are stored in your xolotl directory. xolotl automatically compiles when t needs to. You can turn this

connect¶

Syntax

x.connect('Comp1', 'Comp2')
x.connect('Comp1', 'Comp2',resistivity)
x.connect('Comp1', 'Comp2', SynapseObj)
x.connect('Comp1', 'Comp2', 'path/to/synapse.hpp')
x.connect('Comp1', 'Comp2', 'path/to/synapse.hpp','Parameter',Value...)

Description

Connects two compartments with a synapse.

x.connect('Comp1', 'Comp2') connects two compartments, Comp1 and Comp2, using reciprocal Axial synapses.
x.connect('Comp1', 'Comp2',resistivity) connects two compartments, Comp1 and Comp2, using reciprocal Axial synapses and specifies the axial resistivity.
x.connect('Comp1', 'Comp2', SynapseObj) makes a synapse with presynaptic compartment Comp1 and post-synaptic compartment Comp2 using the synapse object SynapseObj. SynapseObj is a cpplab object that corresponds to a synapse.
x.connect('Comp1', 'Comp2', 'path/to/synapse.hpp') makes a synapse with presynaptic compartment Comp1 and post-synaptic compartment Comp2 using a synapse object that is generated on the fly using the C++ header file specified by 'path/to/synapse.hpp'
x.connect('Comp1', 'Comp2', 'path/to/synapse.hpp','Parameter',Value...) makes a synapse with presynaptic compartment Comp1 and post-synaptic compartment Comp2 using a synapse object that is generated on the fly using the C++ header file specified by 'path/to/synapse.hpp', additionally configuring that object with parameters and values using name-value notation.

The following properties can be specified for most synapses:

Name	PropertyName
Maximal conductance	`gmax`
Reversal potential	`E`
Activation variable	`s`

This method supports tab completion. You should be able to press tab to get a list of compartments to connect.

See Also

xolotl.add

contributingCurrents¶

Syntax

curr_index = xolotl.contributingCurrents(V, I)

Description

This static method calculates the contributions of each current at every point in a voltage race. This is used internally in xolotl.plot to color voltage traces.

where V is a vector of voltages, I is the corresponding matrix of currents

See Also

copy¶

Syntax:

x2 = copy(x);

copies a xolotl object. copy creates an identical copy of a xolotl object that can be manipulated separately. Both copies will use the same binary to integrate, unless you add a new component to one of them.

Warning

Some read-only properties in a xolotl object may not be copied over.
Do not make vectors of xolotl objects, as it may lead to undefined behavior.

See Also

currentscape¶

Syntax

x.currentscape()
norm_currents = x.currentscape()

Description

This method creates a currentscape, or a visualization of the fractional contribution of each current at each point in time

When called with one output, no plot is created, but the raw normalized inward and outward currents are returned.

This method only works with single-compartment models.

You can use manipulate to vary parameters and see this update in real time

x.manipulate_plot_func = {@x.currentscape};
x.manipulate('*gbar');

See Also

download¶

Syntax

x.download;

Description

Downloads a pre-complied binary for this model, if available.

See Also

fI¶

Syntax

data = x.fI()
data = x.fI('Name',value...)

Description

This method computes the f-I (firing-rate vs current) curve of a single compartment model. data is a structure containing the following fields:

I vector of injected currents
f_up firing rates when going up the curve
f_down firing rates when going down the curve
CV_ISI_up coefficient of variation of inter-spike intervals when going up the curve
CV_ISI_down coefficient of variation of inter-spike intervals when going down the curve

The following optional parameters may be specified in name-value syntax:

Name	Allowed Values	Default
I_min	any scalar	- .1
I_max	any scalar	1
n_steps	+ve integer	10
t_end	+ve integers	1e4

See Also

xolotl.integrate

getGatingFunctions¶

Syntax

[m_inf, h_inf, tau_m, tau_h] =  xolotl.getGatingFunctions(conductance)

Description

static method of xolotl that returns function handles that represent the gating and activation functions of a particular conductance.

conductance is a string that specifies a conductance C++ header file. The outputs are function handles that can be evaluated independently. This method is used internally in xolotl.show()

This method supports tab-completion. You should be able to press tab to get a list of conductances you can get the gating function of.

Warning

This may return function handles that are incorrect or malformed for some channels. This is only guaranteed to work when activation functions are simply defined inline in the C++ code.

See Also

xolotl.show

go_to_examples¶

Syntax

xolotl.go_to_examples

Description

A static method that goes to the folder that contains xolotl examples.

See Also

xolotl.run_all_tests

integrate¶

integrates a xolotl model.

Syntax

x.output_type = 0;
V = x.integrate;
I_clamp = x.integrate;
[V, Ca] = x.integrate;
[V, Ca, mech_state] = x.integrate;
[V, Ca, mech_state, I] = x.integrate;
[V, Ca, mech_state, I, syn_state] = x.integrate;

x.output_type = 1;
results = x.integrate;

x.output_type = 2;
results_and_spiketimes = x.integrate;

Description

The outputs of integrate depend on the output_type property of xolotl.

`output_type` value	outputs of `x.integrate`
0 (default)	up to 5 matrices of type double
1	only one output, a structure
2	only one output, a structure

Explanation of outputs

When output_type is 0,

V Voltage trace of every compartment. A matrix of size (nsteps, n_comps)
I_clamp also returned in the first argument, this is the clamping current when a compartment is being voltage clamped. This can be inter-leaved with the voltage of other, non-clamped compartments.
Ca Calcium concentration in every cell and the corresponding E_Ca (reversal potential of Calcium). A matrix of size (nsteps, n_comps)
mech_state a matrix representing every dimension of every mechanism in the tree. This matrix has size (nsteps, NC), where NC depends on the precise controllers used, and is automatically determined.
I the currents of every ion channel type in the model. This is a matrix of size (nsteps, n_cond)

When output_type is 1 or 2, the integration is performed requesting all outputs, and these outputs are organized in a structure and named to match the names of the components in the model.

See Also

loadobj¶

Description

A static method that overloads the built-in loadobj method. This sets local parameters, and is useful when xolotl objects are saved to disk and loaded.

Warning

Do not use this method. This method exists so that MATLAB knows how to load xolotl objects correctly

manipulate¶

Syntax

x.manipulate();
x.manipulate('some*pattern')
x.manipulate({'parameter1','parameter2'})
x.manipulate({'parameter1','parameter2'},mirror_these)
x.manipulate(x.Compartment.Channel)

Description

manipulate is a method that allows you to manipulate some or all parameters in a model while visualizing its behavior.

x.manipulate() manipulates all the parameters in a xolotl model. It wires up sliders to all parameters, and moving these sliders causes the model to integrate, and a plot to update.
x.manipulate('some*pattern') creates sliders only for parameters specified by 'some*pattern'.
x.manipulate({'parameter1','parameter2'}) creates sliders only for the parameters specified in the cell array. Parameters should resolve to valid properties of cpplab objects in the tree.
x.manipulate({'parameter1','parameter2'},mirror_these) creates sliders only for the parameters specified in the cell array. Parameters should resolve to valid properties of cpplab objects in the tree. In addition, parameters specified in mirror_these are also changed to reflect parameters changed in the first argument.
x.manipulate(x.Compartment.Channel) If manipulate is given one argument which is a channel in a compartment, then parameters of that channel can be manipulated, and an additional window will be drawn plotting the activation functions of that channel.

See Also

manipulateConductance¶

This method is used to update the xolotl object every time a slider is moved in the manipulate window. This is used internally in xolotl.manipulate. You should not need to use this by itself.

See Also

manipulateEvaluate¶

This method is used to update the xolotl object every time a slider is moved in the manipulate window. This is used internally in xolotl.manipulate. You should not need to use this by itself.

See Also

xolotl.manipulate

manipulateEvaluateCond¶

This method is used to update the xolotl object every time a slider is moved in the manipulate window. This is used internally in xolotl.manipulate. You should not need to use this by itself.

See Also

plot¶

Syntax

x.plot()
x.plot('comp_name')
x.plot({'comp1','comp2'...})

Description

x.plot makes a plot of voltage and calcium time series of all compartments. The default option is to color the voltage traces by the dominant current at that point using contributingCurrents and to also show the Calcium concentration on the same plot.
x.plot('comp_name') Plots voltage traces from only that compartment.
x.plot({'comp1','comp2'...})) plots voltage traces from these compartments.

If you want to turn off the coloring, or to hide the Calcium concentration, change your preference using:

x.pref.plot_color = false;
x.pref.show_Ca = false;

See Also

plotgbars¶

Syntax

x.plotgbars('compartment_name');
x.plotgbars(axes_handle,'compartment_name');
axes_handle = x.plotgbars(axes_handle,'compartment_name');

Description

Makes a stem plot of conductance densities in a given compartment. If the first argument is a handle to a valid axis, plots will be made there. If no axis handle is given, it will use gca instead. This function can plot onto both Cartesian and polar axes.

See Also

porcupine¶

Syntax

x.porcupine()
data = x.porcupine

Description

x.porcupine makes a plot of voltage and inward and outward currents in a polar plot, wrapped to the burst period of the neuron (assuming it bursts)
data = x.porcupine does not make a plot, but returns a data structure indicating the direction and magnitude of the greatest contribution of each current

See Also

rebase¶

Syntax

x.rebase()

Description

rebase is an internal method that configures some house-keeping settings. rebase is called every time a new xolotl object is created. rebase:

configures the xolotl_folder property
configures the cpp_folder property, which tells xolotl where its C++ files are located
calls the rebase method from the cpplab superclass.

If you move a xolotl object across computers (for example, by saving it to a file and loading it in a different computer), you must call rebase to link it to the C++ files it needs.

See Also

cpplab.rebase

reset¶

Syntax

x.reset()
x.reset('snap_name')

Description

Resets a xolotl object to some default state.

reset called without any arguments resets the model as best as it can -- voltages are set to -60 mV, Calcium in every compartment is set to the internal value, and the gating variables of every conductance are reset.

reset can also be called with a string argument, which is the name of a snapshot previously stored in the model object. Then, reset reconfigures the parameters of the model to match that snapshot. This is useful for working with a model, changing parameters, evolving it, and then coming back to where you started off from.

Here's an example:

% assuming a xolotl object is set up
x.integrate;
x.snapshot('base');
x.set('*gbar') = 1e-3; % turn off all conductances
x.integrate;
% now go back to original state
x.reset('base')

This method supports tab completion. You should be able to press tab and get a list of snapshots that you want to reset to.

% !!! warning reset will not change the values of I_ext and V_clamp

See Also

xolotl.snapshot

rheobase¶

Syntax

options = x.rheobase
I = x.rheobase('PropertyName', PropertyValue, ...)
I = x.rheobase(options)

Description

Finds the minimum injected current required to cause a xolotl model to spike. The model is simulated with increasing amounts of constant injected current until one spike is elicited. This minimum amount of current is called the rheobase. The output I contains the current magnitude needed to cause the model to spike,

If called without arguments and one output, a struct containing fields for all optional arguments, options, is returned.

Otherwise, the first argument should be a xolotl object, and the latter should be either name, value keyword pairs, or a struct to specify options. Options with a NaN value are ignored, and the default is used instead.

Option Name	Default Value	Units
`I_min`	-0.2	nA
`I_max`	4	nA
`SpikeThreshold`	0	mV
`nSpikes`	1
`t_end`	10e3	ms

I_min and I_max define the minimum and maximum of the tested injected current. The SpikeThreshold defines when a spike is said to occur. The voltage must cross this threshold in order for a spike to be counted. You can change the number of spikes to search for via the nSpikes option. This should be used in combination with the t_end option, which defines how long the simulation is. For example, to find the current at which your model spikes at 10 Hz, you could set t_end = 10e3 and nSpikes = 10.

See Also

run_all_tests¶

Syntax

xolotl.run_all_tests

Description

A static method that runs all tests (demos/examples) in xolotl/examples. If you've just installed this, it may be a good idea to run this to make sure everything works.

This method is called during testing, and only if all tests pass is a release published.

setup¶

Syntax

xolotl.setup
x.setup

Description

A static method that allows you to set up compilers on some operating systems. You need to run this only once. If xolotl works, there is no need to run this.

See Also

show¶

Syntax

x.show('path/to/conductance/file')
x.show(x.Compartment)
x.show(x.Compartment.Conductance)
x.show({conductance1, conductance2...})
x.show(x.Compartment.Synapse)

This method displays activation functions and timescales of any conductance or synapse. If you are passing a conductance argument, subsequent calls to show will update the plot, plotting the new activation curves over the old ones, allowing you to compare different channels.

See Also

slice¶

Syntax

% assuming there is a compartment called 'Dendrite'
x.slice('Dendrite',10)

Description

slice partitions a cylindrical compartment into N slices.

The compartment to be sliced must explicitly be a cylindrical section, i.e., it must have a defined length and radius. slice cuts the cylinder along the axis, and connects each slice with Axial synapses. This object can then be treated as a multi-compartment model, and xolotl will integrate it using the Crank-Nicholson scheme reserved for multi-compartment models.

See Also

xolotl.connect

snapshot¶

Syntax

x.snapshot('snap_name')

Description

Saves the current state of a xolotl object for future use. Snapshots act as properties of the xolotl object, so can be reset to anytime, including within other function and scopes.

Warning

Creating two snapshots with the same name will overwrite the first.

Example

% assuming a xolotl object is set up
x.integrate;
x.snapshot('base');
x.set('*gbar') = 1e-3; % turn off all conductances
x.integrate;
% now go back to original state
x.reset('base')

See Also

time¶

Syntax

plot(x.time,x.integrate)

This helper method generates a time vector for your plots in seconds.

See Also

xolotl.integrate

transpile¶

Syntax

x.transpile;

Description

Generate a C++ file that constructs the model, integrates it, and moves parameters and data from MATLAB to C++ and back.

Warning

Manual transpiling is discouraged. xolotl will automatically transpile code for you when needed.

See Also

uninstall¶

Syntax

xolotl.uninstall

Description

Static method of xolotl that uninstalls the currently installed version of xolotl. If xolotl was installed as a MATLAB toolbox, this method deletes the toolbox and removes the toolbox from the path.

See Also

xolotl.update

update¶

Syntax

xolotl.update

Description

Static method of xolotl that updates the currently installed version of xolotl to the latest version. This method needs an active internet connection to work. If xolotl was installed using git, it will attempt to use git to update. If xolotl was installed as a MATLAB toolbox, it will download the latest version of the toolbox and will attempt to replace the installed version with the latest version.

Warning

Updating xolotl if installed as a MATLAB toolbox will overwrite preferences and delete compiled binaries.

See Also

xolotl.uninstall

upload¶

Syntax

x.upload;

Description

Uploads a compiled binary to Github so that others can use it. For this to work, you will need:

write permissions to github.com/sg-s/xolotl
The github CLI (gh) installed and configured

This method will fail silently without any log, and is not meant for public use.

viewCode¶

Syntax

x.viewCode;

Description

view the C++ code generated by xolotl.transpile() that constructs the model and integrates it

See Also

The xolotl class¶

Properties¶

approx_channels¶

closed_loop¶

dt and sim_dt¶

V_clamp¶

I_ext¶

stochastic_channels¶

solver_order¶

t_end¶

output_type¶

temperature and temperature_ref¶

verbosity¶

pref¶

Children¶

Methods¶

add¶

benchmark¶

checkCompartmentName¶

checkTree¶

cleanup¶

compile¶

connect¶

contributingCurrents¶

copy¶

currentscape¶

download¶

fI¶

getGatingFunctions¶

go_to_examples¶

integrate¶

loadobj¶

manipulate¶

manipulateConductance¶

manipulateEvaluate¶

manipulateEvaluateCond¶

plot¶

plotgbars¶

porcupine¶

rebase¶

reset¶

rheobase¶

run_all_tests¶

setup¶

show¶

slice¶

snapshot¶

time¶

transpile¶

uninstall¶

update¶

upload¶

viewCode¶

`approx_channels`¶

`closed_loop`¶

`dt` and `sim_dt`¶

`V_clamp`¶

`I_ext`¶

`stochastic_channels`¶

`solver_order`¶

`t_end`¶

`output_type`¶

`temperature` and `temperature_ref`¶

`verbosity`¶

`pref`¶

`Children`¶