Routine Name: abort Description: Cleanly interrupts simulation in progress. Usage: abort Example: abort Notes:See also: stop , step
Routine Name: abs
Description: Returns absolute value of number.
Usage: positive-number = abs any-number
positive-number returned as absolute value of
any_number
any-number number (float or int) for which to
compute absolute value
Example: genesis > echo { abs -22 }
22
genesis > int x
genesis > float y
genesis > y = -33.333
genesis > echo { abs {y} }
33.333000183
genesis > x = {abs {y}}
genesis > echo {x}
33
Notes:
Routine Name: acos
Description: Returns angle (in radians) corresponding to given cosine.
Usage: angle-in-radians = {acos cosine}
Example: genesis > echo { acos 1 }
0
genesis > float degrees_per_radian = 360 / (2 * 3.1415926)
genesis > echo {{ acos 0.707} * degrees_per_radian}
45.00865245
Notes:
See also:
cos
Routine Name: addaction
Description: Adds a named action to the action table used by element types.
Usage: addaction name action_func
addaction name id-number
Example: addaction NEWACTION 10
addaction K_squid_hh K_squid_hh_SET
(see Scripts/tutorials/hhchan_K.g)
Notes: Each object in a simulation is capable of performing one or
more "actions". An action can be described as an operation
that an object performs on its data. Actions are defined
within compiled functions which are attached to each object.
(You can display a list of actions which an object can perform
and the function(s) which perform using the showobject
routine.) For instance, objects of type compartment can
perform the actions:
RESTORE2 SAVE2 SET CHECK RESET PROCESS INIT
(The actions are actually performed by an underlying C
function associated with the compartment element type.)
You use the addaction routine to add the named action to the
action table. Actions are passed to the handler routines
associated with each type of GENESIS object. The handler is
expected to perform the necessary actions when a given action
type is passed to it by the simulator.
For the most part this routine will only be used when adding
new object types which require use of additional (non-default)
actions already known to GENESIS.
You use the addaction routine to define new actions to be used
by elements. There are a number of predefined actions
which are typically used by objects. PROCESS is one of them.
New actions can be added in any object. Use the 'addaction'
routine in the object definition script to inform the
simulator of the new action. The case number assigned to new
actions is relatively arbitrary as long as it does not
conflict with the case numbers of other actions defined in the
object. (you should get a compiler error if there is a
conflict).
When used as a GENESIS command, addaction is primarily used
in the construction of extended objects. It is also used as
a library intialization command during the compilation of
GENESIS libraries.
See also:
object ,
Extended Objects, Defining New
Objects and Commands (
NewObjects )
Routine Name: addalias
Description: Associates alternative name with existing GENESIS command.
Usage: addalias alias-name command-name
Example: addalias set setfield
Notes: You may put a number of addalias statements in a file and
use an include statement in the .simrc file to include the
file when GENESIS is started.
See also:
addescape
Command Name: addclass
Description: Adds a new class to list of currently recognized GENESIS
element classes.
Adds a new class tag to a given element.
Usage: addclass [element] class-name
Example: addclass /sine device
Notes: The addclass routine adds a class tag to a given element
identifying it as belonging to the given class. Omitting
the element defines a class name without assigning any
element to the class. (This is a deprecated usage which
may not be supported in future releases).
Objects can be grouped into named classes. This
grouping can be used to facilitate the specification of
operations to be performed on functionally related
elements. See scheduling (e.g., the addtask
routine, and Schedules) for an example of class use.
Classes are simply used for grouping of related
elements and do not alter the element functionality in
any way. Classes in GENESIS don't carry the full
connotations of classes within a true object-oriented
programming environment. They are simply convenient
ways of creating named groupings to which objects can be
assigned.
See also: listclasses,
deleteclass ,
showobject ,
Extended
Routine Name: addescape
Description: Adds an escape-key macro binding.
Usage: addescape esc_sequence command-string [-execute] [-id string]
esc_sequence actual keystrokes (or representation)
to associate with escape action
command-string string to insert in place when escape
sequence is issued (should be in
quotation marks if it contains blank
spaces)
-execute flag to have command-string executed
when escape sequence is called
(this puts the field EXEC in the
listescape table; if -exec is left
out, default is REPLACE, i.e., insert
command-string, unexecuted, in command
line at point escape sequence is
issued)
-id string label for this escape sequence, used
typically to identify the escape
sequence in user-understandable
language
Example: genesis > addescape [15~ "/xproto" -id "F5"
genesis > le <F5>
[line changes to:]
genesis > le /xproto
/draw
[associate command string 'echo "I am not a duck"' with key
stroke sequence escape-a:]
genesis > addescape a "echo I am not a duck" -execute
genesis > <escape-a>
I am not a duck
[from escapelist.g file, included in startup:]
addescape [A <^P> -id "up arrow"
addescape [B <^N> -id "down arrow"
addescape [C <^F> -id "right arrow"
addescape [D <^H> -id "left arrow"
addescape [1~ "execute movebol" -exec -id Find
addescape [2~ <^I> -id "Insert Here"
addescape [3~ <^D> -id Remove
addescape [11~ stop -exec -id F1
addescape [17~ "status -process" -exec -id F6
addescape [18~ status -exec -id F7
addescape [28~ "commands | more" -exec -id Help
addescape [29~ step<CR> -id Do
Notes: You use the addescape routine to create escape-key macros for
commonly used command lines. Here, the key is the key you
will depress after the escape key, and command-string is the
string which will be substituted into the SLI interpreter when
the the escape sequence occurs. (When the key is preceded by
escape -- ctrl [ -- during keyboard input, the command-string
is substituted.)
A standard set of escape-key macros is specified during
startup through the file escapelist.g.
See also:
listescape
Routine Name: addfield
Description: Add an extended (user-defined) field to an element.
Usage: addfield [element] field-name [-indirect element field]
[-description text]
field-name name of the new field to be added to element
-indirect make the field-name an alias for the a field
in another element
-description add a descriptive text string
Example: addfield /cell/soma area -d "Area of the compartment"
Notes: If you have a compartment, /soma, with a hh_channel
/soma/hh_Na, then
addfield /soma Gk -indirect hh_Na Gk
will add a field to /soma called Gk which is an alias for
/soma/hh_na Gk. Note that the path in the -indirect option
is relative to the element to which you are adding the
field. The indirect element path can also be an absolute
path.
See also:
deletefield
Routine Name: addforwmsg
Description: Forwards an incoming message to one element to another
element.
Usage: addforwmsg source-element message-number destination-element
source-element element from which the message will be
forwarded
msg-number number (index) of message in message list
(messages are numbered from 0 up)
destination-element
element to which the message will be forwarded
Notes: The destination element must accept messages of the same
name and with the same number of data slots as the message
being forwarded.
See also:
deleteforwmsg ,
showmsg ,
Extended
Routine Name: addglobal
Description: Declares a global variable of the specified type, allowing the
name of the global variable to be held in a string variable.
Usage: addglobal type name [value]
type must be one of int, float or str.
Example:
genesis > str name = "foo"
genesis > addglobal float {name} 5.55
genesis > listglobals
float foo = 5.55
str name = "foo"
(plus many others)
Notes:
Often it is useful to use a string variable name to hold the name of a
global variable. For example, one may want to pass the name of a global
variable to a function that declares a global variable, or that sets or
returns its value. However, normal GENESIS syntax for declarations and
assignments does not permit a variable name to be specified by a string
variable. The routines addglobal, getglobal, and setglobal are designed
to overcome this limitation.
Note that if addglobal is used within a function definition, the declared
variable will nevertheless be global, and not local to the function.
See also:
Variables ,
setglobal ,
getglobal ,
listglobals
Routine Name: addmsg
Description: Establishes message links between two elements.
Usage: addmsg source-element dest-delement msg-type [msg-fields]
Example: addmsg /cell/dend /cell/soma RAXIAL Ra previous_state
addmsg /cell/soma /cell/dend AXIAL previous_state
addmsg /cell/soma /graphs/Vmgraph PLOT Vm *voltage *red
Notes: addmsg sets up communication links to pass information
between elements. Messages flow along message links created
by the addmsg routine each time a simulation timestep is
executed.
For example, an asymmetric compartment connected to another
asymmetric compartment needs to send both its axial
resistance, Ra, and its membrane potential at the previous
simulation step to the second compartment. In order to update
its state, it needs to receive the second compartment's
previous membrane potential.
See also:
deletemsg ,
showmsg ,
getmsg , gen3dmsg, dd3dmsg
Routine Name: addmsgdef
Description: Adds a new message type allowing messages of that type
to be added to the element.
Usage: addmsgdef element message-name [message-arguments...]
-type message-type
element element for which to add the message
definition
message-name name of the message (the convention is
to use all upper case)
messages-arguments
zero or more names for the data slots
of the message
-type option to set the message type number
explicitly
Notes: It is normally unnecessary use the -type option as
addmsgdef assigns an unused message type number
automatically. -type should be necessary only for
specifying active messages.
See also:
deletemsgdef ,
showobject ,
Extended
Routine Name: addobject
Description: Adds a new object to GENESIS defined by the fields, message,
actions and class tags of the given element. The element
is removed and used as a prototype for initial field values
of new elements created from the new object.
Usage: addobject object-name element -author author-info
-description descriptive-text ...
object-name the new name for the object
element element from which to create the new object
-author Information about the author of the object
-description A description of the object; multiple
arguments to -description may be given
resulting in multiple lines of descriptive
text
Notes: The object name must not be the same as an existing
object. Currently, there is no corresponding
deleteobject command.
See also:
listobjects ,
showobject ,
Extended
Routine Name: addtask
Description: Adds a simulation event to the simulation schedule.
Usage: addtask function [arguments...]
function a compiled C function to be executed at each
step in the simulation phase according to its
order in the schedule table (almost always,
this fucntion will be "Simulate")
arguments arguments for the specified function
[practically speaking this means:]
addtask Simulate path -action action-name
path path specification of elements affected
(typically a wildcard path designation
with a CLASS-conditioned selection to
identify all elements of a specific type)
action-name action to perform on specified elements
(usually INIT or PROCESS; must be a valid
action, as determined by listactions)
Example:
addtask Simulate /##[CLASS=myclass] -action PROCESS
addtask myfunction myargs
from startup/schedule.g:]
deletetasks
addtask Simulate /##[CLASS=buffer] -action INIT
addtask Simulate /##[CLASS=segment] -action INIT
addtask Simulate /##[CLASS=device] -action INIT
addtask Simulate /##[CLASS=buffer] -action PROCESS
addtask Simulate /##[CLASS=projection] -action PROCESS
addtask Simulate /##[CLASS=spiking] -action PROCESS
addtask Simulate /##[CLASS=gate] -action PROCESS
addtask Simulate /##[CLASS=segment][CLASS!=membrane][CLASS!=gate]\
[CLASS!=concentration][CLASS!=concbuffer] -action PROCESS
addtask Simulate /##[CLASS=membrane] -action PROCESS
addtask Simulate /##[CLASS=hsolver] -action PROCESS
addtask Simulate /##[CLASS=concentration] -action PROCESS
addtask Simulate /##[CLASS=concbuffer] -action PROCESS
addtask Simulate /##[CLASS=device] -action PROCESS
addtask Simulate /##[CLASS=output] -action PROCESS
resched
Notes: GENESIS provides a default simulation schedule that handles
most simulation configurations (see above), but for your
simulation you may need to specify a different order in which
the simulator should process elements in the simulation. You
use addtask to enter simulation events to the simulation
schedule.
You must be careful to avoid multiple references to elements
with the same action. For instance, given a model containing
the six elements /test[1-6], the following schedule would be
an invalid specification since it would cause test[1] to be
invoked twice on each simulation step.
addtask Simulate /test[1] -action PROCESS
addtask Simulate /test[1-6] -action PROCESS
With broad path specifications, it is easy to accidentally
include multiple reference. However, you can check for these
occurrences by running the check routine. In the above case,
calling check after entering the above specifications would
generate the following message:
** Error - '/test[1]' multiply invoked
with action 'PROCESS'. Check task [2]
Task [2] refers to the second addtask command. This
command was responsible for the conflict.
Alternately, not scheduling all enabled elements (see enable)
for simulation is detected as an error by the check routine.
For instance, given the model of six elements used above, you
might define a schedule with one addtask call as follows:
addtask Simulate /test[1-5] -action PROCESS
Running check would produce the following message:
* Warning - '/test[6]' is not scheduled for simulation.
A valid schedule for this set of elements might be:
addtask Simulate /test[1] -action PROCESS
addtask Simulate /test[2-6] -action PROCESS
or
addtask Simulate /test[1-6] -action PROCESS
See also: <href id="Schedules">, <href id="resched">,
<href id="deletetasks">, <href id="showsched">, <href id="check">
Routine Name: argc
Description: Returns argument count (number of arguments passed to a
function).
Usage: int-value = {argc}
Example: if ({argc} > 3)
echo usage: foo a b c
return
end
Notes:
See also:
argc ,
argv ,
getarg ,
printargs
Routine Name: arglist
Description: Converts list of items into an argument list.
Usage: arglist string
Example:
genesis > str s ="a b c d"
genesis > echo { getarg {arglist {s}} -arg 3}
c
str s
str thingys = "foo bar baz"
foreach s ({arglist {thingys}})
echo {s}
end
Notes: In each of these examples, a single string consisting of
items separated by spaces has been converted into a list.
See also:
argc ,
argv ,
getarg ,
printargs
Routine Name: argv
Description: An array of strings containing the arguments passed to
a function.
Usage: argv position-number
Example:
function echoargs
int i
echo "Number of arguments = "{argc}
for(i=1;i<= {argc};i=i+1)
echo {argv {i}}
end
end
genesis > echoargs foo 5 1.23
Number of arguments = 3
foo
5
1.23
Notes: As with C, indices of argv should start with 1.
See also:
argc ,
arglist ,
getarg ,
printargs
Routine Name: asciidata
Description:
Converts a FMT1 formatted binary file (as produced by the
disk_out object, for example) to ASCII. Output is to stdout.
Usage:
asciidata file-name -time t -cell cell -gain g -old -xy -skip n -header
One of options -cell, -time or -header must be given.
Example: (using the horiz_disk file from Scripts/orient_tut)
genesis > asciidata horiz_disk -header
FMT1
start time = 0.000000e+00
time step = 1.000000e-05
cellnum = 25
data type = 4
data size = 4
genesis > asciidata horiz_disk -cell 24 | more
-7.006086e-02
-7.012120e-02
.
.
-7.597300e-02
-7.596859e-02
//(provides Vm at each time step; adding -xy option gives t and Vm)
genesis > asciidata horiz_disk -time 1.e-4 -xy
0 -0.0706427
1 -0.0706427
2 -0.0706427
.
.
23 -0.0706427
24 -0.0706427
//(cell number and Vm for each of the 25 cells)
See also:
disk_out
Routine Name: asin
Description: Returns angle (in radians) corresponding to given sine.
Usage: angle-in-radians = {asin sine}
Example: genesis > echo {{ asin 0.5 }*(180/3.1415926)}
30.00000135
Notes:
See also:
sin
Routine Name: atan
Description: Returns angle (in radians) corresponding to given tangent.
Usage: angle-in-radians = {atan tangent}
Example: genesis > echo { atan 0.876 }
Notes:
See also:
tan
Routine Name: call
Description: Allows an element to execute the function associated with the
named action.
Usage: call path action [args...] -parent -virtual
-parent call the action on the element using the parent object
of the current object context as the new object
context
-virtual call the action on the element using the element's
object as the object context during the action.
Example: call /form/graph RESET
call /form/graph/plot ADDPTS {x} {y}
Notes: The call routine allows the user to send an action to an
element's handler routine (outside of the simulation cycle).
An action executes in the context of a specific object which
is either the element's object or some base object for the
element. The object context determines what fields,
actions, messages and classes are known and accessibility of
fields during execution of the action function. Without any
other options to call, the object context during the call is
the element's object or the current object context if the
element is already executing an action. The -parent and
-virtual options modify this. These options are to be used
when an action is called within the function definition of
an action to be added with the addaction command. They have
no affect when used outside an action function.
See also:
addaction ,
Extended
Routine Name: callfunc
Description: Allows you to call a function whose name is stored in a
string variable.
Usage: callfunc funcname ...
Example: genesis > str foo = "echo"
genesis > callfunc {foo} a b c
a b c
Notes:
See also:
Routine Name: cd
Description: Changes current working operating system directory.
Usage: cd directory
Example: genesis > cd /usr/genesis/Scripts/neuron
Notes: This is a GENESIS implementation of the operating system
command cd, to assure that any change you make in the working
directory is known to GENESIS. (If you just issued a normal
cd command directly, via "sh cd" for instance, the
change in the current working directory would last only as
long as the subshell created to enact the command, and future
actions in GENESIS would not recognize a change. The GENESIS
implementation of cd fixes this.)
See also:
sh
Routine Name: ce
Description: Changes the current working element.
Usage: ce element-path
element-path complete or relative pathname of element to
make current working element; can also be
operating-system style hierarchy
abbreviations, such as . (current),
.. (element above current)
Example: ce /
ce /proto
ce output
ce ..
genesis > create compartment foo
genesis > ce ^
genesis > pwe
/foo
Notes: All GENESIS elements exist in a hierarchy. The root element
lives at the top of the tree (designated by /) and child
elements are created beneath the root. You use the ce routine
to move about the tree (much as you can use the "cd" command
to move about the operating system file system).
If the element-path specified in a ce call starts with a /
then the path is assumed to be an absolute path from the root
of the element hierarchy. If the first character of the path
specified is not a / then the path is assumed to be relative
to the current working element.
See also:
pwe ,
le ,
pushe ,
pope ,
stack
Routine Name: cellsheet
Description: Copies prototype cells into a 3-D sheet specified by
coordinates in a file.
Usage: cellsheet prototype dest filename [-orient][-curve]
[-randomise x y z] [-twirl theta]
prototype existing cell to copy to create cells in the
sheet (prototype is not changed by the
routine; all operations are done on the
copies)
destination element to become parent of all cells in sheet
filename file defining position and orientation of
cells (ascii file with 3 numbers for each
coordinate (cartesian only), followed by 3
coordinates for the normal vector to the
surface of the sheet at that point; this
vector does not have to be normalised; each
set of 6 numbers should be on different lines)
-orient reorients the cell to be normal to the local
region of the sheet
-curve distorts copies of prototype cell to follow
curvature of sheet of cells; the lengths (and
electrical properties) of the cell are not
changed (this option assumes that length of
each compartment is less than the radius of
curvature of the surface; also, the sampling
density over the cell sheet should be high
enough that the spacing between the points is
smaller than the length of each compartment;
does not attempt to curve compartments where
the angle of rotation would be less than 10
degrees, or more than 60)
-randomise x y z
randomises the coordinates of copied cells by
the specified factors in x, y and z before the
orienting/positioning/curving steps
(randomisation involves finding length of each
compartment in each direction, scaling it by a
random number within the range of the
specified factor, and adding it to the
original; e.g., a factor of 1 would permit a
change of up to the original length of the
compartment; the electrical properties and
channel conductances in each compartment are
scaled according to the total length change)
-twirl theta rotates the finally positioned cell about its
normal by a random angle from 0 to theta
degrees
Example:
include protodefs.g // copied from Scripts/tutorials
readcell cell.p /library/cell // use cell.p from Scripts/tutorials
plane planepoints 400e-6 400e-6 100e-6 100e-6 -normal
egg eggpoints 400e-6 400e-6 400e-6 100e-6 -normal
create neutral /planenet
create neutral /eggnet
rotcoord /library/cell {-3.1415927/2} -y // point dendrite up along z-axis
cellsheet /library/cell /planenet planepoints -orient
cellsheet /library/cell /eggnet eggpoints -orient
showfield /planenet/cell[]/dend x y z
Notes: Creates a sheet of cells by copying from a prototype, and
placing them at 3-D positions specified by an ascii file. A
number of options permit the cells to be oriented, conformed
to the curvature of the surface, randomised, and rotated, in
order to make the geometry more natural.
In the example above, the prototype cell had the apical
dendrite pointing along the x-axis, so rotcoord was used to
rotate it 90 degrees about the y-axis to point outward along
the z-axis. Then, cellsheet was used, first on a file
containing points in a plane, and then on a file containing
points distributed over the surface of an ovoid. In both
cases, the orient option was used to point the dendrite along
the outward normal to the surface.
Routine Name: check
Description: Checks various aspects of simulation to catch specification
errors.
Usage: check
Example: check
genesis > setfield /soma Rm -5000 Cm 0
genesis > check
** Error - Compartment : Invalid Rm. '/soma'
** Error - Compartment : Invalid Cm. '/soma'
Notes: The check routine sends the CHECK action to the handlers for
all enabled elements. The CHECK action should verify the
consistency and well being of the element and report any
problems with it to the user. (Each element which supports
self-checking will be invoked with the CHECK action and report
any problems.)
In the example above, the CHECK action of the compartment
checks to be sure that the Rm and Cm fields are set to
positive values, and running a check prints an error message.
See also:
addtask ,
setclock ,
enable ,
reset
Routine Name: chr
Description: Returns ASCII character specified by number code.
Usage: character = {chr ASCII-number}
Example: genesis > echo { chr 64 }
@
genesis > echo {chr 65}
A
genesis > echo {chr 97}
a
Notes:
Routine Name: clearerrors
Description: Resets error count to 0.
Usage: clearerrors
Example: clearerrors
Notes: When the number of errors reaches its maximum value (default:
10 syntax errors or 20 warnings) the current action is
interrupted, the simulator goes back to the command line, and
the errors are reset. The clearerrors routine can be used to
reset the error count before this occurs, allowing a
simulation to continue running despite errors.
See also:
maxerrors ,
maxwarnings
Routine Name: closefile
Description: Closes an ASCII file opened with the openfile routine.
Usage: closefile filename
Example: openfile myfile w
writefile myfile 10 20 30
closefile myfile
Notes: When you open a file using openfile, you work on a copy of
the file. The closefile routine writes your changes back
into the actual file and eliminates it from the list of open
files. (Closefile is automatically called for all opened
files when you exit from GENESIS).
See also:
openfile ,
listfiles ,
writefile
Converting GENESIS 1.4 Scripts to GENESIS 2.0
What Does Convert Do?
GENESIS 2.0 includes a major revision of command format and command
option naming, script language syntax changes and changes in various
GENESIS features. The convert program converts GENESIS 1.4 compatible
scripts to use GENESIS 2.0 syntax, commands and features. Some
features have changed dramatically enough that an automatic conversion
to the new features is not feasible. In these cases, convert generates
script code for compatibility libraries which support the GENESIS 1.4
features.
Some scripts can be converted and run successfully without any manual
changes to the converted scripts. In most cases, however, some changes
to the converted scripts will be necessary.
The Conversion Process
Below is the process through which a GENESIS 1.4 script is converted
to run under GENESIS 2.0.
1 - Use the convert program to convert scripts from 1.4 to
2.0 syntax.
2 - Fix any known problem areas (See, Convert Problem Areas).
3 - Try the script out and fix any remaining problems.
Using the Convert Program
The easiest way to use convert is to create a new directory for the new
scripts, cd to the new directory and convert the files from the old
directory. A simple shell procedure may be used to convert an entire
directory. For example, if your 1.4 script files are in the directory
../oldscript, then the following shell commands will convert the entire
directory placing the converted scripts in the current working
directory:
csh:
foreach script (../oldscript/*.g)
convert $script
end
sh:
for script in (../oldscript/*.g)
convert $script
end
Global Script Variables
In order for convert to handle certain script expressions involving
global script variables, it must know what globals exist for a given
set of scripts. (This is not a problem for a self contained script
where global variables are defined and used within the script.)
Often a single script file is devoted to defining and initializing
global variables and constants for a given set of scripts.
The -constants option of the convert program gives a list of script
files which define the global variables for the script set. For
example, if the file constants.g contains global variable definitions
which are used througout a set of scripts in the ../oldscripts
directory then the following csh code would convert the scripts:
foreach script (../oldscripts/*.g)
convert $script -constants ../oldscripts/constants,g
end
The -constants option will allow one or more scripts to be given.
Compatibility Libraries
Two areas of major change in GENESIS 2.0 are the Xodus GUI and support
for network modeling (e.g. GENESIS 1.4 connections). Support for use
of these facilities in GENESIS 2.0 is provided by compatibility
libraries.
While the compatibility libraries allow faster conversion of GENESIS
1.4 scripts for use under GENESIS 2.0, these libraries will not be
aggresively supported and should be viewed as a transitional step in
converting scripts to GENESIS 2.0 facilities. Those areas of your
scripts which use these libraries should eventually be recoded to use
the new GENESIS 2.0 features. Assistance for recoding of these
features may be found in the new GENESIS 2.0 Reference Manual (not
available at this time).
The X1compat Library
Compatibility for GENESIS 1.4 features of Xodus is provided as a set of
scripts using GENESIS 2.0 extended objects to implement the old Xodus
objects and script functions to implement old Xodus commands. To load
the X1compat library, include Scripts/X1compat in your SIMPATH and
include X1compat from your .simrc or your main simulation script.
Convert will not add an include statement for X1compat to your
scripts.
X1compat defines a set of old Xodus compatible objects which are named
using the prefix "x1" in place of the normal "x" prefix for Xodus
objects (e.g. xform becomes x1form, etc). Convert will automatically
transform create statements from Xodus objects in 1.4 scripts to use
the X1compat objects. Some support for field naming of old Xodus
objects is included in the new Xodus objects, which may allow direct
use of the new Xodus objects. The -noX1compat convert option causes
convert not to perform the translation to X1compat objects. This is
likely to be useful for only those scripts which use the basic Xodus
widgets (i.e. xform, xlabel, xbutton, xtoggle and xdialog). Uses of
xdraw or xgraph are likely to require use of X1compat.
Convert and the X1compat library cannot address various issues of
layout of widgets on a form. See, Convert Problem Areas, for more
information.
The Connection Compatibility Library
While GENESIS 1.4 connections are not a standard part of GENESIS 2.0, a
compatibility library may be compiled into GENESIS 2.0 which supports
the old connection feature. (See, src/Makefile or Usermake for
instructions on including the library.) The library defines the
connection related objects (e.g. axon, synapses, etc) and the
connection related commands (e.g. region_connect, expweight,
radialdelay, etc) as well as connection specific commands which support
set/get/show of connections (e.g. setconn, getconn and showconn).
Access to connection fields is not supported by the GENESIS 2.0
setfield, getfield and showfield commands.
Convert will change connection related script statements as needed to
use the Connection Compatibility Library. In particular, it will
convert uses of set, get and show on connections to use setconn, et
al. In some cases, convert will be unable to convert these statements
(See, Convert Problem Areas).
Converting User Libraries
Objects and commands defined in user libraries (for the most part) will
not need to change to run under GENESIS 2.0. To compile your libraries
and create a new GENESIS you will need to replace and update your
Usermake, Libmake(s), liblist and perhaps the library startup script.
Copy the Usermake and liblist files from the GENESIS 2.0 installation
directory to your local GENESIS directory renaming Usermake to
Makefile. Add your user libraries to the Makefile and liblist files.
In each user library you must copy the Libmake from the GENESIS 2.0
installation directory into the library directory renaming it
Makefile. Add your library specific information and files to the
Makefile.
The convert program cannot be used to convert startup scripts. The
only changes you should need to make are to modify any GENESIS 1.4
script language features which change in 2.0 and to remove any
non-startup commands from the script. (Startup commands are object,
addfunc, hashfunc, newclass and addaction.) Since a startup script is
usually straight line code and the typical commands in a 1.4 startup
script are the above named commands, there are normally no changes
required. There are, however, some GENESIS 2.0 features you may want
to take advantage of in your startup scripts. See the new GENESIS
Reference Manual section on library startup scripts for details.
Convert Problem Areas
There are a number of areas in which convert will be unable to
transform script statements or where the converted code will perform in
a less than optimal manner. Each problem area described below must be
found and fixed manually.
Script Callbacks
Commands used as callbacks to script commands or functions are not
translated by convert. As such, script callbacks like the following
would fail:
create xbutton echoButton -script "echo -n this is a test"
create xdialog vmDialog -script "set /mycompt Vm <v>"
The echoButton will result in a usage error when pressed and the
vmDialog will fail because the set command no longer exists.
Command Options in Script Variables
A command option which is passed to a command through a script variable
or as the result of a command or script function will not be
translated. For example, if leoptions is a script string variable
holding the value "-R" (a recursive listing), then the following code
will not be converted:
le {leoptions}
The code which sets leoptions must be found and changed.
Command Arguments That Look Like Options
All GENESIS 2.0 commands check for valid command options and complain
when an unkown option is given. As a result, code like
echo -notAnOption
will result in a usage error. This will also be the case if a script
variable value looks like an option, e.g.
str echoOption = "-notAnOption"
echo {echoOption} // Usage error!
The usage statement can be avoided by placing whitespace before the
value, e.g.
echo " -notAnOption"
echo " "{echoOption}
Set/Get/Show Connections in Script Variables
Commands like
set anElm:0 weight 10
will be correctly translated to use the setconn command. However, code
like
str connelm = "anElm:0"
set {connelm} weight 10
will be translated to a setfield command. Convert behaves similarly
with translating the get and show commands.
Script Variable/Command Name Conflicts
With all the command name changes in GENESIS 2.0, it is possible that a
script variable in a GENESIS 1.4 script may coinside with a new GENESIS
2.0 command name. In this case, you may receive a syntax error or
unexpected result as the script variable will take precedence over the
command name. This is may be particularly likely with the el command.
(The convert program may be updated at some future point to rename
script variables which clash with GENESIS 2.0 command names.)
Setting Integration Methods
GENESIS 2.0 removes some of the previously existing integration methods
and renumbers some of the remaining methods. Convert will handle the
renumbering as long as a number is given directly to the setmethod
command. If this is not the case, convert will issue a warning and the
command will be left unaltered. You must change the integration
numbering manually. See setmethod.txt (or type "help setmethod" in
GENESIS) for the new numbering.
Sizing of Xodus Forms
XODUS 1 made use of an unsupported feature of MIT X11 which allowed
forms to automatically adjust their height to accomodate all the
widgets which they contain, even if the form was made too short.
Although this did not work under Openwindows, it allowed users of MIT
X11 to be somewhat sloppy in the sizing of forms when writing scripts.
This feature no longer exists in XODUS, so forms which are incorrectly
sized may not show all the widgets which they contain. The most
convenient way to detemine the proper hgeom for the form is to properly
resize it with the mouse and then inspect the hgeom field for the value
to use in your script.
Apart from the preceeding issue, forms previously large enough to
encompass a given set of widgets may not be large enough under GENESIS
2.0, as the border widths of XODUS object have increased.
Positioning and Sizing of Widgets
Scripts which explicitly set the dimensions of a widget based on the
expected dimensional requirements of a 1.4 widget may cause text or
graphics within the widget to be clipped under 2.0. This is due to the
additional requirements of the Motif style borders.
Likewise, widgets which are positioned using absolute coordinates on
the form based on expected default dimensions of other widgets on the
form may overlap other widgets on the form.
The only widget layouts used under GENESIS 1.4 which are likely to work
well under 2.0 are those using relative positioning. Even if this is
the case, the form size may need to be changed (See Sizing of XODUS
Forms above).
Routine Name: copy
Description: Copies an element (and its children, if any) from one portion
of the element tree to another.
Usage: copy src-element dest-element -repeat # -autoindex
src-element element to copy (if this element has
subelements, they too are copied)
dst-element location into which to copy src-element (if
dst-element already exists, src-element is
copied beneath it with original name; if
dst-element does not exist, copy of
src-element is given that name as new name)
-repeat is followed by an integer specifying how
many duplicates of src-element to make
-autoindex automatically assigns the first free element
index to the newly created element.
Example: copy /cell1 /cell2
// create 5 cells, cell[0-4]
copy /library/protocell /cell[0] -repeat 5
Notes: This routine copies an element and its children, without
changing the original.
Simulation messages and connections between elements within
the copied subtree will be copied, but messages and
connections to elements outside of the copied subtree will not
be copied.
After it has copied the object, the copy routine issues the
COPY action for that element type, if any.
See also:
create ,
createmap ,
move
Routine Name: cos
Description: Returns cosine for given angle (specified in radians).
Usage: cosine = {cos angle-in-radians}
Example: float x
x = {cos {3.14159/4}}
Notes:
See also:
acos
Routine Name: countchar
Description: Counts occurrences of specified character in string.
Usage: number-of-occurrences = {countchar string char}
number-of-occurrences returned as integer indicating how
many occurences of char were found
in string
Example: genesis > echo {countchar "abcbdb" b}
3
Notes:
Routine Name: countelementlist
Description: Returns the number of elements in an element list.
Usage: countelementlist path [-listname listname]
path path specification, which may include
wildcards such as [] or # (note,
however, that operating-system style
use of * is not supported)
listname The listname argument tells it to look for the
field <listname> on the element in <path> and
treat that as an element list.
Example:
genesis > echo {el /#}
/proto /output /cell /control /data
genesis > echo {countelementlist /#}
5
genesis > echo {countelementlist /##}
19
Notes:
See also:
el ,
Tree
Routine Name: cpu
Description: Displays current cumulative cpu usage for user and system time.
Usage: cpu
Example: genesis > cpu
user time used = 3 sec 510000 usec
system time used = 1 sec 180000 usec
Notes: This routine calls the getrusage operating system command to
display user/system usage statistics.
See also:
showstat
Routine Name: create
Description: Creates new element of specified element type.
Usage: create element-type name -autoindex [object-specific-options]
element-type type of element; must be one of the valid
element types (objects) compiled into the
genesis executable, or an extended object
created with the GENESIS scripting language.
name element or path name where new element is to
be attached in the GENESIS element hierarchy;
if single name is given (i.e., no path
separators "/"), element is created on the
current working element [also can be indexed;
see below]
-autoindex automatically assigns the first free element
index to the newly created element.
[options] some elements can be created with additional
options which are specific to the object type
(see individual object documentation for
options)
Example: create neutral /cell
create compartment /cell/soma
create xgraph voltage_plot
Notes: The create routine is used to create new elements in the
GENESIS element tree. It generates an element of type
"element-type" and places it in the element tree with the
assigned name.
The additional options which can be specified for the create
routine depend on the element-type being created. For
example, elements which represent graphical widgets contain
data fields for screen information such as the position and
dimensions of the graphical object. This information may
also be specified as an option in the creation of an element.
create compartment soma[0]
create compartment soma[1]
create compartment soma[10]
create compartment soma -autoindex
In the example above, he name field of each element will be
"soma" but the index fields will have values 0-2 and 10.
The "-autoindex" option in the last statement creates the
element with index 2. Note that soma and soma[0] are
equivalent i.e. the absence of an index implies an index of
0 (the default). Also note that the index is an arbitrary
value and does not need to follow any order.
See also:
listobjects ,
showobject ,
le
Routine Name: createmap
Description: Copies an element multiple times to form a two-dimensional
array.
Usage: createmap source dest Nx Ny -delta dx dy -origin x y -object
source path to the element that will be copied
dest pathname of the parent of the array of copies
Nx,Ny number of elements in the x and y dimensions
of resulting array
dx,dy distance between adjacent elements in the
array in x and y dimensions, in world or
actual coordinates (default: 1,1)
x,y position of first element of array (i.e.,
corner of array, in world coordinates
(default: 0,0)
-object indicates that the source is the name of
an object, rather than the path to an element
Example: createmap /prototypes/cell /map 10 10
createmap mycell /network 3 5 -delta 0.1 0.2 -object
[from /usr/genesis/Scripts/orient_tut/retina.g:]
genesis > createmap /library/rec /retina/recplane \
{REC_NX} {REC_NY} \
-delta {REC_SEPX} {REC_SEPY} \
-origin {-REC_NX * REC_SEPX / 2} {-REC_NY * REC_SEPY / 2}
genesis > le /retina/recplane
rec[0-99]/
Notes: The createmap routine creates a two-dimensional array of the
specified source element by making copies of the source
element and assigning the copies x,y coordinates within the
specified bounds. The resulting array is placed under the
specified destination path. As with the copy command, the
entire tree of child elements and messages is copied along
with the source element. When the "-object" option is
used, the source is the name of a GENESIS object, instead of
the path to an element tree. This is most useful when a
prototype cell is created as an extended object composed from
a combination of basic objects with added fields and default
values.
The resulting array coordinates can be used by routines such
as planarconnect, planarweight, and planardelay to assign
connections, synaptic weights and propagation delays for
simulation-oriented elements. The coordinates can also be
used to display the cells in a draw widget.
See also:
copy ,
planarconnect ,
planarweight ,
planardelay ,
Extended
Routine Name: debug
Description: Sets (or displays) the debug level used by some routines.
Usage: debug [level]
level integer indicating debug level to use:
0 = disable debug (nothing printed)
1 = intermediate debug
2 = intermediate debug
3 = full Debug (print everything)
Example: genesis > debug
debug level 0
genesis > debug 2
debug level 2
Notes: Sets the debug level used by some routines to report status
information. Increasing the level typically increases the
amount of information produced. If no argument is given the
current debug level is displayed.
See also:
silent
Routine Name: delete
Description: Deletes an element and all of its children.
Usage: delete element
Example: delete /neuron
Notes: The delete routine is used to delete elements from the GENESIS
element hierarchy. Deleting an element which has children
attached to it will also delete all of the child elements.
In the course of deleting the object, the delete routine also
issues the DELETE action for the object before it is
eliminated.
When deleting interpol_structs that share tables between them
(e.g. tabchannel, tab2Dchannel, or tabcurrent), or the cells
or compartments containing them, you must call TABDELETE
first, in order to deallocate the memory for the tables.
Finally, you have to give the "reclaim" command for the memory
to actually be freed. Note that the tables are shared among
all copies of the interpol_struct that are created by copy or
readcell from a prototype. Therefore, you shouldn't call
TABDELETE unless you plan to delete all copies of the
interpol_struct.
See also:
create ,
reclaim
Routine Name: deleteaction
Description: Deletes an action from an element added by a previous
addaction command
Usage: deleteaction element action-name
element element to delete the action from
action-name name of the action to delete
Notes: An object's built in actions are permanent and may
not be deleted using deleteaction.
See also:
addaction , listactions,
Extended
Routine Name: deleteall
Description: Deletes all existing elements. [not recommended]
Usage: deleteall -force
-f flag to force deletions
Example: genesis > deleteall
*** WARNING ***
This function removes all elements from the simulation.
If you really want to do this use 'deleteall -force'.
usage: deleteall -force
genesis > deleteall -f
Simulator cleaned out.
Notes: If no flags are specified, deleteall displays a warning
message.
The deleteall routine can be used to return the simulator to
a startup state by deleting all existing elements, including
elements which may be provided by default at startup. If
this is done, running the simulation scripts again could
produce different results.
If you really need to delete all the elements in your GENESIS
session, you might as well quit exit from GENESIS completely
and start again -- deleteall just deletes all the elements
and might not reset other parameters to appropriate values.
In general, you should not use the deleteall routine.
See also:
delete
Routine Name: deleteclass
Description: Delete a class tag from an element which was previously
added using addclass.
Usage: deleteclass element class-name
element element from which to delete the class
class-name name of the class to delete
Notes: Deleteclass will not delete classes defined for the
built in objects.
See also:
addclass , listclasses,
Extended
Routine Name: deletefield
Description: Deletes an extended field which has been added to an element.
Usage: deletefield [element] field-name
Example: genesis > addfield /soma area
OK
genesis > deletefield /soma area
OK
genesis > deletefield /soma inject
deletefield: Cannot delete permanent field 'inject' on element '/soma'
Notes: Only added extended field may be deleted with deletefield.
See also:
addfield
Routine Name: deleteforwmsg
Description: Deletes a forwarded message previously forwarded using
addforwmsg.
Usage: deleteforwmsg source-element message-number destination-element
source-element element from which the message was
forwarded
msg-number number (index) of message in message list
(messages are numbered from 0 up)
destination-element
element to which the message was forwarded
Notes: The destination element must accept messages of the same
name and with the same number of data slots as the message
being forwarded.
See also:
addforwmsg ,
showmsg ,
Extended
Routine Name: deletemsg
Description: Deletes a message link between two elements.
Usage: deletemsg element msg-number -incoming -outgoing
-find srcelem type
element element receiving or sending the message
msg-number index of message in element message list
(index can be obtained with 'showmsg'
routine, or, in a script, with 'getmsg' used
with the -find option)
srcelem element sending the message
type message type (PLOT, AXIAL, VOLTAGE, etc.)
-incoming message to be deleted is incoming
-outgoing message to be deleted is outgoing
-find delete the first message (lowest index)
matching the srcelem and type
Example: deletemsg /cell/soma 2 -incoming
deletemsg /data/voltage -in 0 -find /cell/soma PLOT
Notes: The deletemsg routine is used to remove messages added using
the addmsg routine. Deleting earlier messages will change
the message numbers of the remaining messages. If
msg-number is not known for the desired message, it may be
found by using getmsg with the -find option.
When the -find option of deletemsg is used, the msg-number
argument is required, but ignored, and the message must be
an incoming one. (The -incoming and -outcoming options are
ignored, if specified.)
See also:
addmsg ,
showmsg ,
getmsg
Routine Name: deletemsgdef
Description: Deletes a message definition previously added to an element
using addmsgdef.
Usage: deletemsgdef element msg-name
element element from which to remove the message
definition
msg-name name of the message type to delete
Notes: Deletemsgdef will not delete permanent message definitions
defined by the built in objects.
See also:
addmsgdef ,
showobject ,
Extended
Routine Name: deletetasks
Description: Removes all simulation events from the simulation schedule.
Usage: deletetasks
Example: deletetasks
Notes: deletetasks removes from the simulation schedule table any
functions currently scheduled for execution during simulation.
This allows you to construct a new schedule using a sequence
of addtask calls.
See also:
Schedules ,
addtask ,
resched ,
showsched
Routine Name: disable
Description: Disables an element and its children from participating in a
simulation.
Usage: disable element
Example: disable /prototypes/mitral_cell
Notes: The specified elements are still accessible to basic
operations such as setfield and showfield, but they will not
participate in the simulation or be updated during the run of
the simulation (i.e., when you use the step routine).
You should run reset or resched after you disable an element
to be sure that the simulation properly takes into account the
disabling of the element. (The resched command may be used to
recompute the simulation schedule in order to remove the
disabled element without resetting the simulation. It is not
a good idea to call resched frequently, especially for large
simulations, as it does quite a bit of work.)
The disable command cannot be used with script_out elements.
If you need to disable a script_out element, it will be best
to use a more versatile extended object, instead. (See
Extended.txt.)
See also:
enable ,
step ,
reset
Routine Name: echo
Description: Prints out its arguments to the console.
Usage: echo [arguments] [-nonewline] [-format format-string]
arguments strings, or expressions enclosed in braces
-nonewline do not include carriage return at end of line
format-string a string of the form "%[flag][width]s", where
"width" is the minimum number of characters
to be output. If the output width is less
than this, it is padded with blanks. "flag"
is as in C; "0" means pad with zeroes, "-"
means left justify. (to construct mixed
formats, use multiple echo commands with
-nonewline to place them on a single line)
Example:
genesis > int five = 5
genesis > echo five
five
genesis > echo { five }
5
genesis > echo "Give me" -n; echo space! -f %20s
Give me space!
Notes: The echo routine is used to print output to the command
interpreter window. If echo is followed by a string (or a
quoted string) that string will be printed. If echo is
followed by a string enclosed in curly brackets, then the
value assigned the variable named by the string will be
printed.
Routine Name: egg
Description: Generates coordinates for points on the surface of an ovoid.
Usage: egg filename x y z d -normal
filename name for file into which to put generated
coordinates
x, y, z dimensions of the egg
d approximate distance between points
-normal "normal"; if selected, generates an
additional set of 3 coordinates per line,
to define the normal to the surface. This
format is used by the cellsheet routine.
Example: egg eggpoints 400e-6 400e-6 400e-6 100e-6 -normal
Notes: Generates coordinates for points on the surface of an ovoid,
(an egg) and puts them into a file, with an option for
generating the normals at each point. This is useful for
generating layers of cells on an ovoid. It tries to get
fairly even spacing. The coordinates are dumped into the
file specified by filename with one set of coordinates per
line.
See also:
plane ,
cellsheet
Routine Name: el
Description: Returns list of elements matching wildcard specification.
Usage: list-of-elements = el path [-listname listname]
list-of-elements returned as a text
path path specification, which may include
wildcards such as [] or # (note,
however, that operating-system style
use of * is not supported)
Example: genesis > echo {el /#}
/proto /output /net
genesis > echo {el /net/neuron[]}
/net/neuron /net/neuron[1] /net/neuron[2] /net/neuron[3]
genesis > str name
genesis > foreach name ({el /# })
? echo {name}
? end
/proto
/output
/net
Notes: In GENESIS 1, this was EL or element_list. getelementlist
is an alias for el in GENESIS 2.
The listname argument tells it to look for the field
<listname> on the element in <path> and treat that
as an element list.
Routine Name: enable
Description: Enables previously disabled elements to participate in a
simulation.
Usage: enable element
Example: enable /neuron
Notes: The enable routine is used to enable an element which has been
disabled using the disable routine.
You should run reset or resched after you enable a previously
disabled element to be sure that the simulation state properly
takes into account the newly enabled element.
See also:
disable ,
step ,
reset
Routine name: enddump
Description: Cleans up at the end of a dumpfile. Normally
generated by default in a dumpfile. Doesn't do much of
anything outside a dumpfile.
Usage: enddump
Example: Here is a little dumpfile using initdump that recreates a
simple 2-compartment model, and ignores the orphan element
/x/y/z.
============================================================
//genesis
initdump -version 3 -ignoreorphans 1
simobjdump neutral
simobjdump compartment activation Vm previous_state \
Im Em Rm Cm Ra inject dia len initVm
simundump neutral /x/y/z 0
simundump neutral /a 0
simundump compartment /a/compt 0 0 0.6632976405 0.6632942696 \
-0.3333315551 0 1 1 1 1 0 0 0
simundump neutral /b 0
simundump compartment /b/compt 0 0 0.3299660931 0.3299627243 \
0.3333349228 0 1 1 1 0 0 0 0
addmsg /b/compt /a/compt RAXIAL Ra Vm
addmsg /a/compt /b/compt AXIAL Vm
enddump
// End of dump
============================================================
Notes:
See also:
initdump ,
simdump ,
simobjdump ,
simundump
Routine Name: eof
Description: Tests whether at end of currently opened file.
Usage: eof-flag = {eof filename}
eof-flag returned as 1 if at end of file;
returned as 0 if not at end of file
filename name of open file to test
Example:
str line
openfile TestFile r
line = {readfile TestFile -linemode}
while (!{eof TestFile})
// process line from the file
echo {line}
line = {readfile TestFile -linemode}
end
Notes: The file must be currently open.
See also:
openfile ,
listfiles ,
readfile
Routine Name: exists
Description: Tests for existence of specified element or field.
Usage: exists-flag = {exists element [field]}
exists-flag returned as 1 if element (or element field)
exists; returned as 0 otherwise
element name or full pathname of element to test
field element field to test existence of
(does not check whether field is nonempty)
Example: if ({exists /cell/dendrite})
delete /cell/dendrite
end
genesis > create compartment soma
genesis > echo {exists soma}
1
genesis > echo {exists bogus}
0
genesis > echo {exists soma len}
1
genesis > echo {exists soma bogusfield}
0
Notes:
Routine Name: exit Description: Exits from GENESIS, terminating any simulation in progress. Usage: exit Notes: You can also use "quit", which is identical to "exit".
Routine Name: exp
Description: Returns "e" raised to specified power.
Usage: number = {exp power}
Example: genesis > echo { exp 1 }
2.718281746
Notes:
See also:
log ,
pow
Routine Name: file2tab
Description: Utility function for loading a file into an interpol struct
of an element
Usage: file2tab filename element table -table2 table -table3 table
-xy xdivs -skiplines number -calc_mode mode -autofill table
Arguments: filename: name of ascii file to load into table. Entries
must be separated by spaces, tabs or line breaks.
Line breaks in input file are ignored. In other
words, any number of numeric entries per line are
allowed, and all are used.
element: path of element containing the table
table: name of interpol_struct within the element.
Options: -table2 table
This option allows one to specify an additional table to load
the file into. Entries are loaded alternately into the first
table and table2. Note that table2 must be on the same
element as table. If there are an odd number of entries in
the file, the last one is not used.
-table3 table
This allows a third table. This option is similar to table2.
-xy xdivs
Uses xy mode for the table entries. Assumes that the points
are stored in the file as x,y pairs. Uses the xdivs argument
to set the table size, then figures out xmin, xmax
and sets the table limits and dx accordingly. Uses dx
between all points and fills up table using linear
interpolation if the x,y pairs in the file are not evenly
spaced. Assumes x is monotonically increasing, behavior
in other situations is undefined.
-skiplines number
Skips "number" lines at the start of the file. Useful
for reading in 'xplot' files into a table, since these
files usually have headers.
-calc_mode mode
'mode' is an integer representing one of the legal
interpolation modes (0 = no interpolation, 1 = linear
interpolation, 2 = fixed, see interpol doc).
-autofill table
table is the name of an interpol_struct in which we wish
to place successive integers. Useful for displaying plots
from a single series of numbers in a file:
file2tab yvalue_file /form/graph/plot ypts -autofill xpts
will load the numbers in yvalue_file into ypts, and put
successive integers into xpts.
Example: This simple example illustrates loading an xplot file into
a table using different options to file2tab. In the first
case we end up with the x and y values alternating. In
the second case we end up with the y values only. In the
third case we use the xy mode to load the values into a linear
table while preserving the x information.
Datafile name is xplot.data:
/newplot
/plotname "testplot"
0 5
4 10
8 5
10 10
script file:
//genesis
create table /tab1
file2tab xplot.data /tab1 table -skiplines 2
create table /tab2
file2tab xplot.data /tab2 table -table2 table -skiplines 2
create table /tab3
file2tab xplot.data /tab3 table -skiplines 2 -xy 50
showfield /tab1 *
showfield /tab2 *
showfield /tab3 *
-----------------------------------------------------------------------------
Notes: The control fields of the interpol are set as follows:
xdivs: for 1 table: (num_entries -1)
for 2 tables: (int)(num_entries / 2 -1)
for 3 tables: (int)(num_entries / 3 -1)
xmin : 0
xmax : 1
calc_mode: defaults to 0 (lin-interp), but may be set on the
command line.
See also:
tab2file , interpol_struct documentation
(
Tables ),
table
Routine Name: fileconnect
Description: Establishes synaptic connections and weights between groups
of elements based on a file of weights. The routine
sets up the connections by adding SPIKE messages between the
source and destination objects and then assigning a weight.
Usage: fileconnect source_elements destination_elements \
filename -wtscale w
source_elements A wildcarded list of elements which are the
sources of the SPIKE messages. These must be of
class "spiking" and are usually spikegen or
randomspike objects.
destination_elements A wildcarded list of elements which are
the destinations of the SPIKE messages. These must
be synchans or objects derived from synchan.
filename The name of an ascii file with weights
(as floats) separated by whitespace. Separation
can include spaces, line breaks etc.
The file is expected to have weights for all possible
connections, i.e., :
src_nelements * dest_nelements
entries.
The order of entries is source-first. For
example, if the source_elements list has 9 entries
and the dest_elements list has 16, then the
first 9 entries will specify weights from each of
the sources to the first destination. The next 9
entries will be to the second destination, and so on.
Weights less than or equal to zero will not
form connections at all.
Negative weights are often used to indicate
inhibitory input, so the command provides a way
around that: use a negative wtscale argument.
If a file has +ve as well as -ve weights,
it would be read twice: first with the paths of
excitatory receptor channels and a +ve wtscale,
then with the paths of the inhibitory ones and a
-ve wtscale.
-wtscale w -- This specifies a scale factor for all
weights. As noted above, it can be negative to
select for inhibitory (negative) weights.
Example:
int nx = 5
int ny = 5
int destx = 5
int desty = 5
include cellproto.g
createmap /proto/cell /lgn {nx} {ny}
createmap /proto/cell /v1 {destx} {desty}
fileconnect /lgn/##[TYPE=spikegen] /v1/cell[]/glu \
wts.file -wtscale 0.1
fileconnect /lgn/##[TYPE=spikegen] /v1/cell[]/GABA \
wts.file -wtscale -0.1
wts.file would have 5x5x5x5 entries. A centre-surround
pattern for the above example could start like this:
10 -1 0 0 0
-1 -1 0 0 0
0 0 0 0 0
0 0 0 0 0
0 0 0 0 0
-1 10 -1 0 0
-1 -1 -1 0 0
0 0 0 0 0
0 0 0 0 0
0 0 0 0 0
0 -1 10 -1 0
0 -1 -1 -1 0
0 0 0 0 0
0 0 0 0 0
0 0 0 0 0
...
Notes: The routine is somewhat inefficient for large input and output
arrays with sparse connectivity, since it has to read
Nsrc x Ndest entries. This is offset by the fact that
the routine simultaneously creates synapses and sets
their weights, thereby eliminating a scan for setting
weights. The main use is for setting up large
networks based on weight files generated by other
programs.
See also:
planarconnect ,
planarweight ,
planardelay ; chapter 18 of the Book of GENESIS has a
lengthy discussion on these and related commands. A detailed
example of the use of fileconnect is given in Scripts/examples/fileconnect.
Routine Name: findchar
Description: Returns location of specified character in a given string.
Usage: position = {findchar string char}
position returned as integer indicating position of
first occurrence of char in string (positions
start with 0); returns -1 if char not found in
string
string string to search
char single character to locate in string (any
extra characters in char are ignored)
Example: genesis > echo {findchar abcbx b}
1
genesis > echo {findchar "a bcbx" b}
2
genesis > echo {findchar abcbx bx}
1
genesis > echo {findchar abcbx q}
-1
Notes:
See also:
strcat ,
strcmp ,
strncmp ,
strlen ,
substring
Routine Name: findsolvefield
Description: Returns a string giving the array location of a particular
element field value in the hines solver. Used for
input/output of values when the original element has been
taken over by the hines solver and its fields may not be
updated.
Usage: findsolvefield hsolve element field
hsolve name of the hsolve element
element name of an element which was taken over by hsolve
field the field of the element whiich is to be accessed
Example: // statements to create the hsolve element "/cell"
...
setfield /cell chanmode 4
call /cell SETUP
...
create disk_out /output
addmsg /cell /output OUTPUT \
{findsolvefield /cell /cell/soma/Na Gk}
...
reset
or:
genesis > echo {findsolvefield /cell /cell/soma/Na Gk}
givals[108]
genesis > echo {getfield /cell {findsolvefield /cell /cell/soma/Na Gk}}
2.634178326e-10
Notes: When using chanmodes 2 through 5 with the hines solver
(hsolve), you can no longer assume that all the fields of the
elements that are taken over by hsolve will be updated. The
findsolvefield function is used to access the hsolve arrays
directly to output field values instead of having to use the
old disabled elements. This allows one to establish new
messages for the output of field values after setup of the
hsolve element. The example above shows how to output the Gk
field of the Na channel from the hsolve element /cell. Note
that the fields Gk, Ik, Ek, and Im are not available for
chanmodes 2 and 3, and require the use of findsolvefield
in chanmodes 4 and 5.
See also:
hsolve
Routine Name: floatformat
Description: Sets format for display of variables of type float.
Usage: floatformat format-string
format-string "%[flag][width].[precision][type]",
indicating format to use in displaying
float-type variables. (default: "%0.10g")
The flag, width, precsion and type are
defined as in C, but only f and g type
formats are allowed.
Example:
genesis > float x = 3.12345678
genesis > echo { x }
3.12345678
genesis > floatformat %0.5g
genesis > echo { x }
3.1235
genesis > floatformat %10.5g
genesis > echo { x }
3.1235
genesis > floatformat %10.5f
genesis > echo { x }
3.12346
genesis > float y = 1e-5
genesis > floatformat %0.10g
genesis > echo {y}
1e-05
genesis > floatformat %0.10f
genesis > echo {y}
0.0000100000
genesis > floatformat %+10.2f // show sign
genesis > echo {x}
+3.12
genesis > float pi = 3.14159265
genesis > floatformat %-10.2f //left justify with width 10
genesis > echo {x} {pi}
3.12 3.14
genesis > floatformat %010.2f // "0" flag pads with zeroes
genesis > echo {x} {pi}
0000003.12 0000003.14
Notes: As in C, the width is the minimum number of characters to be
output. If the output width is less than this, it is padded
with blanks, unless the "0" flag is used. For type f, the
precision is the number of digits after the decimal point;
for type g, it is the maximum number of significant digits.
Routine Name: flushfile
Description: The contents of a file opened with ``openfile <filename> w''
and written with ``writefile <filename>'' are flushed from
the buffer onto disk. The file remains open for further
writefile operations.
Usage: flushfile file-name
Example:
genesis > openfile test w
genesis > writefile test 1.0 2.0 3.0
genesis > more test
genesis >
genesis > flushfile test
genesis > more test
1.0 2.0 3.0
genesis > writefile test 4.0 5.0 6.0
genesis > more test
1.0 2.0 3.0
genesis > closefile test
genesis > more test
1.0 2.0 3.0
4.0 5.0 6.0
Notes: This command is useful when the contents of a file need to
be checked before a simulation has terminated. (Writefile
alone does not flush the buffer, and file contents are only
available after closefile has been issued).
See also:
openfile ,
writefile ,
closefile
Routine Name: gaussian
Description: Returns a random value from a Gaussian (Normal) distribution.
Usage: value = {gaussian mean standard-deviation}
Example: genesis > echo {gaussian 0 1 }
0.5069125295
genesis > echo {gaussian 0 100 }
-63.29789352
Notes:
See also:
randseed ,
rand
Routine Name: gen2spk
Description: This program takes ascii files generated by GENESIS
containing simulation times and membrane potentials
(normally of the soma) and extracts the spike times
relative to the onset of a current-clamp square-wave
pulse. The output will be a file which will have currents
and spike times listed in the file.
Usage: gen2spk datafile current-start current-duration \
total-duration -stepsize dt -maxaccuracy
Arguments: datafile: the ascii input file. The format of the input
file is as follows: The beginning of a trial is
indicated by the following two lines:
/newplot
/plotname 0.234
i.e. the plotname is the current value for that
trial (units are arbitrary but are usually in nA).
This format is taken from Matt Wilson's xplot
program, which is useful for displaying simulation
output. The subsequent lines consist of time/Vm pairs
as follows:
0 -0.0770584
0.0002 -0.077233
etc.
which can be generated automatically by the
asc_file object of GENESIS. Multiple trials can be
put in one file, as long as they're separated by the
/newplot, /plotname ... sequence described above.
current-start: the time in the trace where current
injection begins. Most simulations allow the cell to
reach equilibrium before injecting current (e.g. for
50-100 msec or more). All spike times will be relative
to the starting time of the current injection. Units
are in seconds (SI units).
current-duration: the duration of the current injection, in
seconds.
total-duration: the total duration of the entire trace,
including the time before and after the current
injection.
Options: -stepsize dt: the output time step i.e. the time between
samples in the output file. This is usually much
larger than the simulation time step. The default
value is 0.0001 (0.1 msec).
-maxaccuracy: the output spike times are printed with ten
digits of precision rather than 4 (the default).
Obviously this is only useful if your output step
size is small enough so that the accuracy will make
a difference (i.e. less than 0.0001).
Output: A file with the same name as the input file but with
.spk.sim added. The file format is:
CURR 0.1
SPK 0.0010
SPK 0.0123
--------------------
CURR 0.2
SPK 0.0004
SPK 0.0054
SPK 0.0080
...
etc. CURR means the current value and is equal to the
value in the /plotname line in the input file. Each spike
gets a SPK line; the value to the right of the SPK is the
time in seconds when the spike occurred, relative to the
start of the current injection. Different currents are
separated by a line of dashes.
Algorithm: See the comments in the file src/param/gen2spk.c.
Notes: This routine is used mainly for generating data for the
spkcmp function for current injection simulations.
However, it is not limited to this use and will extract
spikes from any membrane potential waveform.
The /newplot and /plotname lines must be written out
explicitly to disk using writefile. Make sure they are
flushed to disk before starting the simulation so that they
don't appear in the middle of what asc_file writes. See
the parameter search demos for examples of this.
Some weird waveforms may defeat the spike-identifying
algorithm. Very small (low amplitude) spikes are a good
example of this. Be careful when using this routine in
cases like this, and check the outputs with a visual
display of the membrane potential waveform.
Example: genesis> gen2spk "Vmfile" 0.2 1.0 1.5
In this case, the current comes on at 0.2 seconds, lasts
for 1.0 seconds (i.e. until the simulation time is 1.2
seconds) and the whole trace is 1.5 seconds long.
See also: Parameter Search (
Param ),
spkcmp ,
shapematch
Routine Name: genesis
Description: Starts up the GENESIS program. (operating system command)
Usage: genesis [-usage][-nosimrc][-altsimrc filename][-notty][-nosig]
[-execdir dirname][-nice nice-level][-nox]
[-defaultcolor][-batch][script arg1 ...]
-usage print the usage message, listing options.
-nosimrc ignore the .simrc file
-altsimrc use 'filename' instead of the .simrc file
-notty do not accept terminal input
-execdir change to 'dirname' after starting genesis
-nice give genesis 'nice-level' priority
-nox start GENESIS without initializing XODUS
-defaultcolor use the display's default colormap
-batch run genesis in the background
script name of a GENESIS script to run
Example: % genesis -altsimrc ~/.backup_simrc
Starting Genesis
==========================================================================
G E N E S I S
Release Version: 2.0
Copyright 1988 - 1995, California Institute of Technology
Some components are copyright by the originating institution and are used
with the permission of the authors.
==========================================================================
Executable: /usr/genesis/genesis
----------------------- Starting XODUS 2.0 -----------------------
Startup script: ~/.backup_simrc
SIMPATH=. /usr/home/jouser/mystartup
SIMNOTES=/usr/home/jouser/.notes
GENESIS_HELP=/usr/genesis/Doc
genesis #0 >
Notes: When starting, GENESIS looks for an initialization file, .simrc,
first in the current working directory, and then in your home
directory. After installing genesis, this file is created in the
GENESIS installation directory. After making any appropriate edits,
you should copy it to your home directory and insure that the
genesis executable is in your path.
A new GENESIS command line option -defaultcolor will cause GENESIS
to use the display's default colormap, even if the default visual is
readonly. The net result is that colorscale colors will be shared
among multiple GENESIS processes, but GENESIS will fail to allocate
a colorscale if the default colortable is full. This option may be
used to avoid X protocol errors on some SGI systems where the X11
server defaults to a TrueColor (24 bit) visual.
To perform a GENESIS simulation in the background (for example if you
want to login from home over a modem, start a simulation, and logout
while the simulation continues to run), your simulation script should
use no graphics, and write all output to files.
Besides specifying the -nox option when starting genesis to avoid
starting XODUS, you also need to use the -notty and -batch options.
GENESIS will attempt to read from stdin after the .simrc and command
line script are completed. The -batch option causes genesis to exit
rather than try to read stdin. -notty will avoid doing any terminal
setup and cleanup procedures which can also cause this type of
behaviour. You must specify both on the command line (i.e. neither
option implies the other). In addition, you need to redirect output
(both stdout and stderr) to a file. For example, to run a script
``batchtest.g'' and direct startup messages and any error messages to
a log file (using the C shell) you would use:
genesis -nox -batch -notty batchtest >& batch.log &
With the Bourne shell (or bash) it would be:
genesis -nox -batch -notty batchtest > batch.log 2>&1 &
See also: src/README,
Simulations
Routine Name: getarg
Description: Returns specified item from an argument list.
Usage: getarg [arguments] -count -arg #
One of -count or -arg must be given
Example: genesis > echo {getarg 11 22 33 44 55 -arg 3}
33
genesis > echo {getarg 11 22 33 44 55 -count}
5
Notes:
See also:
argc ,
argv ,
arglist ,
printargs
Routine Name: getclock
Description: Returns value of the time interval for the specified clock.
Usage: clock-value = {getclock clock-number}
Example: genesis > echo { getclock 0 }
5.000000e-05
Notes: The getclock routine returns the current value of the step
size for the specified clock (as a floating point number).
See also:
showclocks ,
useclock ,
setclock
Routine Name: getdate
Description: Returns operating system date-time.
Usage: str-value = getdate
Example: genesis > echo { getdate }
Thu Jun 22 22:11:13 1995
Notes: This is a GENESIS implementation of the operating system
date command, to have the value returned by the routine rather
than displayed directly to the user. This allows the current
date to be used as a data value within GENESIS.
See also:
sh
Routine Name: getdefault
Description: Returns the default value of an object field.
Usage: getdefault object-name field-name
Example: genesis > echo {getdefault compartment Rm}
1
Notes:
See also:
setdefault
Routine Name: getelementlist Description: Returns list of elements matching wildcard specification. Usage: getelementlist path -listname listname Notes: This is an alias for el.
See also: el
Routine Name: getenv
Description: Returns value of operating-system environmental variable.
Usage: str-value = {getenv environment-variable}
Example: genesis > echo { getenv DISPLAY }
babel.bbb.edu:0
Notes: This is a GENESIS implementation of the operating system
printenv command, to have the value returned by the routine
rather than displayed directly to the user. (GENESIS also
includes a version of printenv to have the value displayed
directly to the user.) The getenv routine allows the value of
the particular operating system environmental variables to be
used as a data value within GENESIS.
See also:
setenv ,
printenv
Routine Name: getfield
Description: Returns value of field in data structure of specified element.
Usage: getfield [pathname] field
field-value = {getfield pathname field}
pathname path specification
defaults to current working element
field name of field in element data structure
Example: echo {getfield /cell/soma Vm}
setfield /cell/soma Rm {getfield /form/Rm_dialog value}
Notes: The getfield routine returns the value of fields in the
specified path.
See also:
setfield ,
showfield ,
getfieldnames
Routine Name: getfieldnames
Description: Returns names of all existing fields in specified element.
Usage: element-fields = {getfieldnames Element}
element-fields returned as a single line (i.e., a
string without carriage returns)
listing fields of specified element
Example: echo { getfieldnames /output }
str name
foreach name ( {getfieldnames soma })
echo {name}
end
Notes:
See also:
getfield ,
showfield ,
setfield
Routine Name: getglobal
Description: Returns the value of a global variable, allowing the name of
the global variable to be held in a string variable.
Usage: getglobal name
Example:
genesis > str variable = "EREST"
genesis > addglobal float {variable}
genesis > setglobal {variable} -0.07
genesis > echo {variable} = {getglobal {variable}}
EREST = -0.070000
Notes:
Often it is useful to use a string variable name to hold the name of a
global variable. For example, one may want to pass the name of a global
variable to a function that declares a global variable, or that sets or
returns its value. However, normal GENESIS syntax for declarations and
assignments does not permit a variable name to be specified by a string
variable. The routines addglobal, getglobal, and setglobal are designed
to overcome this limitation.
See also:
Variables ,
addglobal ,
setglobal ,
listglobals
Routine Name: getmsg
Description: Returns information about a message into or out of element.
Usage: getmsg element -incoming -outgoing -slot msg-number slot-number
-count -type msg-number -destination msg-number
-source msg-number -find srcelem type
[One of -slot, -count, -type, -destination, -source or -find
must be given]
element element for which to determine information
msg-number number (index) of message in message list
(messages are numbered from 0 up)
srcelem element sending the message
type message type (PLOT, AXIAL, VOLTAGE, etc.)
-incoming look for an incoming message
-outgoing look for an outgoing message
-slot return the slot value for the given message
and slot numbers
-count return the number of messages in or out
of this element
-type return the message type for the message
having the index msg-number
-destination return the destination element for the
message having the index msg-number
-source return the source element for the
message having the index msg-number
-find return the index (msg-number) of the first
message matching the srcelem and type
Example:
genesis > echo { getmsg /cell/dend1 -out -destination 0}
/cell/soma
genesis > echo { getmsg /cell/dend1 -out -source 0}
/cell/dend1
genesis > echo { getmsg /cell/dend1 -out -count }
5
genesis > echo { getmsg /cell/dend1 -in -destination 1 }
/cell/dend1
genesis > echo {getmsg /cell/soma -in -find /cell/dend1 RAXIAL}
2
genesis > echo {getmsg /cell/soma -in -type 2}
RAXIAL
genesis > echo {getmsg /cell/soma -in -slot 2 0}
-0.07
Notes: The -find option may only be used to find the index of
an incoming message. It returns -1 if there is no message
from the specified source element and message type.
The -count option may be useful if you want to loop over the
index in order to find multiple messages which meet some
specification.
See also:
addmsg ,
deletemsg ,
showmsg
Routine Name: getparamGA
Description: gets the value of a parameter in a paramtableGA object as a
floating-point number.
Usage: getparamGA path table param
path: The location of the paramtableGA object in the
element hierarchy.
table: The parameter table to be accessed.
param: The location of the desired parameter in the
table.
Return value: a float, representing the parameter value desired.
Example: float val
val = {getparamGA /GA 10 1}
This returns the second parameter (zero-indexed) from
the tenth parameter table in the paramtableGA object
called /GA. The value is stored in the
variable val.
Notes: The reason for having this routine and setparamGA is that
the parameter table array in paramtableGA objects is in an
object-specific binary form (optimized for the genetic
algorithm method) and thus can't be viewed or set directly
using the showfield, getfield or setfield commands (at
least not meaningfully).
This routine and setparamGA are hacks; ultimately they should
be made obsolete by overloading the SET and SHOW actions of
the paramtableGA object.
See also: Parameter Search (
Param ),
paramtableGA ,
setparamGA
Routine Name: getpath
Description: Returns subpart of full element pathname.
Usage: head-string = {getpath name -head}
tail-string = {getpath name -tail}
head-string full path leading to element, without actual
element name
tail-string only actual element name, without full path
name an element pathname
Example: genesis > echo {getpath /cell/soma/Na_channel -head}
/cell/soma/
genesis > echo {getpath /cell/soma/Na_channel -tail}
Na_channel
Notes: You use getpath to extract the parent or head of a path.
See also:
el ,
pwe ,
stack
Routine Name: getsolvechildname
Description: Returns the name of the child stored at the index value
inside the hines solver.
Usage: getsolvechildname hsolve_element index
Example:
genesis > showfield /cell/solve nchildren
[ /cell/solve ]
nchildren = 2
genesis > echo {getsolvechildname /cell/solve 1}
/cell/soma/K_mit_tchan
genesis > echo {getsolvechildname /cell/solve 2}
/cell/soma/Na_mit_tchan
Notes: Mainly used for debugging.
See also:
hsolve ,
getsolvecompname ,
findsolvefield
Routine Name: getsolvecompname
Description: Returns the name of the compartment stored at the index value
inside the hines solver.
Usage: getsolvecompname hsolve_element index
Example:
genesis > showfield /cell/solve ncompts
[ /cell/solve ]
ncompts = 1
genesis > echo {getsolvecompname /cell/solve 0}
soma[0]
Notes: Mainly used for debugging.
See also:
hsolve ,
getsolvechildname ,
findsolvefield
Routine Name: getstat
Description: Returns current simulation time, step number, or memory used
Usage: getstat -time -step -memory
Example:
genesis > echo {getstat -time}
0.1000500023
genesis > echo {getstat -step}
2001
genesis > {getstat -memory}
3704068
Notes:
See also:
showstat
Routine Name: getsyncount
Description: This function is used to count SPIKE messages coming from a
particular presynaptic element and/or synapses on a
particular postsynaptic element. If both the presynaptic
and postsynaptic elements are specified this function
returns the number of connections between the two i.e. the
number of SPIKE messages from the presynaptic element which
are sent to the given postsynaptic element. This function
is often used inside a loop to set fields in synapses
between specific elements to particular values.
Usage: getsyncount [presynaptic-element] [postsynaptic-element]
presynaptic-element The element sending SPIKE messages to
postsynaptic targets.
postsynaptic-element The synchan or derived element which
receives SPIKE messages.
Example: // Set the weights of all synapses that receive SPIKE messages
// from a given source to 10.0
int i
str dest
int nsyn = {getsyncount /input[0]/spike}
for (i = 0; i = {nsyn}; i = i + 1)
dest = {getsyndest /input[0]/spike {i}}
index = {getsyndest /input[0]/spike {i} -index}
setfield {dest} synapse[{index}].weight 10.0
end
Notes: Synchans have an "nsynapses" field which holds a count of the
number of synapses on a given element; this can be used instead
of getsyncount when getting synapse counts for postsynaptic
elements.
See also:
getsynindex ,
getsynsrc ,
getsyndest , BoG chapter 18
Routine Name: getsyndest
Description: Returns a string which is the path of the postsynaptic
element which receives the nth SPIKE message sent by the
given presynaptic element. Can also return the index of
the synapse on this element.
Usage: getsyndest presynaptic-element spikemsg-number -index
presynaptic-element The element sending SPIKE messages to
postsynaptic targets.
spikemsg-number The number of the SPIKE message whose
destination we want. This can be obtained by getmsg
or showmsg.
-index This option returns the index of the synapse which
receives the SPIKE message on the destination
element.
Example: str dest = {getsyndest input[0]/spike 0}
int index = {getsyndest input[0]/spike 0 -index}
setfield {dest} synapse[{index}].weight 10.0
Notes: getsynindex can also be used to get the index of a synapse
if you know the names of the pre- and postsynaptic elements.
See also:
getsyncount ,
getsynindex ,
getsynsrc , BoG chapter 18
Routine Name: getsynindex
Description: getsynindex is used to find the index of synapses between
particular presynaptic and postsynaptic elements.
Usage: getsynindex presynaptic-element postsynaptic-element
[-number n]
presynaptic-element The element sending SPIKE messages to
postsynaptic targets.
postsynaptic-element The synchan or derived element
receiving the SPIKE message from the presynaptic
element.
-number n If there is more than one synapse between the
given pre- and postsynaptic elements, this option
will return the index of the nth such synapse.
This option will rarely be necessary, since
usually there is at most one synapse between a
given presynaptic and postsynaptic element.
Example: int index = {getsynindex /input[0]/spike /cell/soma/Ex_channel}
if (index >= 0)
setfield /cell/soma/Ex_channel synapse[{index}].weight 10.0
end
Notes: If the desired synapse does not exist a value of -1 is
returned.
See also:
getsyncount ,
getsynsrc ,
getsyndest , BoG chapter 18
Routine Name: getsynsrc
Description: Returns a string which is the path of the presynaptic
element sending the SPIKE message to the synapse of the
postsynaptic element with the given index.
Usage: getsynsrc postsynaptic-element index
postsynaptic-element The synchan or derived element
receiving the SPIKE message from the source element.
index The index of the synapse on a synchan or derived element
whose source you want.
Example: str src = {getsynsrc /cell/soma/Ex_chan 0}
if (src == "input[0]/spike")
setfield /cell/soma/Ex_chan synapse[0].weight 10.0
else
setfield /cell/soma/Ex_chan synapse[0].weight 0.0
end
Notes:
See also:
getsyncount ,
getsynindex ,
getsyndest , BoG chapter 18
Routine Name: h
Description: Displays the contents of the command-history buffer.
Usage: h
h [start [end] ]
start number of first command to list (default: 1)
end number of last command to list (default:
number of most recently issued command)
Example: genesis > h 1 5
1 echo { x }
2 floatformat %0.5g
3 echo { x }
4 floatformat %2.5g
5 echo { x }
Notes: Every command typed into the simulator at the keyboard is
saved into a command buffer referred to as the 'history'.
Commands saved in the history buffer can be re-executed using
command recall mechanisms built into the script language. The
h routine displays the list of all commands in the range
specified. Typing h without any arguments will print the
entire history buffer. Typing h with a range will print all
of the commands executed in the range specified.
The following history recall functions are also built into the
script language:
Command Example Description
--------------------------------------------------------------
!! !! Re-execute last command.
!n !5 Re-execute the fifth command entered.
!string !echo Re-execute the last command whose first
chars match the string entered.
ctrl-P ctrl-P Retrieve previous command in the history
buffer. Repeat ctrl-P's to scan backwards
through previous commands.
ctrl-N ctrl-N Scan forward, after executing ctrl-P's,
to echo next command.
Routine Name: help
Description: Displays help on GENESIS topics.
Usage: help [ topic [help-directory-list] ]
topic string (typically a routine name)
help-directory list of directories containing
ascii help files
Example: genesis > help CONTENTS | more
genesis > help synchan | more
genesis > help myroutine /myhelpdirectory /basichelp
Notes: Help searches specified help directories for documentation on
the given topic (typically a routine name). If no directory
is specified then the current default help directory (the last
help directory referenced) will be used. If no default help
directory exists (e.g., when help is used for the first time),
the value of the environment variable GENESIS_HELP is used as
the help directory (cf. setenv, getenv); this variable is
set to the genesis/Doc directory, using the full path
given in the default .simrc file.
As most of these files are longer than a single screen, it is
best to pipe the output into "more".
If no topic is given, the genesis/Doc/README file is printed
to the screen. This gives further information about the
current version of the one-line help, the GENESIS Reference
Manual, and the hypertext documentation.
[for help writers:]
The Help facility allows text to be included from other files
(use ## as first characters on a line, followed by the local
file name; you can omit the .txt suffix). For instance, you
might create the following file trig.txt:
TRIG Routines
##cos
##sin
##tan
When you type "help trig" to view this file, instead of seeing
the text "##cos" etc., the contents of the file cos.txt would
be read in and displayed at that point in the file.
Routine name: initdump
Description: Initializes the simulation dumping/undumping system. Normally
generated by default in a dumpfile, but it can be overridden
from the script to set various flags.
Usage: initdump -version # -ignoreorphans # -allowmsgdup
-version #: The version number of the dumpfile. Allows it to
read old dumpfiles. Each dumpfile keeps its version number in
its header. This is relevant only for reading in dumpfiles, as
simdump always dumps using the latest version.
-ignoreorphans #: # can be 0 or 1. Orphans are elements
without a parent. If ignoreorphans is 1, then simundump will
simply skip over orphan elements. Otherwise it will complain.
-allowmsgdup: When a dumped simulation is being loaded onto
an existing one, then some messages are likely to be duplicated.
Normally such duplicate messages are detected and are NOT
created. This flag disables the mechanism that protects
dumps from duplicating msgs when the elements specified in
the dumps overlap.
Example: Here is a little dumpfile using initdump that recreates a
simple 2-compartment model, and ignores the orphan element
/x/y/z.
============================================================
//genesis
initdump -version 3 -ignoreorphans 1
simobjdump neutral
simobjdump compartment activation Vm previous_state \
Im Em Rm Cm Ra inject dia len initVm
simundump neutral /x/y/z 0
simundump neutral /a 0
simundump compartment /a/compt 0 0 0.6632976405 0.6632942696 \
-0.3333315551 0 1 1 1 1 0 0 0
simundump neutral /b 0
simundump compartment /b/compt 0 0 0.3299660931 0.3299627243 \
0.3333349228 0 1 1 1 0 0 0 0
addmsg /b/compt /a/compt RAXIAL Ra Vm
addmsg /a/compt /b/compt AXIAL Vm
enddump
// End of dump
============================================================
Notes:
See also:
enddump ,
simdump ,
simobjdump ,
simundump
Routine Name: initparamBF
Description: Initializes a number of fields involving a single parameter
for the paramtableBF object.
Usage: initparamBF path param type range center label
path: The location of the parameter search object in
the element hierarchy.
param: The numerical index of the parameter whose ranges
etc. are to be set.
type: The type of the parameter; 0 = additive,
1 = multiplicative.
range: The range of the parameter. For additive
parameters, this is a maximum offset from the
center value; for multiplicative parameters, it's
a maximum scaling factor. In other words, for
additive parameters the full parameter range is
[center - range, center + range] while for
multiplicative parameters it's equal to
[center / range, center * range]. The range
value must be >= 0.
center: The original value of the parameter, which is also
the center of the range to be searched over.
label: A string which is the name of the parameter. This
is useful for identifying the parameter in a text
file output by the SAVEBEST or DISPLAY actions.
Return value: int; 0 for failure and 1 for success.
Examples: initparamBF /BF_object 0 1 2.0 1.0 "Na Gbar"
This sets parameter 0 to be a multiplicative parameter
(type 1) with a range of 2.0 (from 0.5 to 2.0 times the
center value) with a center value of 1.0. The label
indicates that this parameter represents the maximum
conductance of a sodium channel. The label is just for
reference and has no effect on the search process.
Notes: This routine (and the other initparamXX routines) are
shortcuts to set a number of parameter-related fields
simultaneously. All of these fields can also be set
manually, but it's usually much more convenient to use
these functions.
See also: Parameter Search (
Param ),
Paramtable ,
paramtableBF
Routine Name: initparamCG
Description: Initializes a number of fields involving a single parameter
for the paramtableCG object.
Usage: initparamCG path param type range center label
path: The location of the parameter search object in
the element hierarchy.
param: The numerical index of the parameter whose ranges
etc. are to be set.
type: The type of the parameter; 0 = additive,
1 = multiplicative.
range: The range of the parameter. For additive
parameters, this is a maximum offset from the
center value; for multiplicative parameters, it's
a maximum scaling factor. In other words, for
additive parameters the full parameter range is
[center - range, center + range] while for
multiplicative parameters it's equal to
[center / range, center * range]. The range
value must be >= 0.
center: The original value of the parameter, which is also
the center of the range to be searched over.
label: A string which is the name of the parameter. This
is useful for identifying the parameter in a text
file output by the SAVEBEST or DISPLAY actions.
Return value: int; 0 for failure and 1 for success.
Examples: initparamCG /CG_object 0 1 2.0 1.0 "Na Gbar"
This sets parameter 0 to be a multiplicative parameter
(type 1) with a range of 2.0 (from 0.5 to 2.0 times the
center value) with a center value of 1.0. The label
indicates that this parameter represents the maximum
conductance of a sodium channel. The label is just for
reference and has no effect on the search process.
Notes: This routine (and the other initparamXX routines) are
shortcuts to set a number of parameter-related fields
simultaneously. All of these fields can also be set
manually, but it's usually much more convenient to use
these functions.
See also: Parameter Search (
Param ),
Paramtable ,
paramtableCG
Routine Name: initparamGA
Description: Initializes a number of fields involving a single parameter
for the paramtableGA object.
Usage: initparamGA path param type range center label
path: The location of the parameter search object in
the element hierarchy.
param: The numerical index of the parameter whose ranges
etc. are to be set.
type: The type of the parameter; 0 = additive,
1 = multiplicative.
range: The range of the parameter. For additive
parameters, this is a maximum offset from the
center value; for multiplicative parameters, it's
a maximum scaling factor. In other words, for
additive parameters the full parameter range is
[center - range, center + range] while for
multiplicative parameters it's equal to
[center / range, center * range]. The range
value must be >= 0.
center: The original value of the parameter, which is also
the center of the range to be searched over.
label: A string which is the name of the parameter. This
is useful for identifying the parameter in a text
file output by the SAVEBEST or DISPLAY actions.
Return value: int; 0 for failure and 1 for success.
Examples: initparamGA /GA_object 0 1 2.0 1.0 "Na Gbar"
This sets parameter 0 to be a multiplicative parameter
(type 1) with a range of 2.0 (from 0.5 to 2.0 times the
center value) with a center value of 1.0. The label
indicates that this parameter represents the maximum
conductance of a sodium channel. The label is just for
reference and has no effect on the search process.
Notes: This routine (and the other initparamXX routines) are
shortcuts to set a number of parameter-related fields
simultaneously. All of these fields can also be set
manually, but it's usually much more convenient to use
these functions.
See also: Parameter Search (
Param ),
Paramtable ,
paramtableGA
Routine Name: initparamSA
Description: Initializes a number of fields involving a single parameter
for the paramtableSA object.
Usage: initparamSA path param type range center scalemod label
path: The location of the parameter search object in
the element hierarchy.
param: The numerical index of the parameter whose ranges
etc. are to be set.
type: The type of the parameter; 0 = additive,
1 = multiplicative.
range: The range of the parameter. For additive
parameters, this is a maximum offset from the
center value; for multiplicative parameters, it's
a maximum scaling factor. In other words, for
additive parameters the full parameter range is
[center - range, center + range] while for
multiplicative parameters it's equal to
[center / range, center * range]. The range
value must be >= 0.
center: The original value of the parameter, which is also
the center of the range to be searched over.
scalemod: Modifies the range of the initial points on the
simplex. See the paramtableSA doc file for more
details.
label: A string which is the name of the parameter. This
is useful for identifying the parameter in a text
file output by the SAVEBEST or DISPLAY actions.
Return value: int; 0 for failure and 1 for success.
Examples: initparamSA /SA_object 0 1 2.0 1.0 1.5 "Na Gbar"
This sets parameter 0 to be a multiplicative parameter
(type 1) with a range of 2.0 (from 0.5 to 2.0 times the
center value) with a center value of 1.0 and a scalemod
value of 1.5. The label indicates that this parameter
represents the maximum conductance of a sodium channel.
The label is just for reference and has no effect on the
search process.
Notes: This routine (and the other initparamXX routines) are
shortcuts to set a number of parameter-related fields
simultaneously. All of these fields can also be set
manually, but it's usually much more convenient to use
these functions.
See also: Parameter Search (
Param ),
Paramtable ,
paramtableSA
Routine Name: initparamSS
Description: Initializes a number of fields involving a single parameter
for the paramtableSS object.
Usage: initparamSS path param type range center label
path: The location of the parameter search object in
the element hierarchy.
param: The numerical index of the parameter whose ranges
etc. are to be set.
type: The type of the parameter; 0 = additive,
1 = multiplicative.
range: The range of the parameter. For additive
parameters, this is a maximum offset from the
center value; for multiplicative parameters, it's
a maximum scaling factor. In other words, for
additive parameters the full parameter range is
[center - range, center + range] while for
multiplicative parameters it's equal to
[center / range, center * range]. The range
value must be >= 0.
center: The original value of the parameter, which is also
the center of the range to be searched over.
label: A string which is the name of the parameter. This
is useful for identifying the parameter in a text
file output by the SAVEBEST or DISPLAY actions.
Return value: int; 0 for failure and 1 for success.
Examples: initparamSS /SS_object 0 1 2.0 1.0 "Na Gbar"
This sets parameter 0 to be a multiplicative parameter
(type 1) with a range of 2.0 (from 0.5 to 2.0 times the
center value) with a center value of 1.0. The label
indicates that this parameter represents the maximum
conductance of a sodium channel. The label is just for
reference and has no effect on the search process.
Notes: This routine (and the other initparamXX routines) are
shortcuts to set a number of parameter-related fields
simultaneously. All of these fields can also be set
manually, but it's usually much more convenient to use
these functions.
See also: Parameter Search (
Param ),
Paramtable ,
paramtableSS
Routine Name: input
Description: Obtains input from the user at the GENESIS prompt.
Usage: value = input [ prompt-string [ default-value] ]
value value entered by user
prompt-string string to use to prompt user for input
(default: "?"; to use a string that includes
spaces, include the string in quotation marks;
in any case, two blank spaces are always
automatically shown after the prompt string)
default-value value to use if user responds by just pressing
the RETURN key (to use a string that includes
spaces, include the string in quotation marks)
Example: genesis > int x = {input "Value for x:" 3}
(def = 3) Value for x: 666
genesis > echo { x }
666
Notes: The input routine can be used to get input from the keyboard.
If supplied, the default-value is displayed before the
prompt-string, in the form:
(def = <default-value>) prompt-string
Routine Name: isa
Description: Tests to see if an element is derived from a specified object.
Usage: isa-flag = {isa object element}
isa-flag returned as 1 if element is derived from
object; returned as 0 otherwise
object name of a GENESIS object (element-type)
element name or full pathname of element to test
Example: if ({isa symcompartment /cell/dendrite})
echo "This is a symmetric compartment"
end
genesis > create compartment /soma
genesis > echo {isa compartment /soma}
1
genesis > echo {isa symcompartment /soma}
0
Notes: The test will also be true if the element is created from
an extended object that is derived from the specified
object.
See also:
Extended
Routine Name: le
Description: Displays a list of elements in the element tree.
Usage: le [path] -recursive -type
path pathname of element (default: current
element); path cannot include wildcards
-r recursively display entire tree starting
at given element
-t display object type along with element name
(type will be included in curly braces just
after element name)
Example: genesis > le / -t
*proto {neutral} output {neutral}
cell/ {neutral} data/ {xform}
genesis > le / -r
*proto output
cell/ data/
/cell:
soma
/data:
voltage/ RESET
RUN QUIT
/data/voltage:
x_axis y_axis
title volts
current
Notes: Unlike the listings produced by the analogous operating-system
command "ls", the listings produced by the le routine show
elements not in alphabetical order, but in the order in which
they were created.
In the le listings, items preceded by an asterisk (e.g.,
*proto) will not participate in simulations (see the enable
and disable routines for control of this).
Routine Name: listcommands
Description: Displays a list of routines currently recognized by GENESIS.
Usage: listcommands
Example: genesis > listcommands | more
Available commands:
[routines are listed, one screen at a time]
Notes:
Routine Name: listescape
Description: Lists available escape-key/command-sequence bindings.
Usage: listescape
Example: genesis > listescape
AVAILABLE ESCAPE KEYS
---------------------
[29~ Do REPLACE step<CR>
[28~ Help EXEC commands | more
[18~ F7 EXEC status
[17~ F6 EXEC status -process
[11~ F1 EXEC stop
[3~ Remove REPLACE <^D>
[2~ Insert Here REPLACE <^I>
[1~ Find EXEC execute movebol
[D left arrow REPLACE <^H>
[C right arrow REPLACE <^F>
[B down arrow REPLACE <^N>
[A up arrow REPLACE <^P>
Notes: The listescape routine displays a list of the current escape
key to string bindings which have been created using the
addescape routine (in reverse order of creation).
See also:
addescape
Routine Name: listfiles
Description: Lists ASCII files currently opened by openfiles routine.
Usage: listfiles
Example: genesis > listfiles
OPEN ASCII FILES
-----------------
genesis > openfile run.g r
genesis > listfiles
OPEN ASCII FILES
-----------------
run.g r
Notes:
See also:
openfile
Routine Name: listglobals
Description: Lists currently defined GENESIS global variables and their
current values.
Usage: listglobals [global-symbols] -functions -variables
-variables only show variables (types int, float, str)
-functions only show functions (type function)
(Uses last switch on line; if no switches, shows both
functions and variables. If the name is given, it shows
only that global-symbol.)
Example: genesis > listglobals
int B_SPLINE_FILL = 0
int C_SPLINE_FILL = 1
int LINEAR_FILL = 2
Notes: Four datatypes are recognized in listglobals:
int
float
str
function
See also:
echo ,
Variables ,
Functions
Routine Name: listobjects
Description: Lists available element types.
Usage: genesis > listobjects
Notes: The listobjects routine displays a list of the element types
currently defined within GENESIS. GENESIS comes with an
extensive set of element types already included.
See also:
showobject
Routine Name: log
Description: Returns logarithm (base "e") of number.
Usage: log-value = {log number}
Example: genesis > echo { log 1 }
0
genesis > echo {log {exp 1}}
0.9999999404
genesis > echo {log 0}
-Infinity
Notes: To get the base 10 log of x, use {log {x}}/{log 10}.
See also:
exp
Routine Name: logfile
Description: Activates/deactivates logging of all commands issued in
GENESIS session.
Usage: logfile file-name
logfile -off
file-name name for file in which to save record of
messages typed to or displayed at the GENESIS
shell -- if file already exists, information
will be appended; if file does not exist,
it will be created and information entered
-off flag to deactivate logging
Example: genesis > logfile mylog
logging to 'mylog' at Sat Jun 24 18:44:59 1995
...
genesis > logfile -off
logging done at Sat Jun 24 19:08:08 1995
Notes: The logfile routine is used to activate command line logging.
All commands typed from the keyboard as well as various error
messages reported by the simulator will be saved in the
specified logfile.
See also:
notes
Routine Name: max
Description: Returns maximum value of two numbers.
Usage: maximum-value = {max value1 value2}
Example: genesis > echo {max {tan 0.1} 0.1}
0.1003346741
Notes:
See also:
min
Routine Name: maxerrors
Description: Sets (or displays) number of errors currently allowed before
a simulation is automatically stopped.
Usage: maxerrors [number-of-errors]
Example: genesis > maxerrors
max errors = 10
genesis > maxerrors 30
max errors = 30
Notes: By default, the maximum number of errors allowed before the
system stops a simulation is 10.
See also:
maxwarnings ,
clearerrors
Routine Name: maxwarnings
Description: Sets (or displays) number of warning messages currently
allowed before a simulation is automatically stopped.
Usage: maxwarnings [number-of-warnings]
Example: genesis > maxwarnings
max warnings = 20
genesis > maxwarnings 40
max warnings = 40
Notes: By default, the maximum number of warning messages allowed
before the system stops a simulation is 20.
See also:
maxerrors ,
clearerrors
Routine Name: min
Description: Returns minumum value of two numbers.
Usage: minimum-value = min {value1 value2}
Example: genesis > float x = 33.333
genesis > int y = {x}
genesis > echo {min {x} {y}}
33
Notes:
See also:
max
Routine Name: move
Description: Moves an element and its children from one portion of the tree
to another.
Usage: move src_element dst_element
src_element element to move (if this element has
sub-elements, they too are moved)
dst_element location into which to move src_element (if
dst_element already exists, src_element is
moved beneath it with original name; if
dst_element does not exist, src_element is
given that name as new name)
Example: move /cell1 /cell5
create neutral /network
move /cell[1] /network
Notes: In the example above, if /cell5 does not exist, /cell1 will
be renamed to /cell5. The second example turns /cell[1]
into /network/cell[1].
See also:
copy
Routine Name: msgsubstitute
Description: Allows undump of saved simulation with new message names
Usage: msgsubstitute destobj orig_msg_type new_msg_type field1 ...
Example: objsubstitute xplot fakeplot
msgsubstitute fakeplot PLOT INPUT .
also see Scripts/kinetikit/batch_interface.g
Notes: msgsubstitute is used along with objsubstitute to allow
you to save an object of one type using simobjdump and
simdump, and then use simundump to reload it as a
different type. It allows for example, xgraph and xplot
elements to be saved as neutral and table elements, so
that the simulation can run in batch mode. In the example
above, a real xplot object takes a PLOT message, but we
are using a table as fakeplot, which takes an INPUT
message. Here, the "." represets the same field (the
data to be plotted) originally sent with the PLOT message.
See also:
objsubstitute ,
substituteinfo ,
simobjdump ,
simdump ,
swapdump ,
simundump
Routine Name: notes
Description: Allows user to enter text notes into a file.
Usage: notes [file]
file file into which to put notes (default:
most recent notes file used; if first time
in this GENESIS session, uses file specified
by operating system variable SIMNOTES) -- if
file already exists, notes will be appended;
if file does not exist, it will be created and
notes entered
Example: genesis > notes
using notes file '/myhomedirectory/.notes'
End with '.' alone on the last line
-> running the first tutorial script
-> .
genesis > notes squid_notes
using notes file 'squid_notes'
End with '.' alone on the last line
-> We may want to look at the tutorial for ideas
-> about the implemention of voltage clamp
-> circuitry.
-> .
genesis > more squid_notes
+------------------------------------------------------+
Sat Jun 24 19:14:54 1995
We may want to look at the tutorial for ideas
about the implemention of voltage clamp
circuitry.
genesis >
Notes: You end the note by including a period (.) on a line by itself.
The note is entered into the notes file preceded by a dashed
line and the date and time the entry was made.
See also:
logfile
Routine Name: objsubstitute
Description: Allows undump of saved simulation with new object names
Usage: objsubstitute orig_obj_name new_obj_name
Example: create table fakeplot
// commands to add fields and actions to fakeplot
// to make it look like an xplot
...
addobject fakeplot fakeplot
objsubstitute xplot fakeplot
see Scripts/kinetikit/batch_interface.g
Notes: objsubstitute is used to allow you to save an object of
one type using simobjdump and simdump, and then use
simundump to reload it as a different type. It allows for
example, xgraph and xplot elements to be saved as neutral
and table elements, so that the simulation can run in
batch mode.
See also:
msgsubstitute ,
substituteinfo ,
simobjdump ,
simdump ,
swapdump ,
simundump
Routine Name: openfile
Description: Opens ASCII file for reading or writing.
Usage: openfile filename mode
filename name of existing file to open for access from
other GENESIS file-manipulation routines
mode mode in which to open file:
r to open file for read-only access;
w to open file for write-only access (this
wipes out any content of the file; see Notes);
a to open file for appending to the file
(existing content is not erased, but
writefiles are allowed)
Example: genesis > openfile hello w
genesis > writefile hello 10 20
genesis > openfile oldfile r
genesis > echo { readfile oldfile }
Notes: You can have up to 20 files opened simultaneously.
You can read data from an opened file using the readfile
routine, and write data to the file using the writefile
routine (if the file was opened for writing).
Beware: If you open a file for writing (mode w) that already
has text in it, that text will be DELETED!
See also:
closefile ,
listfiles ,
readfile ,
writefile
Routine Name: planarconnect
Description: Establishes synaptic connections between groups of elements
based on the x-y positions of the elements. This routine
sets up the connections by adding SPIKE messages between the
source and destination objects.
Usage: planarconnect source_elements destination_elements \
-relative \
-sourcemask {box, ellipse} x1 y1 x2 y2 \
-sourcehole {box, ellipse} x1 y1 x2 y2 \
-destmask {box, ellipse} x1 y1 x2 y2 \
-desthole {box, ellipse} x1 y1 x2 y2 \
-probability p
source_elements A wildcarded list of elements which are the
sources of the SPIKE messages. These must be of
class "spiking" and are usually spikegen or
randomspike objects.
destination_elements A wildcarded list of elements which are
the destinations of the SPIKE messages. These must
be synchans or objects derived from synchan.
-relative This option means that connections will be set up
based on the locations of destination objects
relative to source objects. If this option is not
selected, the absolute locations of source and
destination elements will be used to determine
whichconnections are to be set up.
-sourcemask {box, ellipse} x1 y1 x2 y2 -- This specifies a
rectangular or elliptical region from which source
elements are to be taken. If the "box" option is
used, then x1 and y1 are the minimum x and y values
of the region while x2 and y2 are the maximum x and y
values of the region. If the "ellipse" option is
used, then the source region is an ellipse with x1
and y1 representing the center of the ellipse while
x2 and y2 represent the lengths of the principal axes
in the x and y directions respectively. Note that
to choose a circular region x2 and y2 must be equal.
Note also that one or the other of {box, ellipse}
MUST be chosen; leaving both of them out will generate
an error. Finally, one can choose multiple source
regions by having multiple -sourcemask options.
The same conventions are followed for the next three
options.
-sourcehole {box, ellipse} x1 y1 x2 y2 -- This specifies a
rectangular or elliptical region NOT to include in
the source region(s). You can exclude multiple
regions by having multiple -sourcehole options.
-destmask {box, ellipse} x1 y1 x2 y2 -- This specifies a
rectangular or elliptical region to which SPIKE
messages will be sent.
-desthole {box, ellipse} x1 y1 x2 y2 -- This specifies a
rectangular or elliptical region NOT to include in
the destination region(s).
-probability p -- This option causes connections to be
made with a probability p, which must be in the
range [0,1]. This allows probabilistically-connected
networks to be set up.
Example: [From the "Orient_tut" simulation:]
planarconnect /retina/recplane/rec[]/input \
/V1/horiz/soma[]/exc_syn \
-relative \
-sourcemask box -1 -1 1 1 \
-destmask box {-V1_SEPX * 2.4} \
{-V1_SEPY * 0.6} \
{ V1_SEPX * 2.4} \
{ V1_SEPY * 0.6}
Notes: This routine calculates distance using only the x and y
coordinates of the element positions. It is convenient for
objects laid out in planar arrays but ignoring the z
direction is somewhat unrealistic. volumeconnect is almost
identical with planarconnect except that it uses the positions
of elements in three dimensions to specify whether connections
are made or not.
The weights and delays of the connections set up by this
command are typically specified using the planarweight and
planardelay commands, although they can be set up by hand.
See also:
volumeconnect ,
planarweight ,
planardelay ; chapter 18 of the Book of GENESIS (2nd ed.) has a lengthy
discussion on this and related commands.
Routine Name: planardelay
Description: Sets the delay fields on groups of synapses between
specified lists of elements. Most often used to set
delays on groups of synapses that have been set up
by calling the "planarconnect" command. This function
can assign groups of synapses to a fixed delay, can
assign delays in proportion to the distances between
pre- and postsynaptic elements, and can add various
types of randomness to delay values.
Usage: planardelay sourcepath [destination_path] \
-fixed delay \
-radial conduction_velocity \
-add \
-uniform scale \
-gaussian stdev maxdev \
-exponential mid max \
-absoluterandom
sourcepath A wildcarded list of elements which are the
sources of the SPIKE messages connecting the
pre- and postsynaptic elements (i.e. the presynaptic
elements). These must be of class "spiking" and are
usually spikegen or randomspike objects.
destination_path A wildcarded list of elements which must be
synchans or objects derived from synchan. If this
(optional) argument is given, only the delays between
the given set of pre- and postsynaptic elements will
be set by this command. If this argument is not
given, then all the synapses receiving SPIKE messages
from the presynaptic elements will have their delays
set by this command. NOTE: this optional argument is
new and is not documented in the Book of GENESIS.
-fixed delay -- This option sets all the synaptic delays in
question to be equal to "delay".
-radial conduction_velocity -- This option sets the synaptic
delays in question to be proportional to
the distance between the source and destination
elements according to the equation:
delay = radial_distance / conduction_velocity
Where conduction_velocity is usually measured in
meters/sec (SI units). "conduction_velocity"
represents the conduction velocity of the
(hypothetical) axon that the spikes travel down.
For planardelay, the distance is measured as:
distance =
sqrt((x_src - x_dest)^2 + (y_src - y_dest)^2)
where x_src is the x component of the source element,
x_dest is the x component of the destination element,
and so on. Note that the z component is not taken
into account, which is unrealistic. volumedelay
uses the z component as well.
-add This option causes the computed delays to be added to
the preexisting delays in the synapses instead of
overwriting them. This is useful when adding small
synaptic delays, among other uses.
The next four options are used to add random components to the
delays established using the -fixed or -decay options. How
these random components are added to the delays is explained
below.
-uniform scale -- This option gives a random number taken
from a uniform distribution in the range
{-scale, scale}.
-gaussian stdev maxdev -- This option gives a random number
taken from a gaussian distribution centered on zero,
with a standard deviation equal to "stdev" and with
a maximum value of "maxdev". The maximum value is
used to limit the random component to a given range.
-exponential mid max -- This option gives a random number
taken from an exponential distribution with a
minimum value of zero, a 1/e point of "mid" and a
maximum value of "max". This is mainly for backwards
compatibility with genesis 1.4.
-absoluterandom This option alters the way the random number
is combined with the nominal delay to give the actual
delay, as described below.
Once a random component has been created for a given delay,
it is used to set the delay as follows. If the
-absoluterandom option has not been selected the delay is set
to be:
final_delay = delay + (delay * random_number)
Whereas if the -absoluterandom option has been selected then
we have
final_delay = delay + random_number
Thus the default is to have the amount of randomness as a
constant proportion of the delay value.
Example: [modified from the Orient_tut simulation:]
planardelay /retina/recplane/rec[]/input \
-radial {CABLE_VEL} \
-gaussian 0.1 0.3
This command will set the size of the delays of synapses
that are receiving their inputs from
/retina/recplane/rec[]/input. It gives delays equal to the
radial distance between elements divided by the conduction
velocity (CABLE_VEL). It also specifies that gaussian noise
be added to the delays with a mean value of 0.1 (which
represents 10% of the original delay, since -absoluterandom
has not been selected) and a maximum value of 0.3 (which is
30% of the original delay value).
Notes: The "destination_path" optional argument is new and is not
documented in the Book of GENESIS.
This routine calculates distance using only the x and y
coordinates of the element positions. It is convenient for
objects laid out in planar arrays but ignoring the z
direction is somewhat unrealistic. volumedelay is identical
to planardelay except that it uses the positions of elements
in three dimensions to calculate distances and is thus more
realistic.
The delays are never allowed to go negative even if a large
negative random component is added. Negative delays are set
to zero.
If the -add option is chosen, the random component modifies
only the delay added and not the total delay.
See also:
volumedelay ,
planarconnect ,
planarweight ,
syndelay ; Chapter 18
of the Book of GENESIS (2nd ed.) has a lengthy discussion on
this and related commands.
Routine Name: planardelay2
Description:
Description: A faster version of planardelay, which sets the delay fields
on groups of synapses between specified lists of elements.
Most often used to set delays on groups of synapses that have
been set up by calling the "planarconnect" command. This
function can assign groups of synapses to a fixed delay, can
assign delays in proportion to the distances between pre- and
postsynaptic elements, and can add various types of randomness
to delay values.
Usage: planardelay sourcepath destination_path \
-fixed delay \
-radial conduction_velocity \
-add \
-uniform scale \
-gaussian stdev maxdev \
-exponential mid max \
-absoluterandom
Notes: In contrast to planardelay, which can set the delays of all
efferent synapses from the source map when no destination is
given, planardelay2 only sets the delays of the synapses
from the source map to a particular destination map. By
requiring the destination parameter, planardelay2 achieves
faster setup times than planardelay. For further details of
usage and examples, see the documentation for planardelay.
See also:
planardelay ,
planarconnect ,
planarweight ,
planarweight2
Routine Name: planarweight
Description: Sets the weight fields on groups of synapses between
specified lists of elements. Most often used to set
weights on groups of synapses that have been set up
by calling the "planarconnect" command. This function
can assign groups of synapses to a fixed weight, can
assign weights in proportion to the distances between
pre- and postsynaptic elements, and can add various
types of randomness to weight values.
Usage: planarweight sourcepath [destination_path] \
-fixed weight \
-decay decay_rate max_weight min_weight \
-uniform scale \
-gaussian stdev maxdev \
-exponential mid max \
-absoluterandom
sourcepath A wildcarded list of elements which are the
sources of the SPIKE messages connecting the
pre- and postsynaptic elements (i.e. the presynaptic
elements). These must be of class "spiking" and are
usually spikegen or randomspike objects.
destination_path A wildcarded list of elements which must be
synchans or objects derived from synchan. If this
(optional) argument is given, only the weights between
the given set of pre- and postsynaptic elements will
be set by this command. If this argument is not
given, then all the synapses receiving SPIKE messages
from the presynaptic elements will have their weights
set by this command. NOTE: this optional argument is
new and is not documented in the Book of GENESIS.
-fixed weight -- This option sets all the synaptic weights in
question to be equal to "weight".
-decay decay_rate max_weight min_weight -- This option sets
the synaptic weights in question to be proportional to
the distance between the source and destination
elements according to the equation:
weight = (max_weight - min_weight) *
exp(-decay_rate * distance) + min_weight
For planarweight, the distance is measured as:
distance =
sqrt((x_src - x_dest)^2 + (y_src - y_dest)^2)
where x_src is the x component of the source element,
x_dest is the x component of the destination element,
and so on. Note that the z component is not taken
into account, which is unrealistic. volumedelay
uses the z component as well.
The next four options are used to add random components to the
weights established using the -fixed or -decay options. How
these random components are added to the weights is explained
below.
-uniform scale -- This option gives a random number taken
from a uniform distribution in the range
{-scale, scale}.
-gaussian stdev maxdev -- This option gives a random number
taken from a gaussian distribution centered on zero,
with a standard deviation equal to "stdev" and with
a maximum value of "maxdev". The maximum value is
used to limit the random component to a given range.
-exponential mid max -- This option gives a random number
taken from an exponential distribution with a
minimum value of zero, a 1/e point of "mid" and a
maximum value of "max". This is mainly for backwards
compatibility with genesis 1.4.
-absoluterandom This option alters the way the random number
is combined with the nominal weight to give the actual
weight, as described below.
Once a random component has been created for a given weight,
it is used to set the weight as follows. If the
-absoluterandom option has not been selected the weight is set
to be:
final_weight = weight + (weight * random_number)
Whereas if the -absoluterandom option has been selected then
we have
final_weight = weight + random_number
Thus the default is to have the amount of randomness as a
constant proportion of the weight value.
Example: [modified from the Orient_tut simulation:]
planarweight /retina/recplane/rec[]/input \
-decay 0.5 10.0 0.1 \
-gaussian 0.1 0.3
This command will set the size of the weights of synapses
that are receiving their inputs from
/retina/recplane/rec[]/input. It gives exponentially decaying
weights with a maximum size of 10.0, a minimum size of 0.1,
and a decay rate of 0.5. It also specifies that gaussian
noise be added to the weights with a mean value of 0.1
(which represents 10% of the original weight, since
-absoluterandom has not been selected) and a maximum value of
0.3 (which is 30% of the original weight value).
Notes: The "destination_path" optional argument is new and is not
documented in the Book of Genesis.
This routine calculates distance using only the x and y
coordinates of the element positions. It is convenient for
objects laid out in planar arrays but ignoring the z
direction is somewhat unrealistic. volumeweight is identical
to planarweight except that it uses the positions of elements
in three dimensions to calculate distances and is thus more
realistic.
The weights are never allowed to go negative even if a large
negative random component is added. Negative weights are set
to zero.
The options -fixed and -decay are mutually exclusive. The
different random options -uniform, -gaussian, and -exponential
are also mutually exclusive.
See also:
volumeweight ,
planarconnect ,
planardelay ; Chapter 18
of the Book of GENESIS (2nd ed.) has a lengthy discussion on
this and related commands.
Routine Name: planarweight2
Description:
Description: A faster version of planarweight, which sets the weight fields
on groups of synapses between specified lists of elements.
Most often used to set weights on groups of synapses that have
been set up by calling the "planarconnect" command. This
function can assign groups of synapses to a fixed weight, can
assign weights in proportion to the distances between pre- and
postsynaptic elements, and can add various types of randomness
to weight values.
Usage: planarweight sourcepath destination_path \
-fixed weight \
-decay decay_rate max_weight min_weight \
-uniform scale \
-gaussian stdev maxdev \
-exponential mid max \
-absoluterandom
Notes: In contrast to planarweight, which can set the weights of all
efferent synapses from the source map when no destination is
given, planarweight2 only sets the weights of the synapses
from the source map to a particular destination map. By
requiring the destination parameter, planarweight2 achieves
faster setup times than planarweight. For further details of
usage and examples, see the documentation for planarweight.
See also:
planarweight ,
planarconnect ,
planardelay , planardelay2
Routine Name: plane
Description: Generates 3-D coordinates for a plane with specified
dimensions and characteristics.
Usage: plane filename x y dx dy [-center cx cy] [-jitter jx jy]
[-normal] [-ellipse] [-hexagonal]
filename name for file into which to put generated
coordinates
x x dimension of rectangular area; if -e option
selected, x axis of ellipsoid area
y y dimension of rectangular area; if -e option
selected, y axis of ellipsoid area
dx spacing in x dimension between points
dy spacing in y dimension between points
-center flag specifying that center of plane should be
set at coordinates (cx,cy) (default: (0,0))
cx x coordinate of center of plane (default: 0)
cy y coordinate of center of plane (default: 0)
-jitter flag specifying that linearly random jitter
should be added to offset coordinates from a
perfect array (jitter in x dimension will vary
in range -jx*dx < jitter < jx*dx; jitter in y
dimension will vary in range
-jy*dy < jitter < jy*dy)
jx jitter in x dimension (as fraction of dx)
(default: 0)
jy jitter in y dimension (as fraction of dy)
(default: 0)
-normal flag specifying that an additional set of 3
coordinates is generated per line, to define
the normal to the surface (this format is
compatible with that read by the cellsheet
routine)
-ellipse flag specifying that generated coordinates
should be restricted to lie in an ellipse with
major axes specified by x,y
-hexagonal (not yet implemented) flag specifying that
generated coordinates should lie in a
hexagonal (rather than rectangular) array
Example: plane planepoints 400e-6 400e-6 100e-6 100e-6 -normal
Notes: All of the cells in the plane have an initial z coordinate of
0.0. (See position for how to change this).
See also:
egg ,
cellsheet
Routine Name: pope
Description: Restores previously stacked ("pushed") element as current
working element.
Usage: pope
Example: genesis > pwe
/neuron
genesis > pushe /somewhereelse
/somewhereelse
genesis > pwe
/somewhereelse
genesis > pope
/neuron
genesis > pwe
/neuron
Notes: This routine ("pop element") is analogous to the
operating-system shell "popd" feature for directories.
See also:
pushe ,
stack
Routine Name: position
Description: Sets xyz coordinates of an element and all of its children.
Usage: position element x y z
element element whose coordinates to specify
x, y, z x, y, z coordinates to give element; to
specify absolute coordinates, use a number;
to specify coordinates relative to the current
position, use the form Rnumber; to ignore the
coordinate (leave it as it is), use I
Example: position /neuron 10 20 4.6
position /neuron I I R5.2
position /neuron 1.5 R1.1 I
position /V1/horiz 0 0 {-5 * V1_SEPZ}
Notes: This routine affects the positions of the child elements as
well as that of the parent.
Routine Name: pow
Description: Returns a number raised to a specified power.
Usage: raised-value = {pow number power)
Example: genesis > echo { pow 10 3 }
1000
Notes:
See also:
exp
Routine Name: printargs
Description: Displays its arguments with argument numbers.
Usage: printargs(argument)
Example: genesis > printargs "a b c d"
argc 1 : a,b,c,d
genesis > printargs a b c d
argc 1 : a
argc 2 : b
argc 3 : c
argc 4 : d
Notes:
See also:
argc ,
argv ,
arglist ,
getarg
Routine Name: printenv
Description: Displays value of operating-system environmental variable.
Usage: printenv environment-variable
Example: genesis > printenv SIMPATH
SIMPATH=. /usr/genesis/startup
Notes: This is a GENESIS implementation of the operating system
command printenv, which displays the value of a particular
operating system environmental variable. Unlike its
operating-system counterpart, printenv from within GENESIS
requires that you supply a variable name (outside of GENESIS,
printenv with no arguments displays the list of all your
environmental variables).
Printenv sends its output directly to the screen. If you need
to capture the information that printenv displays in a GENESIS
variable, use the getenv routine instead.
See also:
getenv ,
setenv
Routine Name: pushe
Description: Saves current working element on stack (for later retrieval
using pop), with option to go to new current working element.
Usage: pushe [path]
path pathname of element to make new current
working element (default: leave pushed
element as current working element)
Example: genesis > ce /output
genesis > pushe /mitral
/mitral
genesis > pwe
/mitral
genesis > ce /
genesis > pope
/output
Notes: This routine ("push element") is analogous to the
operating-system shell "pushd" feature for directories.
pushe is used to change element to a new working element while
saving the location of the current working element on a stack.
The pope routine can then be used to return to the element path
stored on the stack.
See also:
pope ,
stack
Routine Name: putevent Description: Used to place events into a buffer class element Usage: putevent buffer time amplitude [time amplitude] Example: create playback /test putevent /test 10 10.0 20 0.0 30 30.0 40 0.0 50 50.0 60 0.0See also: playback
Routine Name: pwe
Description: Displays full pathname of current working element.
Usage: pwe
Example: genesis > pwe
/neuron/test
genesis > ce ..
/neuron
Notes: The pwe routine prints the path of the current working element
in the GENESIS element hierarchy. (This routine is analogous
to the operating-system command "pwd", which prints the current
working directory.)
See also:
ce
Routine Name: quit Description: Exits from GENESIS, terminating any simulation in progress. Usage: quit Notes: Alias for exit routine.
Routine Name: rand
Description: Returns a random number falling in a specified range.
Usage: number = { rand lo hi}
Example: genesis > echo { rand 0 1 }
0.2742720246
genesis > echo { rand 0 1 }
0.5690608621
genesis > echo { rand 0 100 }
32.53029251
Notes:
See also:
randseed
Routine Name: randcoord
Description: Shuffles positions of compartments in a neuron.
Usage: randcoord element fraction [-electrical] [-channel]
element name of element to shuffle
fraction fractional amount of shift
-electrical flag for scaling electrical properties with
changes in length of compartment
-channel flag for scaling conductance of channels with
changes in length of compartment (currently,
only hh_channels and channelC2s are recognised)
Example: randcoord /cell 0.1 -electrical
Notes: Shuffles around the positions of compartments in a neuron,
based on messages, to make the cell look more natural. If the
given element is not a compartment, it looks for children that
are compartments without incoming AXIAL messages, i.e. somas.
If the given element is a compartment, it starts the traversal
at the compartment itself. Having found the root elements, it
then traverses them by their message trees, relatively
positioning the children.
See also:
relposition
Routine Name: randseed
Description: Initializes random-number generator with new random seed.
Usage: randseed [seed]
Example: genesis > echo {randseed}
803971369
genesis > randseed 54321
WARNING from init_rng: changing global seed value!
Independence of streams is not guaranteed
Notes: Re-seeding the random-number generator with different values
insures that a simulation using commands or objects based on
random numbers (e.g. rand or randomspike) produces different
results each time that it is run. Likewise, re-seeding with
the same value will guarantee that your results are
reproducible. If no argument is given, a seed is chosen using
the system clock, otherwise the argument is used as the seed.
The randseed command sets the seed of both the default
Numerical Recipes genenerator and the SPRNG generator,
regardless of which one has been made active by the setrand
command. The warning message shown in the example above
is generated by the SPRNG generator, and should not be
a cause for concern.
See also:
setrand ,
rand
Routine Name: readcell
Description: Creates a model neuron from a description in a cell parameter
file.
Usage: readcell filename cellname -hsolve -prand SDlen SDdia
-rand SDlen SDdia -split Number -lambdasplit maxl
filename name of the cell descriptor file
(should end with extension .p)
cellname name of the neutral element to be at the
head of the tree of elements which comprise
the cell
-hsolve create cellname as an hsolve element
Example: readcell cell.p /cell
readcell cell.p /hcell -hsolve
"cell.p" contains:
*relative
*cartesian
*asymmetric
*set_compt_param RM 0.33333
*set_compt_param RA 0.3
*set_compt_param CM 0.01
*set_compt_param EREST_ACT -0.07
// For the soma, use the leakage potential (-0.07 + 0.0106) for Em
*set_compt_param ELEAK -0.0594
soma none 30 0 0 30 Na_squid_hh 1200 K_squid_hh 360 spike 0.0
// The dendrite has no H-H channels, so ELEAK = EREST_ACT
*set_compt_param ELEAK -0.07
dend soma 100 0 0 2 Ex_channel 0.795775
Notes:
The first example above will produce the element tree
/cell/soma:
Na_squid_hh K_squid_hh spike
/cell/dend:
Ex_channel
with the maxium channel conductances scaled by the area of the
compartment. Here, "/cell" will be a neutral element. In the second
example, "/hcell" will be an hsolve element. This is the preferred way of
creating a cell which is to be taken over by the Hines solver, as it
automatically creates the hsolve element as the root of the element tree
and sets the path for the elements to be solved. Note that, starting with
GENESIS version 2.2, it is necessary to provide the full path to the cell
when using readcell to directly create an hsolve. (e.g. you can't use
"readcell cell.p hcell -hsolve", even if "/" is the current working
element.)
In cartesian coordinates, the format for each compartment parameter line
in a cell parameter file is
name parent x y z dia chan dens [chan dens] ...
For polar coordinates, it is
name parent r theta phi dia chan dens [chan dens] ...
Here, 'name' gives the name of the compartment, and 'parent' refers to the
adjacent compartment to which it is connected. 'parent' may be replaced
by '.' to refer to the compartment defined on the preceding line. For
asymmetric compartments, the connection to 'parent' is through the axial
resistance (Ra) of 'name'. The coordinates and diameter (x, y, z, dia)
are in microns, all other units are SI (Meter, Kg, Second, Ampere). In
polar mode 'r' is in microns, theta and phi in degrees. Theta is measured
from the z-axis and phi from the x-axis in the x-y plane. The compartment
length, which is not stated explicitly, is calculated from the coodinates
of the compartment and its parent.
'chan' is the name of one of the channel prototypes under the neutral
element '/library'. At present, the supported channel types are
hh_channel, tabchannel, tab2Dchannel, tabcurrent, vdep_channel, synchan,
hebbsynchan, ddsyn, receptor2, manuelconduct, and graded. 'chan' may also
refer to the other neural element types: spikegen, Ca_concen, difshell,
difbuffer, concpool, mmpump, and hillpump. Presently, the obsolete
channelC, channelC2, channelC3, and spike objects are also supported.
For channels, 'dens' is the conductance density (Gbar or gmax per unit
compartment area) in Siemens/m^2. If a negative value is specified, the
absolute value is taken, and it is interpreted as the maximum
conductance in Siemens, without scaling by the compartment area.
For spikegen elements, the 'dens' parameter is the 'thresh' field of the
element. For Ca_concen elements, it is the 'B' field, divided by the
volume of the compartment. However, if the 'thick' field of the Ca_concen
element is non-zero, the volume is scaled using the volume of a true shell
of thickness 'thick'. A negative value of 'dens' is used to indicate that
it should be taken as an absolute value of B, without scaling.
A maximum of 30 'chan dens' pairs are allowed in a compartment
specification. The '*compt' option described below provides a way to
overcome this limitation.
Several types of options may be specified in the cell parameter file.
These options start with a '*', and affect all lines following them,
until canceled by the opposite command.
COMPARTMENT COORDINATES
*relative coordinates are relative to parent
*absolute coordinates are absolute (default)
*polar polar coordinates
*cartesian cartesian coordinates (default)
*lambda_warn will issue warning if the electrotonic length of the
compartment (in terms of the space constant, lambda)
is outside the range 0.01-0.20.
*lambda_warn MIN MAX same as above, but uses the range MIN-MAX.
*lambda_unwarn turns off lambda warning (default)
*double_endpoint
allows both endpoints to be explicitly entered for all compartments.
The syntax is:
name parent x0 y0 z0 x y z chans dens... for cartesian mode, and
name parent r0 t0 p0 r t p chans dens... for polar mode.
The double endpoint mode has two main uses. First, when one is adding
dendrites to a spherical compartment like a soma, one wants the
dendrite to begin at the edge of the sphere, not in the middle. The
double endpoint mode allows the user to attach the cylinder at any
desired point. While this does not matter electrically, the cell will
be prettier when displayed with xcell.
Second, this allows the anatomical (not electrical) attachment of
dendrites in the middle of another compartment rather than at an
endpoint. This flexibility may be particularly important for modeling
invertebrate neurons, whose large process diameters often mean that
the distance between two branch points is just a tiny fraction of the
electrotonic length constant. The only caveat in using the mode for
this purpose is that the view in xcell gives less information about
how the model is performing electrically. For example, if a branch is
connected in the middle of a compartment anatomically (and thus it
will be displayed as such in the cell viewer), one must remember that
it is not connected electrically at that point, but (presumably) at
the closer endpoint of that compartment.
*double_endpoint_off turns off double endpoint mode
COMPARTMENT SHAPE
*spherical make a spherical compartment
*cylindrical make a cylindrical compartment (default)
*symmetric make symmetric compartments
*asymmetric make asymmetric compartments (default)
PARAMETER VALUES
*set_compt_param variable value
sets one of the following internal variables used by the cell
reader to 'value'. 'value' may be a number, or the name of a
globally defined script variable.
RM specific membrane resistance in ohm*m^2
RA specific axial resistance in ohm*m
CM specific membrane capacitance in farad/m^2
EREST_ACT resting potential in volts (initial Em and initVm)
ELEAK if specified, gives an alternate value for initial Em,
so that Vm will be initialized to initVm (EREST_ACT)
on reset, instead of Em. Otherwise, ELEAK = EREST_ACT.
*set_global variable value
similar to the above, but also sets the value of global script
variables of the same name. However, it does not support the ELEAK
internal variable. If the RM, CM, RA and EREST_ACT global variables
have not been previously declared, readcell will create them.
'variable' may also be the name of any other previously declared
global script variable other than the internal variables listed
above. In this case '*set_global' may be used to set the values of
these script variables.
COMPARTMENT AND CELL PROTOTYPES
*start_cell CELL_NAME start new cell (in separate tree)
*append_to_cell CELL_NAME append to existing cell
*makeproto COMP_NAME converts new cell to prototype configuration
*compt COMP_NAME all following compartments will be copies of
COMP_NAME, including its complete subtree and
messages between its elements, with gmax/Gbar
appropriately scaled (unless 'dens' is
negative). This allows you to avoid repeating
many long strings of channel specifications when
there are many compartments that have the same
channels with the same conductance densities.
It also permits compartments to contain elements
of types other than the ones recognized by
readcell. In this case, create a prototype
compartment that contains the desired channels
or other elements linked by any necessary
messages, and use "*compt" in the cell parameter
file to make additional copies of the
compartment.
These commands are illustrated in Scripts/int_methods/granule.p and
Scripts/examples/pore/markov.
Messages can be specified between elements in different compartment
subtrees by creating and setting an extended field "addmsg#", where "#" is
an integer. This field will contain a string of the form "source
destination message-name [values]", defining the message. For example,
this commonly done to allow readcell to properly set up the needed
messages between calcium channels, Ca_concen elements, and calcium
dependent potassium channels. This is illustrated in
Scripts/neurokit/prototypes/traub91chan.g.
SPINES and BRANCHES
There are a variety of commands used for adding dendritic spines and
branches to compartments. These commands affect the passive structure
of the neuron only.
*memb_factor MEMB_FACTOR scales all membrane surface by this factor
*add_spines DENDR_DIAM SPINE_DENS SPINE_SUR
Adds membrane surface for collapsed spines to all compartments with
dia <= DENDR_DIAM; units: um, 1/um, um^2.
*rand_spines DENDR_DIAM SPINE_DENS SPINE_SURF AV_LENGTH SPINE_FREQ
spine_proto
Like above, but a random number of spines will be attached as copies
of the compartment(s) spine_proto. The number of spines added
depends on SPINE_FREQ and AV_LENGTH. On the average a compartment
with dia <= DENDR_DIAM and len = AV_LENGTH will receive n =
SPINE_FREQ spines. If SPINE_FREQ >= 1.0 then all compartments with
dia <= DENDR_DIAM will receive at least one spine. The dendritic
surface area is still corrected for the 'missing' spines.
(See, for example, Scripts/purkinje/Purk2M9s.p.)
*mrand_spines DENDR_MIN DENDR_DIAM SPINE_DENS SPINE_SURF AV_LENGTH
SPINE_FREQ spine_proto
Like above, but a random number of spines will be attached as copies
of the compartment(s) spine_proto. Number of spines added depends on
SPINE_FREQ and AV_LENGTH. On the average a compartment with
DENDR_MIN < dia <= DENDR_DIAM and len = AV_LENGTH will receive
n=SPINE_FREQ spines. If SPINE_FREQ >= 1.0 then all compartments
with DENDR_MIN < dia <= DENDR_DIAM will receive at least one spine.
The dendritic surface area is still corrected for the 'missing'
spines on dendrites with dia <= DENDR_DIAM.
*fixed_spines DENDR_DIAM SPINE_NUM SPINE_SURF SPINE_SKIP spine_proto
Like above, but a fixed number of spines will be attached as copies
of the compartment(s) spine_proto. Number of spines added is
SPINE_NUM, from this command onward a spine will be added every
SPINE_SKIP compartments (if dia <= DENDR_DIAM) The dendritic surface
area is still corrected for the 'missing' spines.
*mfixed_spines DENDR_MIN DENDR_DIAM SPINE_NUM SPINE_SURF SPINE_SKIP
spine_proto
Like above, but a fixed number of spines will be attached as copies
of the compartment(s) spine_proto. Number of spines added is
SPINE_NUM, from this command onward a spine will be added every
SPINE_SKIP compartments (if DENDR_MIN < dia <= DENDR_DIAM). The
dendritic surface area is still corrected for the 'missing' spines.
*rand_branches MAX_DIA RAND_FREQ NUM_ORDERS POSTFIX NUM_COMPS MIN_L
MAX_L MIN_D MAX_D [NUM_COMPS MIN_L MAX_L MIN_D MAX_D] ...
Adds more branches randomly at the end of dendrites. The routine
assumes that the .p file has a logical order, where each branch
segment is defined in continuing lines and the first segment after a
branchpoint is defined immediately after the segment before the
branchpoint (if this is not the case the things might still work
correctly by the MAX_DIA control). The branching is binary (thus
either 2 or 4 or 8 or ... segments are added. NUM_ORDERS (1-5)
determines the number of branchpoints that are added. For each
branchpoint one gives the MIN_L and MAX_L (length) and MIN_D and
MAX_D (diameter) and NUM_COMPS, the number of compartments per
segment. Adds smartly: will skip thick segments if the existing
dendritic tip is thin and will only add to 'tips' with a diameter <
MAX_DIAM. Frequency of addition of these branches is controlled by
RAND_FREQ (0-1): if RAND_FREQ == 1 all tips smaller than MAX_DIAM
will have branches appended. The name will be the name of the
parent + POSTFIX, indexed from 0 to 2^(NUM_ORDERS-1). For a "full"
addition (to a thick dendritic tip) the number of added compartments
is 2*NUM_COMPS[1] + ... + 2*NUM_COMPS[NUM_ORDERS].
See also:
writecell ,
compartment ,
Scripts/neurokit/README, Scripts/int_methods/granule.p
Routine Name: readfile
Description: Reads a line of data from an opened ASCII file.
Usage: readfile filename -linemode
-linemode option indicating that entire line of file
should be returned as a single string, rather
than as a list of arguments (the latter is the
default)
filename name of ascii file (must be already opened
using r option of openfile routine)
Example:
openfile test w
writefile test 1.0 2.0 3.0
writefile test 4.0 5.0 6.0
writefile test 7.0 8.0 9.0
closefile test
openfile test r
// 1st line as 3 args:
echo {readfile test}
// gives: 1.0 2.0 3.0
// 2nd arg of 2nd line:
echo {getarg {readfile test} -arg 2}
// gives: 5.0
// 3d line as one argument:
echo {getarg {readfile test -l} -arg 1}
// gives: 7.0 8.0 9.0
// using the file Vm1 generated by the MultiCell demo
function processline
int step = {argv 1}
float Vm = {argv 2}
echo "Time step: "{step}
echo "Membrane potential: "{Vm}
end
openfile Vm1 r
processline {readfile Vm1}
processline {readfile Vm1}
.
.
closefile Vm1
Notes: The readfile routine does not alter the file in any way.
See also:
openfile ,
closefile ,
listfiles ,
readfile ,
getarg
Routine Name: reclaim
Description: Reclaims memory from deleted elements
Usage: reclaim
Example: call Na_hh_tchan TABDELETE
delete Na_hh_tchan
reclaim
Notes: Memory from deleted elements is usually freed when the
simulator returns to the command prompt. When running
in batch mode in situations where many elements are being
created and deleted, it may be necessary to use reclaim
to free the memory from deleted elements.
At present, elements containing interpol_structs (tables) do
not free up the memory allocated to the tables, when they are
deleted. Objects that have a TABDELETE action (e.g.
tabchannels) will deallocate this memory, if TABDELETE is
called before the element is deleted. Finally, you have to
give the reclaim command for the memory to actually be freed.
Note that the tables are shared among all tabchannels that are
created by copy or readcell from a prototype. Therefore, you
shouldn't call TABDELETE unless you plan to delete all copies
of the channel.
Care should be taken to ensure that deleted elements
will not be actively executing after reclaim is
called. This should only be a potential problem within
an extended object action function or a widget callback
script. Also, it should be noted that reclaim will
recompute the simulation schedule which could be time
consuming.
See also:
delete ,
Tables
Routine Name: relposition
Description: Positions element and its child compartments based on messages
rather than directory-type parent-child relationships.
Usage: relposition element dx dy dz
element name of element to shift
dx dy dz amount of shift in x, y, and z directions
Example: (Using the traub91 simulation)
genesis > showfield /cell/soma x y z
[ /cell/soma ]
x = -0.001324999961
y = 0
z = 0
genesis > showfield /cell/soma x y z
[ /cell/soma ]
x = 0.09867500514
y = 0.200000003
z = 0.3000000119
genesis > showfield /cell/apical_10 x y z
[ /cell/apical_10 ]
x = -0.001199999941
y = 0
z = 0
genesis > showfield /cell/basal_8 x y z
[ /cell/basal_8 ]
x = 0.09856500477
y = 0.200000003
z = 0.3000000119
Notes: Moves the element and all children by dx, dy, dz. The child
elements are determined from messages rather than parent-child
relationships. This is necessary for handling 'flat' element
structures. When we have a cell loaded by readcell, the
children dendrites cannot be identified by the parent soma, so
this command traverses the AXIAL/RAXIAL compartment messages
to figure out the children to move.
In the example above, the relposition command moved the soma
and all of the basal compartments, but none of the apical
compartments. This is because only the basal compartments are
children of the soma.
See also:
position ,
randcoord
Routine Name: resched
Description: Assigns elements for simulation according to the
current simulation schedule.
Usage: resched
Example: [from startup/schedule.g:]
deletetasks
...
addtask Simulate /##[CLASS=device] -action PROCESS
addtask Simulate /##[CLASS=output] -action PROCESS
resched
Notes: If you have created any new objects you want included in the
current simulation schedule, you need to run resched so that
the new object will be made known to the simulator. This
applies in particular to either compiled or extended objects
that have an INIT or PROCESS action. (However, the reset
command also does an implicit resched.)
In the example, all simulation events are removed from the
schedule, and then new simulation tasks are listed in the
schedule. (Only the last two are shown here.) Finally,
resched is called in order to reread the simulation schedule
and schedule the listed element types for simulation.
See also:
Schedules ,
addtask
Routine Name: reset
Description: Resets simulation to initial conditions.
Usage: reset
Example: genesis > reset
time = 0.000000 ; step = 0
Notes: The reset routine returns the simulation state to its initial
conditions (e.g., the simulation time is set back to 0) and
invokes each enabled element with the RESET action in order
for them to place themselves back in the initial condition
state. You should reset the simulation whenever you are
getting ready to start a new simulation run, or after you
adding new elements to the simulation.
If the initial state of one element depends on the initial
state of another element, you may need to call the RESET
action for specific elements in the proper order -- the reset
routine gives no control over the order in which the elements
are RESET, and the simulator does not check for such
dependencies. (In most cases, you can issue two reset
commands, instead.)
For instance, the object which computes the Nernst equilibrium
potential requires ionic concentrations. The initial potential
therefore relies on the initial ionic concentrations. Thus the
elements which compute the ionic concentrations must be reset
before the elements which compute the concentration-dependent
equilibrium potentials. An example is given in nernst.txt.
It is up to you to determine whether reset order is
important. Also, you should make sure that any objects you
create document the conditions under which these
dependencies arise.
Routine Name: resetsynchanbuffers
Description: resets the size of all synchan event buffers (and event
buffers of objects derived from synchan) to the default
size (specified in the nodes_per_synapse field of the
object).
Usage: resetsynchanbuffers
Example: genesis > resetsynchanbuffers
genesis >
Notes: This command also flushes all the pending events from the
event buffers. This command is never necessary unless
you're running out of memory because there were too
many spikes generated as inputs to synchan objects
This might happen, for instance, if you set up a
simulation incorrectly so that huge numbers of spikes were
generated by mistake. For instance, if the abs_refract field
of a spikegen object is set to zero and the input to the
spikegen crosses threshold then large numbers of spikes
will be generated.
See also:
synchan
Routine Name: restore
Description: Restores element state stored in file with save routine.
Usage: restore file-name
Example: restore mycell.save
Notes: After using the save command, restore may be used to restore
save element field values from a file. This allows you to
resume a long simulation at the point where you left off.
An element must be capable of performing the RESTORE2 action
for its fields to be restored.
See also:
save
Routine Name: rotcoord
Description: Rotates coordinates of elements in 3-D space.
Usage: rotcoord path angle [-x | -y | -z | -axis x y z] [-center]
[-translatekids | -fixkids]
path path of element to be rotated
angle angle (in radians) for rotation
-x rotate about the x axis
-y rotate about the y axis
-z rotate about the z axis
-axis x y z use vector specified by x, y, z coordinates
as the axis of rotation
-center x y z offset center of rotation (default: 0,0,0)
-translatekids have children of selected element translated
parallel to the parent rather than rotated
(default is to rotate)
-fixkids prevent children of selected elements
from being moved
Example: rotcoord /library/cell {-3.1415927/2} -y
Notes: Note that the angle of rotation is in radians, clockwise
about the specified axis. By default, all the children of
the selected element are rotated as well. In the example,
the original cell had the apical dendrite pointing along the
x-axis. This command will rotate it 90 degrees
counterclockwise about the y-axis to point outward along the
z-axis. This is useful when using createmap or cellsheet to
make a grid of cells having their dendrites normal to a
surface.
See also:
cellsheet
Routine Name: round
Description: Rounds decimal number to nearest integer value.
Usage: rounded-value = {round number}
rounded-value returned as integer
number integer or floating-point number
to round
Example: genesis > echo { round 3.333 }
3
genesis > echo { round 3.666 }
4
Notes: This routine converts any number to an integer by rounding
to the nearest whole number.
See also:
trunc
Routine Name: save
Description: Saves current field values for specified element in a file.
Usage: save path file-name -append
path pathname of element for which to save
field values in file
file-name name of file in which to store field values
-append flag specifying that field values should
be appended to file (if omitted, field
values overwrite any existing values in file)
Example: save /cell/## mycell.save
reset // (Or quit and restart genesis)
restore mycell.save
Notes: The save and restore commands are useful when you need to
resume a long simulation at the point where you left off.
However, some of the older simulation objects do not have
the required SAVE2 action which is invoked with save. (The
showobject command will list the actions performed by an
object.) When using hsolve elements in chanmode 2 or 3, one
must also call HSAVE and HRESTORE for the hsolve element.
See also:
restore ,
hsolve
Routine Name: scaletabchan
Description: Performs scaling and offsets of the tabchannel A and B tables
for a specified gate.
Usage: scaletabchan channel-element gate mode sx sy ox oy -duplicate
channel-element name of a the tabcahnnel
gate gate to be modified; one of: X, Y, or Z
sx x-axis (voltage) scale factor
sy y-axis scale factor
ox x-axis (voltage) offset
oy y-axis offset
mode one of: a[lpha] b[eta] t[au] m[inf]
Example: // double (spread out) the voltage range for the Na
// activation alpha rate constant.
scale_tabchan Na X alpha 2.0 1.0 0.0 0.0
// increase the K_dr activation time constant by 20%.
scaletabchan K_dr X tau 1.0 1.2 0.0 0.0
// shift the Na inactivation curve (Y gate) left by 5 mV.
scale_tabchan Na Y minf 1.0 1.0 -0.005 0.0
// increase the K_dr activation time constant by 0.1 sec.
scaletabchan K_dr X tau 1.0 1.0 0.0 0.1
Notes: The tabchannel internal tables for the specified gate are
modified to provide scalings and/or offsets to the voltage
dependent function specified by the mode. Here, alpha and
beta are the Hodgkin-Huxley rate constants, tau is the time
constant for activation or inactivation, and minf is the
steady state activation or inactivation. The effect of
applying these scalings and offsets may be viewed by using the
edit_channel menu of Neurokit.
Note that the scale and offset is always relative to the last
operation, and not to the original values. One can reverse
changes in oy and sy because they just shift and scale the
table values. However, ox and sx perform offsets and scaling
of the horizontal axes by moving data in the tables. This can
cause data to spill out of the ends of the tables and be lost.
Thus, large changes in the x-axis should be avoided, if you
plan to reverse your changes.
In a large compartmental model or large network, one may have
many copies of a particular prototype channel. Usually, one
wants these to behave identically. It is also desirable to
minimize the amount of storage space used by the internal
tables. For these reasons, copies of the channel which are
created by the copy command or by readcell use the same tables
as the original prototype, rather than creating new copies of
the tables. This is true of all objects which contain tabular
fields. Sometimes you may want to change just the one copy of
the channel. In this case, use the "-duplicate" option with
scaletabchan.
See also:
tabchannel ,
Tables .
Routine Name: setclock
Description: Sets time interval (step size) associated with specified clock.
Usage: setclock clock-number value
Example: setclock 0 0.01 // simulation time step in msec
setclock 1 0.05 // plotting interval can be larger
genesis > setclock 0 5.5
changing clock [0] from 1 to 5.5
Notes: The setclock routine is used to set the current value
assigned to the time increment for one of the GENESIS
simulator clocks. These clocks are updated each time a step
is performed.
Clock number 0 is the default clock used by each element to
determine how often it should perform a simulation step. When
components of a simulation run at significantly different time
scales, it may be useful to use other clocks (specified with
useclock) having different time intervals.
See also:
showclocks ,
useclock ,
getclock
Routine Name: setdefault
Description: Sets the default value of an object field.
Usage: setdefault object-name field-name value ...
Example: genesis > setdefault compartment Em -0.07
genesis > create compartment /soma
OK
genesis > showfield /soma Em
[ /soma ]
Em = -0.0700000003
genesis > echo {getdefault compartment Em}
-0.0700000003
Notes: Once you have changed the default value of an object
field, all elements created from that object will
have that field initialized to the new value.
See also:
getdefault
Routine Name: setenv
Description: Set value of operating system environmental variable.
Usage: setenv environment-variable [new-value...]
Example: genesis > setenv SIMPATH . ~/genesis/Scripts/neurokit
SIMPATH=. ~/genesis/Scripts/neurokit
[also see the GENESIS default .simrc file]
Notes: This is a GENESIS implementation of the operating system
command setenv, which lets you set the value of a particular
operating system environmental variable. Unlike its
operating-system counterpart, setenv from within GENESIS
requires that you supply a variable name (outside of GENESIS,
setenv with no arguments displays the list of all your
environmental variables).
Unlike its operating system counterpart, setenv from within
GENESIS displays the change that you make (outside of GENESIS,
setenv just returns you to the prompt with no acknowledgement).
The setenv routine is used most commonly from within GENESIS
to define the DISPLAY and SIMPATH environment variables.
DISPLAY determines the X11 host on which the display is made
and SIMPATH lists the path which the simulator will search
through for script files (cf. where).
See also:
printenv ,
getenv
Routine Name: setfield
Description: Sets value of field in data structure of specified element.
Usage: setfield [pathname] field value [field value ... ...]
pathname name of element; if wildcard path
specification, all elements referred to will
have their fields set to specified values
(default: current working element)
field field in element data structure to which to
assign new value
value value to assign specified field
Example: setfield /soma initVm -70.0
setfield /test[] x 10 y 20 // for all indexed elements test[i]
setfield x 10 // set value for current element
genesis > setfield /neutral_test x 100 y 50
genesis > showfield /neutral_test x y
[ /neural_test ]
x = 100
y = 50
Notes: You can define and add additional fields with the addfield
command. These may then be set with the setfield command
just like the predefined fields.
See also:
getfield ,
getfieldnames ,
showfield
Routine Name: setfieldprot
Description: Set the accessibility level element fields.
Usage: setfieldprot element -readwrite fields ... -readonly fields ...
-hidden fields ...
element element for which to change field protections
-readwrite make the following fields readwrite
-readonly make the following fields readonly
-hidden make the following fields hidden
-debug turn on debugging mode; all hidden fields
are treated as if they were readonly and
any field may be made readwrite
-nodebug turn off debugging mode
Notes: Hidden fields are not presented by showfield and are
not readable in any way. The presence of hidden fields
may be determined using the showobject command.
NOTE: The -debug option is intended to be used when
debugging new objects. Hidden and readonly fields
should not usually be changed to readwrite as these
fields are either private fields or computed by the
object. Setfieldprot will give a warning if a built in
field is being made more accessible than the protection
defined by the built in object. If it is necessary to
use debug mode to run a simulation please email the
GENESIS development group and report the problem.
See also:
addfield ,
showobject ,
Extended
Routine Name: setglobal
Description: Sets the value of a global variable, allowing the name of
the global variable to be held in a string variable.
Usage: setglobal name value
Example:
float RM, RA, CM
create xform /control
create xdialog /control/RM -value 1.0 -script "setglobal RM <value>"
create xdialog /control/RA -value 0.1 -script "setglobal RA <value>"
create xdialog /control/CM -value 0.01 -script "setglobal CM <value>"
xshow /control
Notes:
Often it is useful to use a string variable name to hold the name of a
global variable. For example, one may want to pass the name of a global
variable to a function that declares a global variable, or that sets or
returns its value. However, normal GENESIS syntax for declarations and
assignments does not permit a variable name to be specified by a string
variable. The routines addglobal, getglobal, and setglobal are designed
to overcome this limitation.
The example above shows another use of setglobal to assign the value of
a global variable with the "script" field of an XODUS widget. A normal
assignment statement would not work in this case.
See also:
Variables ,
addglobal ,
getglobal ,
listglobals
Routine Name: setmethod
Description: Sets integration method for elements to use in simulation.
Usage: setmethod [path] method
path path of element for which to set integration
method (if omitted, specified method is
applied to all elements in the simulation)
method integer identifying integration method to use:
-1 Forward Euler
0 Exponential Euler (default)
2 2nd order Adams-Bashforth predictor
3 3rd order Adams-Bashforth predictor
4 4th Adams-Bashforth predictor
5 5th order Adams-Bashforth predictor
10 Backward Euler
11 Crank-Nicholson
Example: setmethod /cell/##[OBJECT=compartment] 2
Notes: The method used is stored within the "object" data structure
of the element. For example:
genesis > showfield /cell/soma object->method
[ /cell/soma ]
object->method = 2
The default Exponential Euler method is a good compromise
between speed, accuracy and ease of use for network models
and single cell models involving a few compartments.
Multi-compartmental models result in numerically "stiff"
equations which are best solved with one of the implicit
(Backward Euler or Crank-Nicholson) methods. The implicit
methods must used in conjunction with the hsolve object,
which takes over the computations of compartments,
tabchannels and other selected element types.
See also:
hsolve
Routine Name: setparamGA
Description: sets the value of a parameter in a paramtableGA object from
a floating-point number.
Usage: setparamGA path table param value
path: The location of the paramtableGA object in the
element hierarchy.
table: The parameter table to be accessed.
param: The location of the desired parameter in the
table.
value: The floating-point value of the parameter.
Return value: a float, representing the parameter value desired.
Example: float val = 10.0
setparamGA /GA_object 10 1 {val}
This sets the second parameter (zero-indexed) from
the tenth parameter table in the paramtableGA object
called /GA_object to 10.0.
Notes: The reason for having this routine and getparamGA is that
the parameter table array in paramtableGA objects is in an
object-specific binary form (optimized for the genetic
algorithm method) and thus can't be viewed or set directly
using the showfield, getfield or setfield commands (at
least not meaningfully).
This routine and getparamGA are hacks; ultimately they should
be made obsolete by overloading the SET and SHOW actions of
the paramtableGA object.
See also: Parameter Search (
Param ),
paramtableGA ,
getparamGA
Routine Name: setpostscript
Description: Sets parameters used to generate postscript output of widgets.
Usage: setpostscript [-maxgray maxgray] [-mingray mingray]
[-inverse inverse-flag] [-dpi screendpi]
[-filename name] [-printer]
Notes: This is an alias for xps.
See also:
xps
Routine Name: setprompt
Description: Sets string to use as prompt for GENESIS shell.
Usage: setprompt prompt-string
prompt-string string to use as shell prompt (default:
"genesis #!", where "!" is replaced by
command number); if you want to use a string
that includes blank spaces, you must include
the prompt in quotation marks to make the
string a single argument (additional
arguments are ignored)
Example: genesis #13 > setprompt tutorial
tutorial > setprompt "tutorial !"
tutorial 15 >
Notes: When starting up GENESIS the command line will appear as a
prompt waiting for user input.
genesis #0 >
The number contained in the prompt refers to the index of the
command which is incremented for each line entered from the
keyboard. This number can be used in conjunction with the
'history' recall mechanism to re-execute commands based on
their index. [Note that GENESIS starts with 0 rather than 1.]
The prompt string displayed in the command interpreter window
can be set using the setprompt routine. Specific simulations
often wish to change the prompt to reflect the nature of the
simulation.
See also:
h
Routine Name: setrand
Description: Selects Numerical Recipes or SPRNG random number generator
Usage: setrand -nr -sprng
-nr Use the Numerical Recipes generator (default)
-sprng Use the SPRNG random number generator
Example: genesis > setrand
Using Numerical Recipes random number generator
genesis > setrand -sprng
Using SPRNG random number generator
Notes:
As of GENESIS version 2.2, SPRNG (the scalable portable random number
generator) has been incorporated into GENESIS to provide faster and higher
quality random numbers, which will be the same across all hardware platforms.
We continue to support use of the Numerical Recipes generator, which is used
by default. In order to use the SPRNG generator, GENESIS must be compiled
with the appropriate lines uncommented in genesis/src/Makefile. (This is done
by default, but the use of SPRNG may be disabled for some platforms on which
it refuses to compile.) This allows you to choose among several algorithms
for random number generation. Lagged Fibonacci is the default, as it is the
fastest and has the longest number sequence.
The setrand command is used to select between the NR or SPRNG generators.
When used with no options, setrand reports the currently used random number
generator.
See also:
randseed ,
rand
Routine Name: setrandfield
Description: Sets an element field to a random value
Usage: | [-uniform low high]
setrandfield path field | [-gaussian mean sd]
| [-exponential mid max]
Example: setrandfield /pyr/pyramidal[]/HH_Na_channel \
X_alpha_V0 -gaussian -40 3
Notes: In the example above (from Scripts/piriform/pyramidal.g),
setrandfield is being used to give some variation to the
voltage dependence of the activation of Na channels used in
all of the pyramidal cells used in the model. In this case,
there is a gaussian distribution about the mean of -40 mV,
with a standard deviation of 3 mV. Another use of the
setrandfield comamnd would be to use it in script function to
be executed as the command of a script_out object, or as the
PROCESS action of an extended object, in order to randomly
change a field at every time step. This would be a way to
inject a noise current into a compartment, for example.
The -uniform option gives a a random number taken from a
uniform distribution in the range "low" to "high".
The -exponential option gives a random number taken from an
exponential distribution with a minimum value of zero, a 1/e
point of "mid" and a maximum value of "max". Versions of
GENESIS prior to 2.2 used a different interpretation of the
two arguments.
See also:
setfield
Routine Name: setsearch
Description: This function allows the user to change which parameters
will be varied in a parameter search and which will stay
constant. It allows users to perform restricted parameter
searches, keeping certain parameters constant while others
are searched over.
Usage: setsearch path [param1] [param2] ... -all -not -add
path: The location of the parameter search object in
the element hierarchy.
param1 etc.: The numerical indices of the parameters to be
varied. All other parameters will be fixed by
default (but see below). There can be any number of
these arguments up to the total number of parameters.
-all: Causes all parameters to be searched over. All
other options or parameter numbers are ignored.
-not: Changes the meaning of the paramX arguments; now
they are parameters NOT to be searched over. All
other parameters are searched over.
-add: Searches over the listed parameters. Also searches
over whatever other parameters whose search flags
were previously on (i.e. equal to 1).
Return value: int; 0 for failure and 1 for success.
Examples: // Search over parameters 0, 4, 8 only.
setsearch /param_object 0 4 8
// Search over all parameters except for 0, 4, and 8.
setsearch /param_object 0 4 8 -not
// Search over all parameters.
setsearch /param_object -all
// Search over parameters 0, 4, and 8 in addition to
// whatever parameters were previously being searched over.
setsearch /param_object 0 4 8 -add
Notes: This routine is just a shortcut way to set the search[]
fields of paramtable objects. Anything this routine can do
can also be done by manually setting these flags. These
flags have the following values: 0 means "don't search this
parameter" while 1 means "do search this parameter".
Limitations: This routine only works for the paramtable objects included
in this library. It will not automatically work for new
objects written by the user without hacking
src/param/param_utils.c
See also: Parameter Search (
Param ),
Paramtable
Routine Name: setupNaCa
Description: Allocates and fills tabcurrent tables with the values needed
to implement the Na-Ca exchanger pump.
Usage: setupNaCa tabcurrent-element gamma Celcius Cain Caout \
Nain Naout -xsize n -xrange min max -ysize n \
-yrange min max
tabcurrent-element This must have been created from a
tabcurrent object.
gamma Parameter representing the fractional
position of the energy barrier within the
membrane, usually taken to be 0.38.
Celsius Temperature in degrees Celsius.
Cain Ca concentration inside the compartment.
Caout Ca concentration outside the cell.
Nain Na concentration inside the compartment.
Naout Na concentration outside the cell.
-xsize xdivs Number of divisions for the x variable
of the tabcurrent I_tab and G_tab tables.
-xrange min max Minimum and maximum values of the x
variable for the I_tab and G_tab tables.
-ysize ydivs Number of divisions for the y variable
of the tabcurrent I_tab and G_tab tables.
-yrange min max Minimum and maximum values of the y
variable for the I_tab and G_tab tables.
Example:
// Assume there is a parent compartment, and a Ca_concen element Ca_conc
create tabcurrent NaCa
setfield NaCa Gindex {VOLT_C1_INDEX}
setfield NaCa Gbar {1.4e-5*compt_area} // kCaNa = 1.4e-5 Amp/(mM^4)/m^2
setupNaCa NaCa 0.38 37 0 2.4 10 125 -xsize 100 -xrange -0.1 0.05 \
-ysize 100 -yrange 0 0.300
addmsg .. NaCa VOLTAGE Vm
addmsg Ca_conc CONCEN1 Ca
addmsg NaCa .. CHANNEL Gk Ek
Notes:
The setupNaCa routine fills the I_tab table of a tabcurrent element with
values of
Cain*Naout^3 * exp((gamma-1)*V*F/(R*T)) - Caout*Nain^3 *exp(gamma*V*F/(R*T))
where F is the Faraday constant (9.6487e4 coul/mol), R is the gas constant
(8.314 volts*coul/(deg K * mol)), and T = Celsius + 273.15. The G_tab table
is filled with values of -dI_tab/dV, to give the slope conductance Gk when
it is scaled by Gbar. The concentrations should be given in mM (millimoles
per liter = moles/m^3).
When the tabcurrent Gbar is set to the compartment area times the constant
kNaCa, this results in the expression for the Na+ - Ca2+ exchanger pump
current given by Equation (6.11) in De Schutter E., and Smolen P., "Calcium
dynamics in large neuronal models", in Methods in neuronal modeling: From ions
to networks (2nd edition), C. Koch and I. Segev editors, pp. 211-250 (1998).
This is similar to the expression used for a similar electrogenic current in
DiFrancesco, D., and Noble, D., "A model of cardiac electrical activity
incorporating ionic pumps and concentration changes", Phil. Trans. Roy. Soc.
London Ser. B 307: 353-398 (1985).
When setting the concentration parameters, either Cain or Caout (but not both)
should be set to zero. The one that is set to zero is expected to be
delivered to the tabcurrent element with a CONCEN1 or CONCEN2 message. In
almost every case, this will be Cain, as it will vary much more than the Ca
concentration outside the cell. The tabcurrent Gindex field should be set to
VOLT_C1_INDEX if the Ca concentration is delivered with a CONCEN1 message, and
VOLT_C2_INDEX if it is delivered with a CONCEN2 message. The voltage V should
be provided by a VOLTAGE message from the compartment that contains the
tabcurrent element.
The -xsize and -ysize parameters give the number of divisions in the tables,
with the first index (corresponding to voltage) running from 0 to xdivs and
the second one (corresponding to Ca concentration) from 0 to ydivs.
See also:
tabcurrent ,
setupghk
Routine Name: setupalpha
Description: Sets up A and B tables of voltage-dependent gates based on
generic equations describing the form of the alpha and beta
rate functions.
Usage: setupalpha channel-element gate AA AB AC AD AF BA BB BC BD BF \
-size n -range min max
channel-element This must be a tabgate or a tabchannel i.e.
a voltage-dependent gate or channel with
tabulated activation functions.
gate The name of the gate (must be X, Y, or Z).
AA-AF Coefficients A to F of the alpha table
(see below).
BA-BF Coefficients A to F of the beta table
(see below).
-size n Number of divisions in the table
(default = 3000).
-range min max Range of the table (default: min = -0.100;
max = 0.050).
This routine makes it easy to set up the A and B tables of
tabulated channels or gates (tabchannel or tabgate objects)
when the equations describing the rate constants alpha and
beta are of the form:
y(x) = (A + B * x) / (C + exp((x + D) / F))
Many standard channels have alpha and beta parameters that can
be cast into this form. In these cases to set up the tables
we can simply call setupalpha with the parameter values as
arguments to the function. Since there are both alpha and
beta variables, we use the coefficients AA-AF to refer to the
alpha variable and BA-BF to refer to the beta variable.
setupalpha calls the TABCREATE action of the tabchannel or
tabgate to allocate tables with n divisions (n + 1 entries)
representing x values from min to max. It then evalutes the
functions at these points to fill the tables.
tabgates have tables for the alpha and beta rate variables, so
these alpha and beta values are used to directly fill the
tables. The gates of a tabchannel each have an A table that
holds alpha values, and a B table that contains alpha + beta.
These tables are filled with A = alpha and B = alpha + beta.
The tables are by default set up in "no interpolation" mode,
which means that the process of finding the correct table
value is simply a lookup operation. With 3000 divisions in
the table (i.e. the table size is 3001) the lookup usually
provides sufficient accuracy. If not, you can override this
behavior; see the tabchannel documentation. The range of the
activation variable is between -0.100 and 0.050 by default.
This is adequate for most voltage-dependent channels, but
can be overridden using the -range option.
Example: from Scripts/neurokit/prototypes/traub91chan.g:
create tabchannel Kdr_hip_traub91
setfield ^ \
Ek {EK} \ // V
Gbar { 150 * SOMA_A } \ // S
Ik 0 \ // A
Gk 0 \ // S
Xpower 1 \
Ypower 0 \
Zpower 0
setupalpha Kdr_hip_traub91 X \
{16e3 * (0.0351 + EREST_ACT)} \ // AA
-16e3 \ // AB
-1.0 \ // AC
{-1.0 * (0.0351 + EREST_ACT) } \ // AD
-0.005 \ // AF
250 \ // BA
0.0 \ // BB
0.0 \ // BC
{-1.0 * (0.02 + EREST_ACT)} \ // BD
0.04 // BF
This command sets up the X gate (activation gate) of Traub's
delayed-rectifier potassium channel (Kdr_hip_traub91).
SOMA_A and EREST_ACT are constants defined in the script
file. Note that the C value for the A table (AC) is -1; this
can cause problems in general but does not cause any problems
here (see below).
Notes: For tabgate elements, which represent only a single gate, the
"gate" argument is ignored, but it should still be given as
X, Y, or Z. The setuptau command is similar to setupalpha,
but uses the state variables tau and minf instead.
If the alpha and beta rate constant of your channel cannot be
described using the above equation, you must fill the tables
with one of the other methods described in the tabchannel
documentation, or The Book of GENESIS, Chapter 19 (2nd ed.).
The rate equation described above has a removable singularity
when C = -1 at the point x = -D (which is, unfortunately, a
common case). In this case the routine may generate
inaccurate results due to roundoff errors. We STRONGLY
RECOMMEND that if you must use a C value of -1 you check the
resulting activation curves by using Neurokit (in the "Edit
Channel" mode) to see if they look reasonable. If they do
not then you will have to define the channel using a script
function as mentioned above. Such a function will result in
a slower setup time for the channel but will be much more
accurate.
See also:
tabchannel ,
tabgate ,
setuptau ,
tweakalpha ,
tweaktau ,
Tables
Routine Name: setupgate
Description: Sets up the internal tables of tabgate or table elements,
based on a generic equation describing the values of the
entries.
Usage: setupgate channel-element table A B C D F -size n \
-range min max -noalloc
channel-element This must be a tabgate or a table
gate The name of the table (must be
alpha or beta for tabgates, "table" for
table elements)
A-F Coefficients A to F of the table
equation (see below).
-size n Number of divisions in the table
(default = 3000).
-range min max Range of the table (default: min = -0.100;
max = 0.050).
-noalloc used to prevent allocation of the table
when the table has already been allocated
with a call to TABCREATE or a previous use
of setupgate
This routine makes it easy to set up the internal tables of
tagate or table elements when the equations describing them
are of the form:
y(x) = (A + B * x) / (C + exp((x + D) / F))
setupgate calls the TABCREATE action of the element
to allocate tables with n divisions (n + 1 entries)
representing x values from min to max. It then evalutes the
functions at these points to fill the tables.
Example: see Scripts/neurokit/prototypes/newbulbchan.g
Notes: The setupgate routine may not be used on tabchannels.
The state equation described above has a removable singularity
when C = -1 at the point x = -D. common case). In this case
the routine may generate inaccurate results due to roundoff
errors.
See also:
setupalpha ,
setuptau ,
Tables
Routine Name: setupghk
Description: Allocates and fills tabcurrent tables with the values needed
to implement the Goldman-Hodgkin-Katz equation.
Usage: setupghk tabcurrent-element charge Celcius Cain Caout \
-xsize n -xrange min max -ysize n -yrange min max
tabcurrent-element This must have been created from a
tabcurrent object.
charge The ionic valence, z.
Celsius Temperature in degrees Celsius.
Cain Ca concentration inside the compartment.
Caout Ca concentration outside the cell.
-xsize xdivs Number of divisions for the x variable
of the tabcurrent I_tab and G_tab tables.
-xrange min max Minimum and maximum values of the x
variable for the I_tab and G_tab tables.
-ysize ydivs Number of divisions for the y variable
of the tabcurrent I_tab and G_tab tables.
-yrange min max Minimum and maximum values of the y
variable for the I_tab and G_tab tables.
Example: create tabcurrent ghk_tab
setfield ghk_tab Gindex {VOLT_C1_INDEX} Gbar 0.0
setupghk ghk_tab 2 {Temp} 0 {CCaO} \
-xsize {tab_xfills} -xrange {tab_xmin} {tab_xmax} \
-ysize {tab_xfills} -yrange {tab_ymin} {tab_ymax}
setfield ghk_tab G_tab->calc_mode {LIN_INTERP}
setfield ghk_tab I_tab->calc_mode {LIN_INTERP}
Notes:
The setupghk routine fills the I_tab table of a tabcurrent element with
values of
-V/(R*T)*(zF)^2(Cain - Caout*exp(-z*F*V/(R*T)))/(1 - exp(-z*F*V/(R*T)))
where z is the charge (ionic valence = 2 for calcium), F is the Faraday
constant (9.6487e4 coul/mol), R is the gas constant (8.314 volts*coul/(deg K *
mol)), and T = Celsius + 273.15. The G_tab table is filled with values of
-dI_tab/dV, to give the slope conductance Gk when it is scaled by Gbar. The
concentrations should be given in mM (millimoles per liter = moles/m^3).
When the tabcurrent Gbar is set to the permeability constant PCa, this results
in the expression for the non-ohmic GHK current given by Equation (6.6) in De
Schutter E., and Smolen P., "Calcium dynamics in large neuronal models", in
Methods in neuronal modeling: From ions to networks (2nd edition), C. Koch and
I. Segev editors, pp. 211-250 (1998). The negative sign here expresses
the GENESIS convention of treating inward currents as positive.
When setting the concentration parameters, either Cain or Caout (but not both)
should be set to zero. The one that is set to zero is expected to be
delivered to the tabcurrent element with a CONCEN1 or CONCEN2 message. In
almost every case, this will be Cain, as it will vary much more than the Ca
concentration outside the cell. The tabcurrent Gindex field should be set to
VOLT_C1_INDEX if the Ca concentration is delivered with a CONCEN1 message, and
VOLT_C2_INDEX if it is delivered with a CONCEN2 message. The voltage V should
be provided by a VOLTAGE message from the compartment that contains the
tabcurrent element. An "ADD_GBAR Gk" message may be sent to the tabcurrent
element from a calcium channel to change the calcium permeability.
The -xsize and -ysize parameters give the number of divisions in the tables,
with the first index (corresponding to voltage) running from 0 to xdivs and
the second one (corresponding to Ca concentration) from 0 to ydivs.
See also:
tabcurrent ,
setupNaCa
Routine Name: setuptau
Description: Sets up A and B tables of voltage-dependent gates based on
generic equations describing the form of the tau (time
constant) and minf (steady state activation) state constants.
Usage: setuptau channel-element gate AA AB AC AD AF BA BB BC BD BF \
-size n -range min max
channel-element This must be a tabgate or a tabchannel i.e.
a voltage-dependent gate or channel with
tabulated activation functions.
gate The name of the gate (must be X, Y, or Z).
AA-AF Coefficients A to F of the tau table
(see below).
BA-BF Coefficients A to F of the minf table
(see below).
-size n Number of divisions in the table
(default = 3000).
-range min max Range of the table (default: min = -0.100;
max = 0.050).
This routine makes it easy to set up the A and B tables of
tabulated channels or gates (tabchannel or tabgate objects)
when the equations describing the state constants tau and
minf are of the form:
y(x) = (A + B * x) / (C + exp((x + D) / F))
Many standard channels have tau and minf parameters that can
be cast into this form. In these cases to set up the tables
we can simply call setuptau with the parameter values as
arguments to the function. Since there are both tau and minf
variables, we use the coefficients AA-AF to refer to the tau
variable and BA-BF to refer to the minf variable.
setuptau calls the TABCREATE action of the tabchannel or
tabgate to allocate tables with n divisions (n + 1 entries)
representing x values from min to max. It then evalutes the
functions at these points to fill the tables.
tabgates have tables for the alpha and beta rate variables, so
the tau and minf values are used to calculate alpha = minf/tau
and beta = (1 - minf)/tau, and fill these tables. The gates of
a tabchannel each have an A table that holds alpha values, and
a B table that contains alpha + beta. These tables are filled
with A = minf/tau and B = 1/tau.
The tables are by default set up in "no interpolation" mode,
which means that the process of finding the correct table
value is simply a lookup operation. With 3000 divisions in
the table (i.e. the table size is 3001) the lookup usually
provides sufficient accuracy. If not, you can override this
behavior; see the tabchannel documentation. The range of the
activation variable is between -0.100 and 0.050 by default.
This is adequate for most voltage-dependent channels, but
can be overridden using the -range option.
Example: see Scripts/neurokit/prototypes/newbulbchan.g
Notes: For tabgate elements, which represent only a single gate, the
"gate" argument is ignored, but it should still be given as
X, Y, or Z. The setupalpha command is similar to setuptau,
but uses the rate variables alpha and beta instead.
If the tau and minf state constant of your channel cannot be
described using the above equation, you must fill the tables
with one of the other methods described in the tabchannel
documentation, or The Book of GENESIS, Chapter 19 (2nd ed.).
The state equation described above has a removable singularity
when C = -1 at the point x = -D (which is, unfortunately, a
common case). In this case the routine may generate
inaccurate results due to roundoff errors. We STRONGLY
RECOMMEND that if you must use a C value of -1 you check the
resulting activation curves by using Neurokit (in the "Edit
Channel" mode) to see if they look reasonable. If they do
not then you will have to define the channel using a script
function as mentioned above. Such a function will result in
a slower setup time for the channel but will be much more
accurate.
See also:
tabchannel ,
tabgate ,
setupalpha ,
tweakalpha ,
tweaktau ,
Tables
Routine Name: sh
Description: Issues operating system command from GENESIS shell.
Usage: sh command
Example: genesis > echo hello there
hello there
genesis > sh echo hello there
hello there
genesis > echo $DISPLAY
** Error - parse error
genesis > sh echo $DISPLAY
** Error - parse error
genesis > sh "echo $DISPLAY"
babel.bbb.edu:0
genesis >
Notes: You can issue most operating system commands just by typing
them at the GENESIS prompt (if the GENESIS interpreter does
not recognize them as GENESIS commands, it automatically
passes them on to the operating system for evaluation).
However, if you have a GENESIS routine with the same name as
an operating system command, you need to use the sh routine to
send the command directly to the operating system.
See also:
Routine Name: shapematch
Description: This function compares two waveforms generated by GENESIS
and returns a number which represents how similar the
waveforms are to each other.
Usage: shapematch reference-file simulation-file
-start start-time -stepsize dt
-absdev -alternate
Arguments: reference-file: reference data file of outputs vs. time
simulation-file: simulation data file of outputs vs. time
The reference data is what you want the parameter search
to match; the simulation data is what the simulation
produces.
Options: -start start-time: The time at which waveform comparison
starts. If no value is given, start at time = 0.
-stepsize dt: The time step of the samples in the files.
Default = 0.0001 sec.
-absdev: Uses the mean of absolute differences of samples
instead of the root-mean-squared differences to
calculate the match value.
-alternate: Uses an alternate algorithm which can deal with
waveforms having spikes and waveforms using
different time points. The alternative algorithm
is considerably slower than the default algorithm,
and has not been thoroughly debugged.
Return value: Returns a nonnegative floating-point number representing the
goodness of the match, with 0 representing a perfect match.
The more different the waveforms are, the larger the value.
The value represents the root of the mean of the squared
differences in the waveforms at corresponding time points,
unless the -absdev option is chosen (see above). A huge
positive value is returned on an error. In the event of an
error, a massive penalty value (1.0e6) is returned.
Example: float match
match = {shapematch "refdata" "simdata" -stepsize 0.00005}
Notes: The default algorithm requires both waveforms to be defined
on the same time points. It should not be used for
comparing waveforms with spikes.
The alternate algorithm compares interspike intervals only,
ignoring spikes. To do this it will transform the time
base of corresponding ISIs so that they match. This is
reasonable if the ISIs are similar, but if they are very
different the results will not be very meaningful. The
alternate algorithm should probably be used in conjunction
with spkcmp to compare the spike times as well.
The -absdev option will not work for the alternate
algorithm; it uses mean squared deviations only.
The alternate algorithm has not been as well tested as the
default algorithm and we cannot guarantee that it will
function correctly. It was stolen from Upi Bhalla's
shapematch routine.
See also: Parameter Search (
Param )
gen2spk ,
spkcmp
Routine Name: showclocks
Description: Displays currently defined clocks and their assigned values.
Usage: showclocks
Example: genesis > showclocks
ACTIVE CLOCKS
-------------
[0] : 0.001
[1] : 0.005
Notes: Clock number 0 is the global simulation clock. The default
step size is 1.0 in whatever units you are using.
See also:
useclock ,
setclock ,
getclock
Routine Name: showcommand
Description: Displays name of C function invoked by a GENESIS routine.
Usage: showcommand routine-name
Example: genesis > showcommand el
'el' ==> 'do_construct_list'
Notes: This command is useful when you are looking in the GENESIS
source code for the function which implements a particular
command.
See also:
Routine Name: showfield
Description: Displays value of field in data structure of specified element.
Usage: showfield [pathname] [field] ... -all -basic -describe
pathname name of existing element; if wildcard path
specification, all elements referred to will
have their specified fields displayed
(default: current working element)
field field in element data structure for which to
display value; some special options for field:
-basic displays basic information;
-all displays basic info and all fields;
-describe displays a description of the
object from which the element was created;
* displays all fields;
** displays an extended listing of the element
contents, including a description of the
object from which the element was created
Example: //showfield membrane potential, axial resistance
showfield /cell/soma Vm Ra
// show values of all soma fields
showfield /cell/soma -a
genesis > showfield /neutral_test basic
[ /neutral_test ]
flags = 0
NOT FUNCTIONAL
Clock [ 0 ] = 1.000000e+00
0 incoming messages
0 outgoing messages
-----------------------------------------------------
Notes: When a field is specified, the showfield routine is similar
to getfield, but it displays its values rather than returning
them.
When the -describe option is given instead of a field name,
the showfield routine is similar to the showobject routine.
See also:
setfield ,
getfield ,
getfieldnames ,
showobject
Routine Name: showmsg
Description: Displays list of incoming and outgoing messages of an element.
Usage: showmsg element
Example: genesis > showmsg /cell/soma
INCOMING MESSAGES
MSG 0 from '/cell/soma/Na_squid_hh' type [0] 'CHANNEL'
< Gk = 2.99968e-10 > < Ek = 0.045 >
MSG 1 from '/cell/soma/K_squid_hh' type [0] 'CHANNEL'
< Gk = 1.03666e-08 > < Ek = -0.082 >
OUTGOING MESSAGES
MSG 0 to '/cell/soma/Na_squid_hh' type [0] 'VOLTAGE'
< Vm = -0.07 >
MSG 1 to '/cell/soma/K_squid_hh' type [0] 'VOLTAGE'
< Vm = -0.07 >
MSG 2 to '/data/voltage' type [0] 'PLOT' < data = -0.07 >
< name = volts > < color = red >
Notes: showmsg is usually used interactively, when debugging or
trying to understand a simulation, as it prints detailed
information to the screen. Use getmsg within a simulation
script to return specific information.
See also:
addmsg ,
deletemsg ,
getmsg
Routine Name: showobject
Description: Displays description of specified element type.
Usage: showobject object-type
Example: genesis > showobject compartment
object = compartment
datatype = compartment_type
function = Compartment()
class = [ membrane ] [ segment ]
size = 124 bytes
author = M.Wilson Caltech 6/88
VALID ACTIONS
RESTORE2 SAVE2 SET CHECK RESET PROCESS INIT
VALID MESSAGES
[6] EREST : Em
[3] INJECT : inject
[2] AXIAL : Vm
[1] RAXIAL : Ra Vm
[0] CHANNEL : Gk Ek
FIELDS
(ro) name compartment
(ro) index 0
(ro) object &1688896
(hidden) flags
(hidden) nextfields
(hidden) extfields
x 0
y 0
z 0
(hidden) nmsgin
(hidden) msgin
(hidden) nmsgout
(hidden) msgout
(hidden) compositeobject
(hidden) componentof
(hidden) parent
(hidden) child
(hidden) next
activation 0
Vm 0
previous_state 0
Im 0
Em 0
Rm 0
Cm 0
Ra 0
inject 0
dia 0
len 0
initVm 0
DESCRIPTION
Axially asymmetric compartment. Ra is located on
one side of the compartment. This is slightly more
computationally efficient than the symmetric
counterpart.
genesis >
Notes: This routine returns many pieces of information about the
object type, including the class, size, author, valid actions
and messages, and data fields with the default values which
are assigned when the object is instantiated as an element.
If the field is not readable and writeable, the field is
labeled (ro) if it is protected as read-only, and (hidden) if
it and its contents are hidden to the user.
See also:
showfield ,
setfieldprot
Routine Name: showsched
Description: Displays current working simulation schedule.
Usage: showsched
Example: genesis > showsched
WORKING SIMULATION SCHEDULE
[1] Simulate /##[CLASS=segment] -action INIT
[2] Simulate /##[CLASS=segment][CLASS!=membrane][CLASS!=gate]
[CLASS!=concentration][CLASS!=concbuffer] -action PROCESS
[3] Simulate /##[CLASS=membrane] -action PROCESS
[4] Simulate /##[CLASS=output] -action PROCESS
Notes:
See also:
Schedules ,
addtask
Routine Name: showstat
Description: Reports statistics about current simulation time
or memory use
Usage: showstat [-process] [-element [element-name]]
-process prints statistics of time and memory used
-element prints simulation status of all elements,
or the specified element
Example:
genesis > showstat
current simulation time = 0.100050 ; step = 2001; dt = 5.000000e-05
genesis > showstat -process
process status: 0:0.79 user 0:0.09 sys 0:39 real 3.70 Mbytes
genesis > showstat -element /cell/soma
'/cell/soma' element count:
2 hh_channel 384 bytes ( 0.00 Mbytes)
2 messages 96 bytes ( 0.00 Mbytes)
----------------------------------------------------------
4 480 bytes ( 0.00 Mbytes)
total memory usage : 3032324 bytes ( 3.03 Mbytes )
genesis > showstat -element
'/' element count:
3 neutral 228 bytes ( 0.00 Mbytes)
5 messages 316 bytes ( 0.00 Mbytes)
1 compartment 144 bytes ( 0.00 Mbytes)
2 hh_channel 384 bytes ( 0.00 Mbytes)
2 xform 272 bytes ( 0.00 Mbytes)
2 xlabel 224 bytes ( 0.00 Mbytes)
3 xbutton 420 bytes ( 0.00 Mbytes)
1 xdialog 124 bytes ( 0.00 Mbytes)
1 xgraph 188 bytes ( 0.00 Mbytes)
2 xaxis 416 bytes ( 0.00 Mbytes)
1 xshape 168 bytes ( 0.00 Mbytes)
1 xplot 204 bytes ( 0.00 Mbytes)
----------------------------------------------------------
24 3088 bytes ( 0.00 Mbytes)
total memory usage : 3032324 bytes ( 3.03 Mbytes )
Notes:
See also:
getstat
Routine Name: silent
Description: Sets and returns flag which supresses certain information
displays to console.
Usage: silence-status = silent [silent-flag]
silent-flag 1 to suppress informative displays; 0 to
allow informative displays; 2 suppresses
startup messages.
Example: genesis > echo { silent }
0
genesis > silent 1
echo { silent }
1
Notes: Note that in the example above, the prompt is supressed after
the silent flag is set to 1. Various routines use the
status of the silent flag to decide whether to print out
certain informative messages.
For
example, the routines related to element stack (pushe, pope,
stack) normally display the working element they deal with;
if silent is > 0, these routines will not echo that
information. Within any SLI control structure, the flag
behaves as if it were one greater. For example, if the
"step" command is used within a script function, the usual
message reporting the number of steps and cpu time is
supressed unless the flag is set to -1.
See also:
debug
Routine name: simdump
Description: Dumps an entire simulation to a GENESIS script file.
Should generally be invoked after calling the
'simobjdump' function to specify object fields.
One of a family of functions for dumping and restoring
simulations in their entirety, and merging overlapping
simulations. The output of these functions is an ascii file
readable by the GENESIS script interpreter. However, this
ascii file uses 'simundump' to restore field values, which is
efficient but not very human-friendly.
Since the output of simdump is GENESIS script file, one
can dump various parts of a simulation into different files,
and read them back in separately, or read them into a different
simulation, and so on.
Simdump files do quasi-intelligent 'merging' of files with
existing simulations. If an element is already there, it
will content itself with updating the field values and
adding missing messages. By default it will avoid duplicating
existing messages. It also has a provision for
ignoring orphan elements, whose parents are not defined. These
options are activated by the initdump command.
Usage: simdump filename -path path -tree tree -messages -all
filename: The name of the output dump file.
-path path: specifies a wildcard path of elements to
be dumped. This option can be used repeatedly to put
several different bits of the simulation into the
file. The same effect could be achieved by using
the extended wildcard specification.
-tree tree: A currently disabled option for getting the
wildcard path from an xtree.
-messages: A currently disabled option.
-all : Tells simdump to dump the entire simulation.
Example: See below for an example of a simple and a complex dump of
a simulation plus interface.
Notes: In theory it should be possible to use simdump on its own,
without invoking simobjdump or initdump. In this situation,
the command assumes that all fields of the objects are to
be dumped. This is inefficient. Worse, it causes problems
because fields can take values that should not be reloaded
into them. Pointers are a good example. Also see below about
what happens with Xodus.
Simdump always saves files in 'append' mode. This means that
if you accidently use the same filename as an existing .g file,
the original won't be destroyed, and you can edit the file
to extract the dumped part and the original.
Xodus poses lots of problems for simdump, because Xodus
objects do not always behave cleanly. For example,
Xodus objects often have default field values like 'nil'
which are not valid when trying to reload the dumpfile. It
is necessary to exclude the offending fields by using
simobjdump to select well-behaved fields for the dump.
Furthermore, there is no 'field' to determine whether an
xform is displayed or not, so the forms won't appear until
explicity 'shown'. There are various other annoyances, like
things not updating when you expect them to. For this reason,
simdump will need help if you are trying to dump an interface.
Simdump will happily dump the entire contents of a 1-Megabyte
xplot or table. This gives a valid, but enormous dumpfile.
If this is not desirable, simobjdump allows one to specify
the -noDUMP option. See simobjdump documentation.
A few objects will dump too much information for the
parser to handle as part of a single command. This is only
likely to occur in very rare situations.
The hsolver can be dumped, but its fields must be restricted
to the path. The solver will need to be re-initialized
when trying to restore the simulation. It is better to
just rebuild the whole hsolver from scratch.
In general, cell models are much more compactly specified
by the .p files than by the simdump files. It is also much
more user-friendly that way.
The long-bewailed problem with re-entrant parsers means that
the generated script file cannot be read in on a mouse-click.
You will have to type in a command to load the script file.
Example:
This example consists of two files: a demo simulation file called "dumpdemo.g",
and a file "savefunc.g" with two versions of simulation dumping functions.
Cut out the scripts to the appropriate files. Run dumpdemo, which is a
little compartmental model with interface. Save using the simple and complex
versions of the dumping interface. Examine the resulting dumpfiles using
your favourite editor, and then reload them to see what happens.
================ Cut here for file "dumpdemo.g" =============================
//genesis
setclock 0 0.001
include savefunc.g
create neutral /a
create compartment /a/compt
setfield ^ Ra 1 Cm 1 Rm 1
copy /a /b
addmsg /a/compt /b/compt AXIAL Vm
addmsg /b/compt /a/compt RAXIAL Ra Vm
create xform /form
create xgraph /form/graph -ymax 0.5 -xmax 5
create xplot /form/graph/plot -fg red
create xbutton /form/simple_save -script "do_simple_save"
create xbutton /form/complex_save -script "do_complex_save"
create xbutton /form/quit -script quit
xshow /form
addmsg /b/compt /form/graph/plot PLOT Vm *Vm *red
setfield /a/compt inject 1
reset
step 5 -t
============== Cut here for file savefunc.g ================================
//genesis
// This function saves only the structure of the simulation. None
// of the interface objects will be saved.
function do_simple_save
// compartments are well-behaved, so we can get away with
// dumping all compartment fields by default
// Here we illustrate two ways of dumping multiple paths
simdump simple_dump.g -path /a -path /a/## -path "/b,/b/##"
echo "Simple dump done to file: simple_dump.g"
end
// This function saves everything about the simulation. It has
// to jump through many hoops to deal with Xodus oddness.
function do_complex_save
str filename = "complex_dump.g"
// Write out some general info for the dumpfile
openfile {filename} "w"
writefile {filename} "//genesis"
writefile {filename} {"// Saved on " @ {getdate}}
writefile {filename} "setclock 0 0.001"
writefile {filename} "include savefunc.g"
closefile {filename}
// Specify which fields of the Xodus objects we want to save
simobjdump xform xgeom ygeom wgeom hgeom
simobjdump xaxis script
simobjdump xshape script
simobjdump xgraph xmin ymin xmax ymax xgeom ygeom wgeom hgeom
simobjdump xplot npts
simobjdump xbutton script
simobjdump xdialog script value
// Dump the entire simulation
simdump {filename} -all
// We're not done yet: we need to help the interface get back
// to its original state.
openfile {filename} "a"
writefile {filename} "xshow /form"
writefile {filename} \
"setfield /form/graph/plot npts "{getfield /form/graph/plot npts}
writefile {filename} "xupdate /form/graph"
closefile {filename}
echo "Complete dump done to file: "{filename}
end
=============================================================================
See also:
initdump ,
simobjdump ,
simundump .
Routine name: simobjdump
Description: Sets up the format for dumping and reading objects to a file
using simdump.
Usage: simobjdump object ... -coords -default -noDUMP
object: The name of the GENESIS object class
... : The fields to be dumped for this object
-coords: Dump the x y z coords.
-default: Use all the fields defined for the object. This
will also happen if you call simobjdump with no
arguments, or if you don't call simobjdump at all.
-noDUMP: A few GENESIS object classes, such as tables, have
a DUMP action which does object-specific things.
noDUMP inactivates this DUMP action. For example, in
a table, the DUMP action would normally dump the entire
contents of the table. noDUMP prevents this from
happening.
Example: Here is a little dumpfile using simobjdump that recreates a
simple 2-compartment model. In this case the simobjdump
command was not used at all before the simdump, so the
simdump command caused the entire set of fields for the
relevent classes (neutrals and compartments) to be specified
for the dumpfile.
============================================================
//genesis
initdump -version 3
simobjdump neutral
simobjdump compartment activation Vm previous_state \
Im Em Rm Cm Ra inject dia len initVm
simundump neutral /a 0
simundump compartment /a/compt 0 0 0.6632976405 0.6632942696 \
-0.3333315551 0 1 1 1 1 0 0 0
simundump neutral /b 0
simundump compartment /b/compt 0 0 0.3299660931 0.3299627243 \
0.3333349228 0 1 1 1 0 0 0 0
addmsg /b/compt /a/compt RAXIAL Ra Vm
addmsg /a/compt /b/compt AXIAL Vm
enddump
// End of dump
============================================================
Notes: In theory it should be possible to use simdump on its own,
without invoking simobjdump or initdump. In this situation,
the command assumes that all fields of the objects are to
be dumped. This is inefficient. Worse, it causes problems
because fields can take values that should not be reloaded
into them. Pointers are a good example. Also see below about
what happens with Xodus.
Simdump will happily dump the entire contents of a 1-Megabyte
xplot or table. This gives a valid, but enormous dumpfile.
If this is not desirable, simobjdump allows one to specify
the -noDUMP option.
See also:
initdump ,
simdump ,
simundump .
Routine name: simundump
Description: Creates an element and assigns values to its fields.
Simundump is not really a human-use command. It only
occurs in dumpfiles, and is always preceeded by initdump
and simobjdump, and followed up by enddump at the end of
the file.
Usage: simundump object element ... -tree tree x y z
object: The object class to be created
element: The path of the new element
... : Fields values of the element. The field names are
specified earlier in the file by the simobjdump command.
-tree tree: A currently disabled option for getting the
wildcard path from an xtree.
Example: Here is a little dumpfile using simundump that recreates a
simple 2-compartment model.
============================================================
//genesis
initdump -version 3
simobjdump neutral
simobjdump compartment activation Vm previous_state \
Im Em Rm Cm Ra inject dia len initVm
simundump neutral /a 0
simundump compartment /a/compt 0 0 0.6632976405 0.6632942696 \
-0.3333315551 0 1 1 1 1 0 0 0
simundump neutral /b 0
simundump compartment /b/compt 0 0 0.3299660931 0.3299627243 \
0.3333349228 0 1 1 1 0 0 0 0
addmsg /b/compt /a/compt RAXIAL Ra Vm
addmsg /a/compt /b/compt AXIAL Vm
enddump
// End of dump
============================================================
Notes:
Simundump does quasi-intelligent 'merging' of files with
existing simulations. If an element is already there, it
will content itself with updating the field values and
adding missing messages. It won't try to add messages to
missing elements, and won't complain: it assumes that you
meant to leave them out. It also has a provision for
ignoring orphan elements, whose parents are not defined. These
options are activated by the initdump command.
In current versions of simdump/undump, the first field argument
to simundump is always the 'flags' field of the element (even
if it not requested). This restores the clocks, and other
status attributes of elements.
Xodus poses lots of problems for simundump, because Xodus
objects do not always behave cleanly. For example,
Xodus objects often have default field values like 'nil'
which are not valid when trying to reload the dumpfile. It
is necessary to exclude the offending fields by using
simobjdump to select well-behaved fields for the dump.
Furthermore, there is no 'field' to determine whether an
xform is displayed or not, so the forms won't appear until
explicity 'shown'. There are various other annoyances, like
things not updating when you expect them to. For this reason,
simundump will need help if you are trying to reload an
interface.
See also:
initdump ,
simdump ,
simobjdump
Routine Name: sin
Description: Returns sine for given angle (specified in radians).
Usage: sine = {sin angle-in-radians}
Example: float s
s = {sin {3.14159/4}}
Notes:
See also:
asin
Routine Name: spkcmp
Description: This function compares two spike time files, one from raw
data and one from a GENESIS simulation; it returns a number
which is a measure of how different the spike times are for
the two cases.
Usage: spkcmp reference-data simulation-data
-offset time
-pow1 p
-pow2 q
-msp missing_spike_penalty
-nmp nonmonotonicity_penalty
-et end-time
-spk
Arguments: reference-data: reference data spike time file
simulation-data: simulation data spike time file
The reference data is what you want the parameter search to
match; the simulation data is what the simulation produces.
The recommended convention is to have the reference data
spike time file end in .spk and the simulation data spike
time file end in .spk.sim.
Options: -offset time
This offsets the simulation spikes by a fixed
amount. It's useful when the delay before current
injection is different for the experiments and the
simulations. This value can be positive or negative.
-pow1 p
This controls the degree to which spike mismatches
at the beginning of the trace are more heavily
weighted than those at the end. A value of zero
(the default) means there is no extra weight. p
must be >= 0.
-pow2 q
This controls the degree to which missing spikes
are penalized differently according to how many
spikes there were in the real trace. The idea is
that when the real trace has lots of spikes, each
missing or extra spike should not be penalized too
harshly, but when it has only a few it should be
penalized very harshly. A value of zero (the
default) means all missing spikes get the same
penalty. q must be >= 0.
-msp missing_spike_penalty
Penalty for spikes which are in one trace but not
the other; default = 1.0 per spike.
-nmp nonmonotonicity_penalty
Penalty for simulated traces where the interspike
intervals do not get larger monotonically with time.
This allows us to select against cells with bursting
behaviors. A nonmonotonicity penalty of (say) 2.0
would add 2.0 for each second of nonmonotonicity; in
other words, if you have a nonmonotonic interspike
interval, the duration of that particular ISI in
seconds will be multiplied by 2.0. and this would be
added to the total penalty. Default = 0.0 per second
of monotonicity per spike (i.e. no penalty).
-et end-time
If used, ignore spikes beyond a certain end time.
-spk
This causes the number of missing spikes to be
printed out instead of having a penalty added to
the total.
Return value: Returns a nonnegative floating-point number representing
the goodness of the match, with 0 representing a perfect
match. The units of the match are roughly in units of
(msec error)/spike. The more different the times are, the
larger the value. In the event of an error, a massive
penalty value (1.0e6) is returned.
Input spike file format:
Spike time files should be in the following format:
CURR <current-value>
SPK <spike time>
----------
etc.
The line of dashes delimits the different current values.
The spike times may be omitted for a given current; this
will happen if no spikes occur at a given current. Note
that this assumes a fixed current input (current clamp).
Multiple currents may be put one after another in the file.
Typically a single file will contain spike times from
several different current injections into a single cell
(real or modeled). Make sure the currents in the
simulation spike results and in the target spike results
(what you are trying to match) are in the same order.
Algorithm: The algorithm is essentially an average of the absolute
values of the differences in spike times between the real
and simulated outputs, with corrections for spikes which
are only present in one of the outputs. There are several
other parameters controlled by the options (described
above). The algorithm is described in detail in the file
src/param/spkcmp.c (function compare_spikes()).
Example: genesis > float match
genesis > match = {spkcmp "realpyr.spk" "simpyr.spk.sim" \
-pow1 1.0 -pow2 0.6 -msp 0.5 -nmp 200.0}
Notes: This function is typically used for processing data
generated by the gen2spk function, which outputs spike time
files in the correct format for this function.
This function expects that the two spike time files have
the same values for input currents in the same order; if
not, it exits with an error message and returns a huge
penalty.
The spike file format has clearly been optimized for
current-clamp experiments, which is a limitation.
This function has been optimized to work with typical
outputs of pyramidal cells from piriform cortex. It should
work well for all regular-spiking pyramidal cells. It may
work well for other cell types as well (with some
adjustment of the option values), but for cells with very
different behavior (e.g. Purkinje cells in bursting mode)
you may be better off writing your own custom match function.
See also: Parameter Search (
Param ),
gen2spk ,
shapematch
Routine Name: sqrt
Description: Returns square root of positive number.
Usage: square-root = {sqrt positive-number}
Example: genesis > echo {sqrt 2}
1.414213538
genesis > echo {sqrt 0}
0
Notes:
Routine Name: stack
Description: Displays list of elements on working element stack.
Usage: stack
Example: genesis > pwe
/
genesis > pushe /neuron1
/neuron1
genesis > pushe /neuron2
/neuron2
genesis > stack
/
/neuron1
Notes: The stack routine prints out the current contents of the
element stack (the stack used to store paths pushed and 'pop'ed
from the stack using the GENESIS pushe and pope routines).
The stacked elements are listed in the reverse order in which
they will be 'pop'ed (i.e., the last element listed will be
the first 'pop'ed).
See also:
pushe ,
pope
Routine Name: step
Description: Advances the simulation by one or more steps.
Usage: step [steps-or-time] -time -verbose -background
steps number of steps to advance simulation
time time by which to advance simulation
-time interpret the first argument as time
-verbose use verbose mode (display status of simulation
at each step)
-background run simulation as background process, and
return user to GENESIS shell
Example: step 100
step 5 -v
step 25.4 -t -b
genesis > step
time = 1.000000 ; step = 1
completed 1 steps in 0.000000 cpu seconds
Notes: When run in the background, the simulation is still sensitive
to ^C. Generating a ^C interrupt can cause the simulation to
abnormally terminate a step giving erroneous results. To halt
an simulation in progress, use the stop routine.
Only one simulation can be started at any given time. A
background simulation must already be running. The showjobs
routine will display this status (as the Simulate function).
See also:
stop ,
showstat ,
reset ,
check
Routine Name: stop
Description: Completes current simulation step, stopping simulation.
Usage: stop
Example: stop
Notes: After cleanly stopping the simulation, the routine returns you
to the GENESIS shell. The stop routine is NOT equivalent to
interrupting with ^C, which leaves the simulation in an
unknown state -- stop completes the current step in progress.
See also:
step ,
abort
Routine Name: strcat
Description: Returns new string as concatenation of two strings.
Usage: new-string = {strcat s1 s2}
Example: genesis > echo { strcat "bad" "dog" }
baddog
Notes: Unlike the C function of the same name, this routine does not
modify the string s1.
You can also concatenate strings using the ``@'' operator.
Routine Name: strcmp
Description: Compares two strings.
Usage: compare-flag = {strcmp s1 s2}
compare-flag returned as 0 if strings are identical; 1 if
s1 is "greater than" s2; -1 if s1 is "less
than" s2
Example: genesis > echo { strcmp "hi" "hi" }
0
genesis > echo { strcmp "hi" "he"}
1
genesis > echo { strcmp "hi" "ho"}
-1
Notes: "Greater than" means "later in the standard ASCII sequence".
You can compare strings up to a specified character using the
strncmp routine.
See also:
strcat ,
strlen ,
substring ,
findchar
Routine Name: strlen
Description: Returns length of string in number of characters.
Usage: length-int = {strlen string}
Example: genesis > echo { strlen "string" }
6
genesis > echo { strlen "hi there" }
8
Notes: Blanks, TABs, and so forth are included in the count.
See also:
strcat ,
strcmp ,
substring ,
findchar
Routine Name: strncmp
Description: Compares two strings up to specified number of characters.
Usage: compare-flag = {strncmp s1 s2 n}
compare-flag returned as 0 if strings are identical;
1 if s1 is "greater than" s2;
-1 if s1 is "less than" s2
n number of characters up to which to make
comparison
Example: genesis > echo { strncmp "hip" "hit" 2 }
0
genesis > echo { strncmp "hip" "hit" 3 }
-1
Notes: The strncmp routine is like the strcmp routine, but restricted
to a certain number of characters for comparison.
"Greater than" means "later in the standard ASCII sequence".
See also:
strcat ,
strlen ,
substring ,
findchar
Routine Name: strsub
Description: Returns a string with one substring replaced by another
Usage: strsub string old-substring new-substring [-all]
Example: genesis > echo {strsub "old dogs chase old cats" old young}
young dogs chase old cats
genesis > {strsub "old dogs chase old cats" old young -all}
young dogs chase young cats
Notes:
Routine Name: substituteinfo
Description: Lists the substitutions made with the use of objsubstitute
and msgsubstitute
Usage: substituteinfo
Example: genesis > objsubstitute compartment mycompt
genesis > substituteinfo
Number of object substitutions: 1
0 orig=compartment new=mycompt
Number of msg substitutions: 0
Notes: objsubstitute and msgsubstitute are used to allow
you to save an object of one type using simobjdump and
simdump, and then use simundump to reload it as a
different type. substituteinfo provides information
about these substitutions.
See also:
objsubstitute ,
msgsubstitute ,
simobjdump ,
simdump ,
swapdump ,
simundump
Routine Name: substring
Description: Returns part of original string as new substring.
Usage: new-string = {substring string startindex [endindex]}
new-string returned as new string created
string original string
startindex integer indicating position of first character
in string to include in new string
endindex integer indicating position of final character
in string to include in new string (default:
final character in string)
Example: genesis > echo { substring "0123456789" 3 7 }
34567
genesis > echo { substring "0123456789" 3 }
3456789
Notes: The substring routine can be useful in conjunction with other
routines (e.g., getpath) for constructing names based on part
of an element path name.
See also: strcat , strcmp , strncmp , strlen , findchar
Routine name: swapdump
Description: Mirrors initialization data for doing simulation dumps
using simdump. Consider this situation: we have a dumpfile
that we want to read in, but at the same time we have
laboriously defined (using simobjdump) our favourite sets of
fields for all objects. Unfortunately the dumpfile has its own
set of simobjdumps, which will overwrite ours. So we use
swapdump, which puts our own simobjumps into storage, while we
read in the dumpfile. Then we can do swapdump again to go back
to our original set of simobjdumps.
Usage: swapdump
Example: Complicated model is already set up, with its own preferences
for simobjdump. Now we want to read in a dumpfile called foo.g.
...
swapdump // put original simobjdump preferences into storage
include foo.g // read in dumpfile which has its own simobjdumps
swapdump // restore original simobjdump preferences
...
simdump bar.g -all // Save combined model using original
// simobjdump preferences.
Notes:
See also:
initdump ,
simdump ,
simobjdump ,
simundump
Routine Name: syndelay
Description: This command is used to set or to add a small "synaptic"
component to the delay fields of synapses. It is useful
for when cells are very close together and thus where
planardelay or volumedelay give unrealistically small
delays.
Usage: syndelay path delay \
-add \
-uniform scale \
-gaussian stdev maxdev \
-exponential mid max \
-absoluterandom
path A wildcarded list of elements which must be synchans or
objects derived from synchan.
delay -- This sets all the synaptic delays in question to be
equal to "delay", or adds "delay" to the existing
delay if the -add option is selected.
-add This option causes the delays to be added to the
preexisting delays in the synapses instead of
overwriting them.
The next four options are used to add random components to the
delay. How these random components are added to the delays is
explained below.
-uniform scale -- This option gives a random number taken
from a uniform distribution in the range
{-scale, scale}.
-gaussian stdev maxdev -- This option gives a random number
taken from a gaussian distribution centered on zero,
with a standard deviation equal to "stdev" and with
a maximum value of "maxdev". The maximum value is
used to limit the random component to a given range.
-exponential mid max -- This option gives a random number
taken from an exponential distribution with a
minimum value of zero, a 1/e point of "mid" and a
maximum value of "max". This is mainly for backwards
compatibility with genesis 1.4.
-absoluterandom This option alters the way the random number
is combined with the nominal delay to give the actual
delay, as described below.
Once a random component has been created for a given delay,
it is used to set the delay as follows. If the
-absoluterandom option has not been selected the delay is set
to be:
final_delay = delay + (delay * random_number)
Whereas if the -absoluterandom option has been selected then
we have
final_delay = delay + random_number
Thus the default is to have the amount of randomness as a
constant proportion of the delay value.
Example: syndelay /cell[]/apical_dend/Ex_chan 0.001 \
-add -gaussian 0.1 0.3
This command will add a small delay to the delay fields in the
synapses in /cell[]/soma/apical_dend/Ex_chan. The "synaptic"
delay added will be 1 millisecond plus a random component.
Notes: The delays are never allowed to go negative even if a large
negative random component is added. Negative delays are set
to zero.
If the -add option is chosen, the random component modifies
only the delay added and not the total delay.
See also: planardelay , volumeconnect , volumeweight , syndelay ; Chapter 18 of the Book of GENESIS (2nd ed.) has a lengthy discussion of this and related commands.
Routine Name: tab2file
Description: Utility function for writing one or more tables of an element
that uses interpol_structs (e.g. a table, tabchannel, xplot,
etc.) to an ascii file. The output file has the entries for
the respective tables in successive positions. Various
specialized output modes let one do on-the-fly conversions of
the table entries.
Usage: tab2file file-name element table -table2 table -table3 table \
-mode mode -nentries n -overwrite
Arguments: filename: name of ascii file to which the table contents
will be written
element: path of element containing the table
table: name of interpol_struct within the element
Options: -table2 table
This option allows one to specify an additional table to write
into the file. Entries are written alternately from the first
table and table2. Note that table2 must be in the same
element as table.
-table3 table
This allows a third table. This option is similar to table2.
-mode mode
mode can be y (the default), xy, alpha, beta, tau, minf, or
index. In modes alpha, tau, xy, or index, one table must be
specified. In modes beta and minf, two tables must be
specified.
y: The table contents are written one to a line, without
the x values. If the -table2 or -table3 option is used,
then the entry for each table is written om the same line.
xy: The table contents are written as one (x,y) pair per
line.
index: The table contents are written as one (i,y) pair per
line, where i is the index, which runs from 0 to nentries.
alpha: This mode, as well as beta, tau, and minf, assume that
the element containing the tables is a tabchannel, with each
gate having an A table containing alpha values, and a B table
containing values of alpha + beta. When the table specified
is an A table, the alpha mode is the same as the xy mode,
giving an (x,alpha) pair per line.
beta: In this case, the A table is specified as the table, and
the B table is used with -table2. Then the output is one
(x,beta) pair per line, with beta = B - A.
tau: Like the beta mode, the A table is specified as the
table, and the B table is used with -table2. Then the output
is one (x,tau) pair per line, with tau = 1/(A + B).
minf: Like the beta mode, the A table is specified as the
table, and the B table is used with -table2. Then the output
is one (x,minf) pair per line, with the steady state
activation minf = A/B = alpha/(alpha + beta).
-nentries n
The parameter n, or nentries, is more properly described as
xdivs, the number of divisions, with indices of the entries
running from 0 to n, so the actual number of entries is n + 1.
If the --nentries option is not used, the default is to
calculate n from the xivs field of the interpol_struct. Some
objects (e.g. xplot) do not have an xdivs field of the
interpol_struct. In this case, n must be specified as the
total number of entries - 1.
-overwrite
The default behavior is to append to the file file-name if it
already exists. The overwrite option is used to create a new
file, overwriting the old one.
Example: (using the elements created by Scripts/tutorials/newtutorial3.g)
/* create a file that looks like:
-0.100000 0.039416
-0.099950 0.039586
-0.099900 0.039756
...
0.049900 0.975220
0.049950 0.975246
0.050000 0.975272
*/
tab2file mfile /cell/soma/K_hh_tchan X_A -table2 X_B -mode minf
/* create a file that looks like:
0 7.462942
1 7.491676
2 7.520512
...
2998 1099.018540
2999 1099.518456
3000 1100.018372
*/
tab2file ifile /cell/soma/K_hh_tchan X_A -mode index
/* save an xplot (from Scripts/kinetikit/xgraphs.g) */
function do_save_plot(file)
str file
str plot = {getfield /parmedit/plot elmpath}
int x
x = {getfield {plot} npts} // Get the actual number of points
tab2file {file} {plot} xpts -table2 ypts -nentries {x - 1}
xhide /parmedit/plot
end
Notes: Elements having TABSAVE and TABREAD actions (e.g. tabchannel,
tab2Dchannel, and tabcurrent) can also call these actions
instead of using tab2file and file2tab.
See also:
file2tab , interpol_struct
documentation (
Tables )
Routine Name: tan
Description: Returns tangent for given angle (specified in radians).
Usage: tangent = {tan angle-in-radians}
Example: float t = {tan {3.14159/4}}
Notes:
See also:
atan
Routine Name: trunc
Description: Returns integer part of number.
Usage: integer = {trunc number}
Example: genesis > echo { trunc 5.999 }
5
Notes: This routine converts any number to an integer by deleting
the decimal part without any rounding.
See also:
round
Routine Name: tweakalpha
Description: Allows one to fill the A and B tables of a tabchannel
with values of the rate constants alpha and beta, and
then convert them to the proper values A = alpha and
B = alpha + beta.
Usage: tweakalpha channel-element gate
gate X, Y, or Z
Example: tweakalpha K_mit_usb X
Notes:
See also:
tabchannel ,
tweaktau
Routine Name: tweaktau
Description: Allows one to fill the A table of a tabchannel with the
activation time constant tau, and the B table with the steady
state activation m_inf, and then convert the tables to the
proper values A = alpha and B = alpha + beta.
Usage: tweaktau channel-element gate
gate X, Y, or Z
Example: tweaktau Na_rat_smsnn X
Notes:
See also:
tabchannel ,
tweakalpha
Routine Name: useclock
Description: Specifies which clock an element should use during simulation.
Usage: useclock path clock-number
Example: useclock /graphform/Vmgraph 1
Notes: The useclock routine specifies which clock is to be used by a
GENESIS element. You might use it, for instance, to allow
some elements to be updated at greater intervals than the
basic simulation step.
See also: showclocks , setclock , getclock
Routine Name: version
Description: Returns the GENESIS version number.
Usage: version_number = {version}
Example:
if ({version} < 2.0)
echo "This simulation requires version 2.0 or later"
exit
end
Notes:
See also:
Routine Name: volumeconnect
Description: Establishes synaptic connections between groups of elements
based on the x-y-z positions of the elements. This routine
sets up the connections by adding SPIKE messages between the
source and destination objects.
Usage: volumeconnect source_elements destination_elements \
-relative \
-sourcemask {box, ellipsoid} x1 y1 z1 x2 y2 z2 \
-sourcehole {box, ellipsoid} x1 y1 z1 x2 y2 z2 \
-destmask {box, ellipsoid} x1 y1 z1 x2 y2 z2 \
-desthole {box, ellipsoid} x1 y1 z1 x2 y2 z2 \
-probability p
source_elements A wildcarded list of elements which are the
sources of the SPIKE messages. These must be of
class "spiking" and are usually spikegen or
randomspike objects.
destination_elements A wildcarded list of elements which are
the destinations of the SPIKE messages. These must
be synchans or objects derived from synchan.
-relative This option means that connections will be set up
based on the locations of destination objects
relative to source objects. If this option is not
selected, the absolute locations of source and
destination elements will be used to determine
which connections are to be set up.
-sourcemask {box, ellipsoid} x1 y1 z1 x2 y2 z2 -- This
specifies a rectangular or ellipsoidal region from
which source elements are to be taken. If the "box"
option is used, then x1, y1, and z1 are the minimum
x, y, and z values of the region while x2, y2, and
z2 are the maximum x, y, and z values of the
region. If the "ellipsoid" option is used, then the
source region is an ellipsoid with x1, y1 and z1
representing the center of the ellipsoid while x2,
y2, and z2 represent the lengths of the principal
axes in the x, y, and z directions respectively.
Note that to choose a spherical region x2, y2, and
z2 must be equal. Note also that one or the other
of {box, ellipsoid} MUST be chosen; leaving both of
them out will generate an error. Finally, one can
choose multiple source regions by having multiple
-sourcemask options. The same conventions are
followed for the next three options.
-sourcehole {box, ellipsoid} x1 y1 z1 x2 y2 z2 -- This
specifies a rectangular or elliptical region NOT to
include in the source region(s). You can exclude
multiple regions by having multiple -sourcehole
options.
-destmask {box, ellipsoid} x1 y1 z1 x2 y2 z2 -- This
specifies a rectangular or elliptical region to which
SPIKE messages will be sent.
-desthole {box, ellipsoid} x1 y1 z1 x2 y2 z2 -- This
specifies a rectangular or elliptical region NOT to
include in the destination region(s).
-probability p -- This option causes connections to be
made with a probability p, which must be in the
range [0,1]. This allows probabilistically-connected
networks to be set up.
Example: Say we want to connect the spike generating-region of a group
of cells with excitatory synapses on the apical dendritic
compartments of the same group of cells, without connecting
any cell to itself. We could do this:
volumeconnect /cell[]/soma/spike \
/cell[]/apical_dend/exc_syn \
-relative \
-sourcemask box -1 -1 -1 1 1 1 \
-sourcehole box -10e-6 -10e-6 -1 \
10e-6 10e-6 1 \
-destmask box -1 -1 -1 1 1 1
Note that here we are excluding a region 10 microns square in
the x and y direction (but essentially unlimited in the z
direction) so that cells don't connect to themselves. Here
I'm assuming we're using SI units. This could also have
been done with planarconnect. Note also that the usual way
to specify "all cells in a region" is to give source or
destination regions using -sourcemask or -destmask with
limits far greater than the entire extent of all the
elements in the region.
Notes: This routine is almost identical with planarconnect except
that it uses the positions of elements in three dimensions
to specify whether connections are made or not, whereas
planarconnect uses only the x and y dimensions.
The weights and delays of the connections set up by this
command are typically specified using the volumeweight and
volumedelay commands, although they can be set up by hand.
See also:
planarconnect ,
volumeweight ,
volumedelay ; Chapter 18
of the Book of GENESIS (2nd ed.) has a lengthy discussion on
this and related commands.
Routine Name: volumedelay
Description: Sets the delay fields on groups of synapses between
specified lists of elements. Most often used to set
delays on groups of synapses that have been set up
by calling the "volumeconnect" command. This function
can assign groups of synapses to a fixed delay, can
assign delays in proportion to the distances between
pre- and postsynaptic elements, and can add various
types of randomness to delay values.
Usage: volumedelay sourcepath [destination_path] \
-fixed delay \
-radial conduction_velocity \
-add \
-uniform scale \
-gaussian stdev maxdev \
-exponential mid max \
-absoluterandom
sourcepath A wildcarded list of elements which are the
sources of the SPIKE messages connecting the
pre- and postsynaptic elements (i.e. the presynaptic
elements). These must be of class "spiking" and are
usually spikegen or randomspike objects.
destination_path A wildcarded list of elements which must be
synchans or objects derived from synchan. If this
(optional) argument is given, only the delays between
the given set of pre- and postsynaptic elements will
be set by this command. If this argument is not
given, then all the synapses receiving SPIKE messages
from the presynaptic elements will have their delays
set by this command. NOTE: this optional argument is
new and is not documented in the Book of Genesis.
-fixed delay -- This option sets all the synaptic delays in
question to be equal to "delay".
-radial conduction_velocity -- This option sets the synaptic
delays in question to be proportional to
the distance between the source and destination
elements according to the equation:
delay = radial_distance / conduction_velocity
Where conduction_velocity is usually measured in
meters/sec (SI units). "conduction_velocity"
represents the conduction velocity of the
(hypothetical) axon that the spikes travel down.
For volumedelay, the distance is measured as:
distance =
sqrt((x_src - x_dest)^2 +
(y_src - y_dest)^2 +
(z_src - z_dest)^2)
where x_src is the x component of the source element,
x_dest is the x component of the destination element,
and so on.
-add This option causes the computed delays to be added to
the preexisting delays in the synapses instead of
overwriting them. This is useful when adding small
synaptic delays, among other uses.
The next four options are used to add random components to the
delays established using the -fixed or -decay options. How
these random components are added to the delays is explained
below.
-uniform scale -- This option gives a random number taken
from a uniform distribution in the range
{-scale, scale}.
-gaussian stdev maxdev -- This option gives a random number
taken from a gaussian distribution centered on zero,
with a standard deviation equal to "stdev" and with
a maximum value of "maxdev". The maximum value is
used to limit the random component to a given range.
-exponential mid max -- This option gives a random number
taken from an exponential distribution with a
minimum value of zero, a 1/e point of "mid" and a
maximum value of "max". This is mainly for backwards
compatibility with genesis 1.4.
-absoluterandom This option alters the way the random number
is combined with the nominal delay to give the actual
delay, as described below.
Once a random component has been created for a given delay,
it is used to set the delay as follows. If the
-absoluterandom option has not been selected the delay is set
to be:
final_delay = delay + (delay * random_number)
Whereas if the -absoluterandom option has been selected then
we have
final_delay = delay + random_number
Thus the default is to have the amount of randomness as a
constant proportion of the delay value.
Example: [modified from the Orient_tut simulation:]
volumedelay /retina/recplane/rec[]/input \
-radial {CABLE_VEL} \
-gaussian 0.1 0.3
This command will set the size of the delays of synapses
that are receiving their inputs from
/retina/recplane/rec[]/input. It gives delays equal to the
radial distance between elements divided by the conduction
velocity (CABLE_VEL). It also specifies that gaussian noise
be added to the delays with a mean value of 0.1 (which
represents 10% of the original delay, since -absoluterandom
has not been selected) and a maximum value of 0.3 (which is
30% of the original delay value).
Notes: The "destination_path" optional argument is new and is not
documented in the Book of GENESIS.
This routine calculates distance using the x, y, and z
coordinates of the element positions and is thus more
realistic than planardelay, which only uses the x and y
directions. In general, we encourage users to use this
function instead of planardelay, which is mainly provided
for backwards compatibility with genesis 1.4.
The delays are never allowed to go negative even if a large
negative random component is added. Negative delays are set
to zero.
If the -add option is chosen, the random component modifies
only the delay added and not the total delay.
See also:
planardelay ,
volumeconnect ,
volumeweight ,
syndelay ; Chapter 18
of the Book of GENESIS (2nd ed.) has a lengthy discussion on
this and related commands.
Routine Name: volumedelay2
Description:
Description: A faster version of volumedelay, which sets the delay fields
on groups of synapses between specified lists of elements.
Most often used to set delays on groups of synapses that have
been set up by calling the "volumeconnect" command. This
function can assign groups of synapses to a fixed delay, can
assign delays in proportion to the distances between pre- and
postsynaptic elements, and can add various types of randomness
to delay values.
Usage: volumedelay sourcepath destination_path \
-fixed delay \
-radial conduction_velocity \
-add \
-uniform scale \
-gaussian stdev maxdev \
-exponential mid max \
-absoluterandom
Notes: In contrast to volumedelay, which can set the delays of all
efferent synapses from the source map when no destination is
given, volumedelay2 only sets the delays of the synapses
from the source map to a particular destination map. By
requiring the destination parameter, volumedelay2 achieves
faster setup times than volumedelay. For further details of
usage and examples, see the documentation for volumedelay.
See also:
volumedelay ,
volumeconnect ,
volumeweight ,
volumeweight2
Routine Name: volumeweight
Description: Sets the weight fields on groups of synapses between
specified lists of elements. Most often used to set
weights on groups of synapses that have been set up
by calling the "volumeconnect" command. This function
can assign groups of synapses to a fixed weight, can
assign weights in proportion to the distances between
pre- and postsynaptic elements, and can add various
types of randomness to weight values.
Usage: volumeweight sourcepath [destination_path] \
-fixed weight \
-decay decay_rate max_weight min_weight \
-uniform scale \
-gaussian stdev maxdev \
-exponential mid max \
-absoluterandom
sourcepath A wildcarded list of elements which are the
sources of the SPIKE messages connecting the
pre- and postsynaptic elements (i.e. the presynaptic
elements). These must be of class "spiking" and are
usually spikegen or randomspike objects.
destination_path A wildcarded list of elements which must be
synchans or objects derived from synchan. If this
(optional) argument is given, only the weights between
the given set of pre- and postsynaptic elements will
be set by this command. If this argument is not
given, then all the synapses receiving SPIKE messages
from the presynaptic elements will have their weights
set by this command. NOTE: this optional argument is
new and is not documented in the Book of GENESIS.
-fixed weight -- This option sets all the synaptic weights in
question to be equal to "weight".
-decay decay_rate max_weight min_weight -- This option sets
the synaptic weights in question to be proportional to
the distance between the source and destination
elements according to the equation:
weight = (max_weight - min_weight) *
exp(-decay_rate * distance) + min_weight
For volumeweight, the distance is measured as:
distance =
sqrt((x_src - x_dest)^2 +
(y_src - y_dest)^2 +
(z_src - z_dest)^2)
where x_src is the x component of the source element,
x_dest is the x component of the destination element,
and so on.
The next four options are used to add random components to the
weights established using the -fixed or -decay options. How
these random components are added to the weights is explained
below.
-uniform scale -- This option gives a random number taken
from a uniform distribution in the range
{-scale, scale}.
-gaussian stdev maxdev -- This option gives a random number
taken from a gaussian distribution centered on zero,
with a standard deviation equal to "stdev" and with
a maximum value of "maxdev". The maximum value is
used to limit the random component to a given range.
-exponential mid max -- This option gives a random number
taken from an exponential distribution with a
minimum value of zero, a 1/e point of "mid" and a
maximum value of "max". This is mainly for backwards
compatibility with genesis 1.4.
-absoluterandom This option alters the way the random number
is combined with the nominal weight to give the actual
weight, as described below.
Once a random component has been created for a given weight,
it is used to set the weight as follows. If the
-absoluterandom option has not been selected the weight is set
to be:
final_weight = weight + (weight * random_number)
Whereas if the -absoluterandom option has been selected then
we have
final_weight = weight + random_number
Thus the default is to have the amount of randomness as a
constant proportion of the weight value.
Example: [modified from the Orient_tut simulation:]
volumeweight /retina/recplane/rec[]/input \
-decay 0.5 10.0 0.1 \
-gaussian 0.1 0.3
This command will set the size of the weights of synapses
that are receiving their inputs from
/retina/recplane/rec[]/input. It gives exponentially decaying
weights with a maximum size of 10.0, a minimum size of 0.1,
and a decay rate of 0.5. It also specifies that gaussian
noise be added to the weights with a mean value of 0.1
(which represents 10% of the original weight, since
-absoluterandom has not been selected) and a maximum value of
0.3 (which is 30% of the original weight value).
Notes: The "destination_path" optional argument is new and is not
documented in the Book of Genesis.
This routine calculates distance using the x, y, and z
coordinates of the element positions and is thus more
realistic than planarweight, which only uses the x and y
directions. In general, we encourage users to use this
function instead of planarweight, which is mainly provided
for backwards compatibility with genesis 1.4.
The weights are never allowed to go negative even if a large
negative random component is added. Negative weights are set
to zero.
The options -fixed and -decay are mutually exclusive. The
different random options -uniform, -gaussian, and -exponential
are also mutually exclusive.
See also:
planarweight ,
volumeconnect ,
volumedelay ; Chapter 18
of the Book of GENESIS (2nd ed.) has a lengthy discussion on
this and related commands.
Routine Name: volumeweight2
Description:
Description: A faster version of volumeweight, which sets the weight fields
on groups of synapses between specified lists of elements.
Most often used to set weights on groups of synapses that have
been set up by calling the "volumeconnect" command. This
function can assign groups of synapses to a fixed weight, can
assign weights in proportion to the distances between pre- and
postsynaptic elements, and can add various types of randomness
to weight values.
Usage: volumeweight sourcepath destination_path \
-fixed weight \
-decay decay_rate max_weight min_weight \
-uniform scale \
-gaussian stdev maxdev \
-exponential mid max \
-absoluterandom
Notes: In contrast to volumeweight, which can set the weights of all
efferent synapses from the source map when no destination is
given, volumeweight2 only sets the weights of the synapses
from the source map to a particular destination map. By
requiring the destination parameter, volumeweight2 achieves
faster setup times than volumeweight. For further details of
usage and examples, see the documentation for volumeweight.
See also:
volumeweight ,
volumeconnect ,
volumedelay ,
volumedelay2
Routine Name: where
Description: Returns name of operating-system directory in which specified
file is located.
Usage: where filename
filename name of file to search for (must be actual
name; where does not add a .g if you do not
explicitly supply it, and does not accept
wildcarded names)
Example: genesis > where mysim.g
'mysim.g' found in .
genesis > where fooby
could not find 'fooby' in . /usr/genesis/startup
Notes: The where routine searches the script path list (as specified
in the operating system environmental variable SIMPATH) and
reports the first instance found of the specified file.
Routine Name: writecell
Description: Writes parameters of neuron to a cell parameter file in a
standard format.
Usage: writecell filename cellname -cartesian -polar -relative
-absolute -syndens -syncond -author author
filename name to give cell descriptor file
(should end with extension .p)
cellname name of GENESIS cell for which you
want to store description
author who made the cell
default options -cartesian -relative -syndens
Example: writecell newmitral.p /mitral
Notes: This cell-writing routine is the counterpart of the readcell
routine. writecell takes a multicompartment neuron set up
in GENESIS and writes it in the neuron descriptor format to
a file. Options allow you to specify whether the compartment
coordinates are cartesion or polar, and whether they are
given in absolute units or relative to the postion of the
parent compartment. The -syndens and -syncond options
specify whether synaptic conductances are expressed as
densities (conductance per unit area) or in absolute units.
The format of the cell parameter file is described in the
documentation for readcell. The routine is capable of
parsing GENESIS neurons which are not in the 'flat' element
structure produced by the readcell routine. There are
limitations to the present version of writecell, as there
have been new features added to readcell which have not yet
been incorporated into writecell. Thus, not all cell models
can be parameterized with writecell.
See also:
readcell
Routine Name: writefile
Description: Writes out ASCII data to currently opened file.
Usage: writefile filename [arguments ...] [-nonewline] [-format str]
filename name of file to write to (must first be opened
with openfile routine with w or a switch)
-nonewline do not append carriage return at end of line
(if omitted, carriage return is appended)
-format str use specified format string str to format each
argument (to construct mixed formats, use
multiple writefile calls with -n option to
place them on a single line)
arguments strings to be written out to file (default is
nothing, which effectively means a blank line
unless -n is selected to suppress carriage
return; the arguments are written out with
single spaces between each and are terminated
with a carriage return)
Example: openfile test2 w
// both of these write three entries per line,
// each separated by a space
writefile test2 1.0 2.0 3.0
writefile test2 "4.0 5.0 6.0"
genesis > openfile test w
genesis > writefile test Vm = 10 "string with space" {10+5}
genesis > writefile test one -n
genesis > writefile test line
genesis > writefile test X Y -format "%5s"
genesis > writefile test 5.3 6.5 -format "(%3s)"
genesis > writefile test FIRST SECOND -n -format "%-10s"
genesis > writefile test THIRD -format "%30s"
genesis > writefile test done
genesis > closefile test
genesis > more test
Vm = 10 string with space 15
oneline
X Y
(5.3)(6.5)
FIRST SECOND THIRD
done
genesis >
Notes: The changes you make are made permanent when you close the
file (using closefile), or flush the buffer with flushfile.
There is limited formatting of output.
See also:
openfile ,
closefile ,
listfiles ,
readfile ,
flushfile ,
floatformat
Routine Name: xcolorscale
Description: Sets the color scale for mapping numerical values to
color.
Usage: xcolorscale colorscale
colorscale: hot, rainbow, rainbow2, redhot, or grey
Example: xcolorscale hot
Notes: The colorscale (which is a file in genesis/startup) applies
to pixes which have a field mapped to color, such as the
shapes in an xvar or xview, or the cell display in xcell. It
does not apply to widgets, like buttons, labels, etc.
Routine Name: xgetstat
Description: returns 0 if Xodus is not properly initialized.
Usage: status = {xgetstat}
Example: echo {xgetstat}
1
if ({{xgetstat})
include graphics
end
Notes: It is possible to run GENESIS without XODUS by using
the -nox option to the genesis command line. If a
simulation is to intended to be run both with and
without XODUS, a simulation script may use xgetstat to
determine if XODUS is available.
See also:
genesis
Routine Name: xps
Description: Sets parameters used to generate postscript output of widgets.
Usage: xps [-maxgray maxgray] [-mingray mingray]
[-inverse inverse-flag] [-dpi screendpi]
[-filename name] [-printer]
maxgray integer between 0 and 256 (with mingray,
sets the range of black to white)
mingray integer between 0 and 256 (threshold for
a pixel to be black)
inverse-flag 0 to leave image as is; 1 to reverse
image
screendpi screen resolution in dots per inch
name name of the file to which output will be
directed
-printer flag indicating that print commands should be
sent directly to printer rather than to file
Examples: genesis > xps -inverse 0 -filename dump.ps
genesis > xps
usage: xps [-maxgray maxgray(0-256)][-mingray mingray]
[-inverse 0/1] [-dpi screendpi][-filename name][-printer]
[-help][-usage]
status : maxgray = 256, mingray = 0, inverse = 0, dpi = 100
output to file 'dump.ps'
Notes: The xgraph and xdraw widgets are able to output their contents
to a postscript printer or file when ctrl-p is typed while the
cursor is within the widget. xps is used to set some relevant
parameters. Called with no arguments, the routine displays a
usage message plus the current settings for output parameters
that you can set with the routine.
The default is to send the output to the postscript printer
that is specified by the PRINTER environment variable. The
filename option may be used to specify a filename to which the
output may be sent instead. Use the printer option to restore
output to the printer. Note that this is NOT used to set the
printer name.
The inverse flag should normally be set to 0 for dark colors
plotted on a light background, such as the default gray
background provided by XODUS. However, you will generally get
better results by setting the bg field of the widget to
"white". If you make light plots on a black background, set
inverse to 1. The dots per inch of the display (specified
with the dpi option) is used for setting the line width of
plotted lines. A larger dpi will make a narrower line.
mingray is subtracted from the pixel value to define the pixel
value at which the color is black. Reducing the range
(maxgray - mingray) increases the contrast, scaling the pixel
value by 1/(maxgray - mingray).
This method of producing graphical output has the advantage of
being independent of the screen resolution. To produce an
exact bit-mapped replica of the image on the screen, it is
best to use one of the screen capture utilities such as xv or
import (from the ImageMagick package), available at the usual
X windows archive sites. For publication quality graphs, it
is best to use an asc_file object to write data to a file that
can be processed with a plotting package such as gnuplot.
setpostscript is an alias for xps.
Routine Name: xsimplot
Description: Allows 2-D plotting of data/subsets of data from the
binary file on disk. At present it can deal with files
in the FMT1 and the Netcdf file formats.
Usage: xsimplot graphelm pathtofile -cell cellnum \
-skip skipby -overlay overlaynum \
-offset overlayoffset -color col -gain gainval -old
Example: See Scripts/examples/diskiolib/diskio/simplot.g
Notes: xsimplot can be used to plot data or subsets of data
from a binary simulation file onto an xgraph. At the
moment it can be reliably used to plot data from a
FMT1 or a netcdf file generated by genesis simulations
via the use of the disk_out or diskio elements.
Explanation of arguments and options:
____________________________________
The 2 mandatory arguments to xsimplot are the
1. the genesis path of the xgraph element
on which the data is to be plotted.
2. the unix pathname of the binary data file.
-cell cellnum:
The -cell option allows plotting of a
particular set of values dumped onto the file.
For example, if a 100 SAVE messages are sent
to a diskio/disk_out element and the
simulation stepped 100 times, by specifying a
cellnum anywhere from 0-99, one can plot
values corresponding to a particular message.
cellnum defaults to 0 if this option is not
specified.
-skip skipby:
The -skip option allows plotting of a subset
of values within a cell. For example, in order
to plot values corresponding to the 30th, 60th
and the 90th time step in a 100 step
simulation file, a skipby value of 30 will
plot these points joined by a discontinuous
straight line. Defaults to 1 if not
specified.
-overlay overlaynum:
Allows successive renderings of the same plot
to overlay on the graph instead of overwriting
previous ones. Goes hand in hand with the
usage of the -offset option.
-offset overlayoffset:
Allows the same plot to be offset in the
y-axis by the amount equal to overlayoffset.
When used with the -overlay option, gives a
means of graphically comparing plots from 2
different simulation runs.
-color col:
Color of plot pix - can be specified as a
string or an index into a colorscale.
Defaults to black.
-gain gainval:
Currently not implemented
-old:
A No-op. Retained for backwards compatibility
with GENESIS 1.4.
See also:
disk_out ,
diskio ,
xgraph ,
xplot ,
xcolorscale