PSICS - the Parallel Stochastic Ion Channel Simulator
previous ←   → next
Under development
Please let us know of errors, unclear text or if you have suggestions form improvements:

Run control - the PSICSMaster file

The master file is the first file read by PSICS and specifies a single run or sequence of runs for the simulator. Some parameters are set within this file itself, but most of the specification comes from other objects that are referred to by the master file. It links four other essential model files: morphology, environment, properties and access. In each case, the attribute in the master file should be set to the id of the target object. The timestep and runTime are also set at the start of the file and, optionally, the numerical method to be used. This can be set either with the method attribute or via explicitly setting the temporal difference weighting, tdWeighting. See the numerical methods section of the user guide for details.

The elements of the master object are all optional and either extend the scope of the calculation, as with parameter sweeps, or give greater control over aspects of the calculation such as morphology discretization or the threshold for treating channels stochastically. The use of the main elements is described first followed by the complete reference for all the master file attributes and elements.

Finding components

By default, PSICS will look in the current folder for the other components needed for the full model, but it can be useful to build up standard libraries elsewhere for frequently used components such as ion channel models. In this case, embedded ModelFolder elements are needed with the path attribute set to relative or absolute path of the library folder. One ModelFolder element is required for each search path. So, for example, if your morphology files are stored in /home/abc/psics/lib/morph then you could add the line
<ModelFolder path="/home/abc/psics/lib/morph"/>
Inside a model specification file. Then, wherever it is saved, you could refer to channels by their id from that file or from other files that it references without needing local copies of the channel definitions themselves.

The path can also be a relative link, such as "../channels" (indicating the folder called "channels" under in the parent of the model folder). This can be used for example when developing a series of related models in different folders. By using relative paths for the library components, the models are more portable: you can package up and distribute the whole folder tree and expect the models to work straight away for other users on other systems. If you use absolute paths, then other users will have to download the library as well as a particular model and set the ModelFolder path to wherever they have put the library models.

Multiple runs and parameter sweeps

By default, the master file defines a single run of the calculation. There are several options to define multiple runs. The simplest is to set the repeats attribute to a number greater than one. This causes multiple stochastic instances to be run. The output data all go in the same file, just adding extra columns for each run.

Parameter sweeps, where the model is run repeatedly systematically changing one parameter, are defined with an embedded RunSet object. If there is an embedded RunSet then there will always be multiple output files, so it has to specify what names should be used via the filepattern attribute which shows how to generate the file names. It is just a template for the file name containing a "$" sign. For each file the "$" will be replaced by the current value of the parameter being changed in the sweep.

The other required attributes of a RunSet are a way to identify the parameter being changed, and the values it can take. The first is a standard parameter reference, in the form "component_id:attribute_name" where component_id is the id of the object that contains the target parameter, and attribute_name is its name within that object. The values should be entered as a dimensional array, such as "[2, 4, 8]ms". This extends the normal units convention for input quantities to allow vectors where all elements are expressed in the same units.

It is also possible to vary two parameters together by setting the covary and covalues attributes. This do not do a grid of models, but rather changes the covary target each time the vary target is changed. It is useful where you need a balancing change for the original variation, such as studying the effect of single channel conductance on the cell without changing the total available conductance. In this case each time the single channel conductance is increased, the number density should be decreased by the corresponding factor, so, for example if values array for the conductance was "[10, 20, 40]pS", the covalues array for the density could be "[10, 5, 2.5]per_um2".

Multiple commands

When a parameter is varied via the RunSet a different set of results is generated for each value, which is normally appropriate of the model itself has been changed. But when the target parameter only changes the stimulation, not the model itself, it can be more convenient to combine it all within a single run. This is achieved via the CommandSet element. Like the RunSet it has vary and values attributes, but the vary target must be part of a stimulation definition. Internally, the command set causes the target stimulation command to be multiplied up into a set of commands in the preprocessing stages just as if you had manually created a set of commands within the stimulus definition file.

N.B., at present, a CommandSet can only appear within a RunSet object even if you only want one run. The workaround in this case is to create a dummy RunSet with only one value, such as, "vary='timeStep' values='[100]ms'".

Discretization control

Various optional elements control the discretization of the model. The most important is the StructureDiscretization that sets the baseElementSize for the compartments. See the model processing section of the user guide for details of the structure discretization. It is also possible to set the channel table increment via the ChannelDiscretization element, though this is likely only to be useful for performance or accuracy tests.


A typical PSICS model involves both stochastic and continuous calculation of channels according to how many channels of a given type there are on a compartment. The dividing line above which the continuous calculation is used can be set on a cell-wide basis via the stochThreshold attribute of the master file. For finer grained control, it can be set on a channel by channel basis with embedded ChannelStochThreshold elements.


As with all stand-alone models, the PSICSMaster component has an info attribute which is intended for a brief (< 1 line) description of the model, and supports embedded About elements to contain more extended paragraphs of text intended for the user or reader of the model. Any text present in the info attribute or About elements is incorporated in the results summary page that is generated when the model is run, and will therefore be readily accessible to anyone viewing the output of the model.


As well as textual information about the model it is possible to define default views of the results via an embedded ViewConfig object. This is not strictly part of the model specification, but is included in the master file because it typically needs to refer to the output files by name. Details of the ViewConfig format are not included below but are presented separately in the Visualization section.


Overall specification and control of a calcluation

Standalone model

This is the first object read when the calculation starts. It says where to find model components, what simulation to perform and what to do with the results.


morphologyidentifier referenceThe identifier of the cell morphology to be used (CellMorphology) yes
propertiesidentifier referenceThe identifier of the channel distribution to be used (CellProperties) yes
environmentidentifier referenceThe identifier of the cell environment to be used (CellEnvironment) yes
accessidentifier referenceThe identifier of the access configuration to be used (Access)
activityidentifier referenceThe identifier of the activity (incoming spikes etc) configuration to be used, if any (Activity)
methodone of the possible valuesNumerical method to be used (defaults to weighted Crank-Nicolson)CRANK_NICOLSON, IMPLICIT_EULER, FORWARD_EULER, WCN_0.51, WCN_0.6
timeStepFloating point valueTimestep for fixed step calculationsms(0.001, 1)
runTimeFloating point valueTime to run the model forms(1, 1000)
tdWeightingFloating point valueExplict control of temporal differencing as an alternative to selecting one of the fixed methodsnone[0., 1.]
startPotentialFloating point valuePotential to initialize the cell to at the start of the calculationmV(-80, -50)
maxPointsWhole numberMaximum number of compartments allowed. If the discretization generates more points, the simulation will be abandoned.(10, 100000)
repeatsWhole numberNumber of repeates of the same recording(1,100)
stochThresholdWhole numberThe threshold beyond which channel calculations use the ensemble limit. This can be overridden for particular channels with ChannelStochThreshold blocks.(10, 1000)
quickChannelsFlagUse quicker, compartment based method for allocating channels instead of giving them all exact 3D locations"true" or "yes", "false" or "no"
oneByOneFlagAdvance every channel individually. This is much slower in general and is intended to provide comparisons with results using the normal approximations. Please let us know if you find a case that shows statistically significant differences."true" or "yes", "false" or "no"
squareCapsFlagIf set, model segments with flat (rather than hemispherical) ends and treat minor points as originating from the center of the parent point, not the surface. This is mainly useful for exact comparisons with results from models that make this assumption."true" or "yes", "false" or "no"
infoMetadataBrief description of the model


Element typeRole
ChannelStochThresholdPer-channel stochasticity thresholds. Allows some channel types to be treated stochastically against a continuous background from the rest.
ModelFolderPaths to search for models
StructureDiscretizationStructure discretization parameters
ChannelDiscretizationChannel discretization parameters
MorphologySourceImports of external morphologies
RunSetOptional mult-run specifications
ViewConfigDefault views of the results
AboutExtended textual information about the model


A folder to include in the search path for model components

within: PSICSRun

By default, PSICS looks in the current folder for components referenced from the mode.ModelFolder specify additional serach paths where other components can be found. The path should be expressed with forward slashes for separators, and can be either absolute, such as '/home/PSICS/models/CaChannels', or relative to the main model file, such as '../models/CaChannels' where '..' stands for the parent folder of the current directory.


paththe path to a folder to search for modelsSearch pathyes

Elements - No child elements are allowed


Per-channel stochasticity threshold

within: PSICSRun

This provides finer-grained control of the stochastic calculation than the default stochThreshold specification. Any thresholds provided this way apply to the specified channel type across the entire structure.


channelidentifier referenceThe channel type (KSChannel) yes
thresholdWhole numberThe threshold beyond which the calculationfor this channel type uses the ensemble limit(10, 1000)

Elements - No child elements are allowed


Discratization parameters for channels

within: PSICSRun

Channel transition rates are tabulated for use in the calculation. A discretization specification can be used to change the default table range and step. It is unlikely to be useful to set this except for detailed performance or accuracy tests.


vMinFloating point valueMinimum tabulated potentialmV(-100., -70.0)
vMaxFloating point valueMaximum tabulated potentialmV(20., -60.0)
deltaVFloating point valueVoltage step for linearization of channel tablesmV(0.3, 3.0)

Elements - No child elements are allowed


Compartmentalization options for the morphology

within: PSICSRun

The baseElementSize is the main attribute for controlling how the cell morphology is compartmentalized. The discretization algorithm is detailed in the 'process' section of the user guide.The merge flag allow the discretization algorithm to generate exactly the same compartmentalizations as certain legacy test cases, but are unlikely to be useful for new models.


baseElementSizeFloating point valueDefault element size. For a segment of radius r, the resulting length, l, is r^(3/2) *, 100)
mergeFlagIf merge is set to false, then it will use at least one compartment for each point in the original structure: ie, nearby points will not be combined into a single compartment"true" or "yes", "false" or "no"

Elements - No child elements are allowed


multiple run configuration

within: PSICSRun

Specification of a set of runs varying either one parameter on its own, or two parameters together. If one parameter is changed, only the 'vary', 'values', and 'filepattern' attributes are needed. If a second parameter is changed, its name should be set with the 'covary' attrubute, and values array as 'covalues'.


mergeFlagMerge the output files into a single file."true" or "yes", "false" or "no"
valuesArray of floating point valuesThe values to be taken by the variable parameter on separate runs
They should be expressed as, fpr example, '[1.5, 2, 3.5]ms' where the same units apply to all values. The units should match the dimensions of the quantity to be varied.
matching(0.001, 5000)yes
covaluesArray of floating point valuesCo-varied values, if any
If set, this should have the same length as the values array
matching(0.001, 5000)yes
varyplain textName of the parameter to vary. If this is in a different component (different file), it should be prefixed with the id of the id of the component
covaryplain textOptional parameter to vary in sync with the parameter specified by 'vary'
filepatternplain textTemplate for output file set of files is written for each value of the varied quantity.


Element typeRole
CommandSetcommand families


family of command profiles differing in one parameter

within: RunSet

Specification of a set of runs using modifications of the same command profile


valuesArray of floating point valuesThe values to be taken by the variable parameter on separate runs
They should be expressed as, for example, '[1.5, 2, 3.5]ms' where the same units apply to all values and should match the dimensions of the varied quantity
varyplain textName of the parameter to vary expressed as in the form id:paramname where the id is the identifier of the particular commmand element and the paramname is the name if the parameter within that component

Elements - No child elements are allowed


Textual infomation about a model

within: PSICSRun, KSChannel

An About block can be used to contain a paragraph of text asociated with a model. A model can include any number of About blocks.



Elements - No child elements are allowed

previous ←   → next