GENESIS Reference ManualMay 5, 2001: GENESIS Command Reference

Previous Next Table of Contents

## 25. GENESIS Command Reference

## 25.1 abort

    Routine Name:   abort

    Description:    Cleanly interrupts simulation in progress.

    Usage:          abort

    Example:        abort

    Notes:

See also: stop , step

## 25.2 abs

     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:

## 25.3 acos

    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

## 25.4 addaction

    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 )

## 25.5 addalias

    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

## 25.6 addclass

    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

## 25.7 addescape

    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

## 25.8 addfield

    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

## 25.9 addforwmsg

    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

## 25.10 addglobal

    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

## 25.11 addmsg

    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

## 25.12 addmsgdef

    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

## 25.13 addobject

    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

## 25.14 addtask

    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">

## 25.15 argc

    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

## 25.16 arglist

    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

## 25.17 argv

    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

## 25.18 asciidata

    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

## 25.19 asin

    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

## 25.20 atan

    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

## 25.21 call

    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

## 25.22 callfunc

    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:

## 25.23 cd

    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

## 25.24 ce

    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

## 25.25 cellsheet

    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.

## 25.26 check

    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

## 25.27 chr

    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:

## 25.28 clearerrors

    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

## 25.29 closefile

    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

## 25.30 convert

    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.doc (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).

## 25.31 copy

    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

## 25.32 cos

    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

## 25.33 countchar

    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:

## 25.34 countelementlist

    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

## 25.35 cpu

    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

## 25.36 create

    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

## 25.37 createmap

    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

## 25.38 debug

    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

## 25.39 delete

    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

## 25.40 deleteaction

    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

## 25.41 deleteall

    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

## 25.42 deleteclass

    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

## 25.43 deletefield

    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

## 25.44 deleteforwmsg

    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

## 25.45 deletemsg

    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

## 25.46 deletemsgdef

    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

## 25.47 deletetasks

    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

## 25.48 disable

    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.doc.)

See also: enable , step , reset

## 25.49 echo

    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.

## 25.50 egg

    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

## 25.51 el

    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.

## 25.52 enable

    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

## 25.53 enddump

    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

## 25.54 eof

    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

## 25.55 exists

    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:

## 25.56 exit

    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".

## 25.57 exp

    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

## 25.58 file2tab

    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

## 25.59 fileconnect

    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.

## 25.60 findchar

    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

## 25.61 findsolvefield

    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

## 25.62 floatformat

    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.

## 25.63 flushfile

    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

## 25.64 gaussian

    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

## 25.65 gen2spk

    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

## 25.66 genesis

    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

## 25.67 getarg

    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

## 25.68 getclock

    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

## 25.69 getdate

    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

## 25.70 getdefault

    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

## 25.71 getelementlist

    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

## 25.72 getenv

    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

## 25.73 getfield

    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

## 25.74 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

## 25.75 getglobal

    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

## 25.76 getmsg

    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

## 25.77 getparamGA

    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

## 25.78 getpath

    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

## 25.79 getsolvechildname

    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

## 25.80 getsolvecompname

    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

## 25.81 getstat

    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

## 25.82 getsyncount

    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

## 25.83 getsyndest

    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

## 25.84 getsynindex

    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

## 25.85 getsynsrc

    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

## 25.86 h

    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.

## 25.87 help

    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 .doc suffix).  For instance, you
                    might create the following file trig.doc:

                            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.doc would
                    be read in and displayed at that point in the file.

## 25.88 initdump

    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

## 25.89 initparamBF

    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

## 25.90 initparamCG

    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

## 25.91 initparamGA

    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

## 25.92 initparamSA

    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

## 25.93 initparamSS

    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

## 25.94 input

    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

## 25.95 isa

    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

## 25.96 le

    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).

## 25.97 listcommands

    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:

## 25.98 listescape

    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

## 25.99 listfiles

    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

## 25.100 listglobals

    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

## 25.101 listobjects

    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

## 25.102 log

    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

## 25.103 logfile

    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

## 25.104 max

    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

## 25.105 maxerrors

    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

## 25.106 maxwarnings

    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

## 25.107 min

    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

## 25.108 move

    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

## 25.109 msgsubstitute

    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

## 25.110 notes

    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

## 25.111 objsubstitute

    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

## 25.112 openfile

    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

## 25.113 planarconnect

    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.

## 25.114 planardelay

    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.

## 25.115 planardelay2

    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

## 25.116 planarweight

    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.

## 25.117 planarweight2

    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

## 25.118 plane

    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

## 25.119 pope

    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

## 25.120 position

    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.

## 25.121 pow

    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

## 25.122 printargs

    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

## 25.123 printenv

    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

## 25.124 pushe

    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

## 25.125 putevent

    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.0

See also: playback

## 25.126 pwe

    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

## 25.127 quit

    Routine Name:   quit

    Description:    Exits from GENESIS, terminating any simulation in progress.

    Usage:          quit

    Notes:          Alias for exit routine.

## 25.128 rand

    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

## 25.129 randcoord

    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

## 25.130 randseed

    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

## 25.131 readcell

    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

## 25.132 readfile

    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

## 25.133 reclaim

    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

## 25.134 relposition

    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

## 25.135 resched

    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

## 25.136 reset

    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.doc.

                    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.

## 25.137 resetsynchanbuffers

    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

## 25.138 restore

    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

## 25.139 rotcoord

    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

## 25.140 round

    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

## 25.141 save

    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

## 25.142 scaletabchan

    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 .

## 25.143 setclock

    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

## 25.144 setdefault

    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

## 25.145 setenv

    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

## 25.146 setfield

    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

## 25.147 setfieldprot

    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

## 25.148 setglobal

    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

## 25.149 setmethod

    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

## 25.150 setparamGA

    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

## 25.151 setpostscript

    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

## 25.152 setprompt

    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

## 25.153 setrand

    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

## 25.154 setrandfield

    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

## 25.155 setsearch

    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

## 25.156 setupNaCa

    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

## 25.157 setupalpha

    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

## 25.158 setupgate

    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

## 25.159 setupghk

    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

## 25.160 setuptau

    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

## 25.161 sh

    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:

## 25.162 shapematch

    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

## 25.163 showclocks

    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

## 25.164 showcommand

    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:

## 25.165 showfield

    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

## 25.166 showmsg

    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

## 25.167 showobject

    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

## 25.168 showsched

    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

## 25.169 showstat

    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

## 25.170 silent

    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

## 25.171 simdump

    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 .

## 25.172 simobjdump

    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 .

## 25.173 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

## 25.174 sin

    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

## 25.175 spkcmp

    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

## 25.176 sqrt

    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:

## 25.177 stack

    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

## 25.178 step

    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

## 25.179 stop

    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

## 25.180 strcat

    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.

## 25.181 strcmp

    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

## 25.182 strlen

    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

## 25.183 strncmp

    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

## 25.184 strsub

    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:

## 25.185 substituteinfo

    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

## 25.186 substring

    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

## 25.187 swapdump

    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

## 25.188 syndelay

    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.

## 25.189 tab2file

    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 )

## 25.190 tan

    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

## 25.191 trunc

    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

## 25.192 tweakalpha

    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

## 25.193 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

## 25.194 useclock

    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

## 25.195 version

    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:

## 25.196 volumeconnect

    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.

## 25.197 volumedelay

    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.

## 25.198 volumedelay2

    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

## 25.199 volumeweight

    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.

## 25.200 volumeweight2

    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

## 25.201 where

    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.

## 25.202 writecell

    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

## 25.203 writefile

    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

## 25.204 xcolorscale

    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.

## 25.205 xgetstat

    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

## 25.206 xps

    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.

## 25.207 xsimplot

    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

Previous Next Table of Contents