### Navigation

- index
- modules |
- modules |
- next |
- previous |
- NEURON 7.3 documentation »
- neuron.exe/general »

# functions

PUT ALPHABETIC SEQUENCE JUMP TABLE HERE

## argument-related

`numarg`()
  Syntax:
    `n = numarg()`
  Description:
    Number of arguments passed to a user written hoc function.

  See also

  arguments, `argtype()`

`argtype`()
  Syntax:
    `itype = argtype(iarg)`
  Description:
    The type of the ith arg. The return value is 0 for numbers, 1 for objref, 2 for strdef, 3 for pointers to numbers, and -1 if the arg does not exist.

  See also

  arguments, `numarg()`

`hoc_pointer_`()
  Syntax:
    `hoc_pointer_(&variable)`
  Description:
    A function used by c and c++ implementations to request a pointer to the variable from its interpreter name. Not needed by the user.

## code-executing

`execute`()
  Syntax:

    `execute("statement")`

    `execute("statement", objref)`

  Description:
    parse and execute the command in the context of the object. If second arg not present then execute it at the top level of the interpreter. If command begins with a ‘~’ then the tilda is removed and the rest of the command is executed without enclosing it in {}. This allows one to create a func or proc dynamically.

  See also

  `execute1()`

`execute1`()
  Syntax:

    `err = execute1("statement")`

    `err = execute1("statement", objref)`

    `err = execute1("statement", show_err_mes)`

    `err = execute1("statement", objref, show_err_mes`

  Description:

    Same as `execute()` but returns 0 if there was an interpreter error during execution of the statement and returns 1 if successful. Does not surround the command with {}.

    If the show_err_mes arg is present and equal to 0 then the normal interpreter error message printing is turned off for the scope of the statement.

    Error messages can be turned on even inside the statement with `show_errmess_always()`.

    Parse and execute the command in the context of the object. If second arg not present then execute it at the top level of the interpreter.

  Example:

    Execute1 is heavily used in the construction of the fitter widgets. It is also useful to objects in gaining information about the outside with the idiom

        sprint(cmd, "%s.var = outside_var", this)
        execute1(cmd)

    Here, outside_var is unavailable from within the object and so a command is constructed which can be executed at the top level where that variable is available and sets the public var in the object.

## code-loading

`load_proc`()
  Syntax:

    `load_proc("name1", ...)`

    `load_func("name1", ...)`

    `load_template("name1", ..._`

  Description:

    Load the file containing a definition.

    For each name in the list all the `*.oc` and `*.hoc` files will be searched and the first file that contains the appropriate proc, func, or begintemplate will be loaded. Loading only takes place if the name has not previously been defined. The search path consists of the current working directory, followed by the paths in the environment variable HOC_LIBRARY_PATH (space separated), followed by `$NEURONHOME/lib/hoc`. Remember that only entire files are loaded– not just the definition of the name. And nothing is loaded if the name is already defined. Inadvertent recursion will use up all the file descriptors. For efficiency, on the first load, all the names are cached in a temporary file and the file is scanned on subsequent loads for that session.

  Warning

  This command is very slow under mswindows. Therefore it is often useful to explicitly load the standard run library with the statement:

      xopen("$(NEURONHOME)/lib/hoc/noload.hoc")

`load_file`()
  Syntax:

    `load_file("filename")`

    `load_file("filename", "name")`

    `load_file(0or1, "filename")`

  Description:

    Similar to `load_proc()` but loads files and so does not have the search overhead. Suitable for loading packages of files.

    The functionality is identical to `xopen()` except that the xopen takes place only if if a file of that name has not already been loaded with the load_file, `load_proc()`, `load_template()`, or `load_func()` functions. The file is searched for in the current working directory, $HOC_LIBRARY_PATH (a colon or space separated list of directories), and `$NEURONHOME/lib/hoc` directories (in that order) for the file if there is no directory prefix. Before doing the xopen on the file the current working directory is temporarily changed to the directory containing the file so that it can xopen files relative to its location.

    If the second string arg exists, the file is xopen’ed only if the name is not defined as a variable AND the file has not been loaded with load_file. This is useful in those cases where the package was first xopen’ed without going through the load_file function.

    If the first arg is a number and is 1, then the file is loaded again even if it has already been loaded.

  Description:

`load_func`()

  see `load_proc()`

`load_template`()

  see `load_proc()`

## equation-related

`prmat`()

  Prints the form of the matrix defined by eqn statements. Each nonzero element is printed as an “*”.

`solve`()

  Does one iteration of the non-linear system defined by eqn statements. Returns the linear norm of the difference between left and right hand sides plus the change in the dependent variables.

`eqinit`()

  Throws away previous dependent variable and equation specifications from eqn statements.

## error-handling

`coredump_on_error`()
  Syntax:
    `coredump_on_error(1 or 0)`
  Description:
    On unix machines, sets a flag which requests (1) a coredump in case of memory or bus errors.

`show_errmess_always`()
  Syntax:
    `show_errmess_always(boolean)`
  Description:
    Sets or turns off a flag which, if on, always prints the error message even if normally turned off by an `execute1()` statement or other call to the interpreter.

`execerror`()
  Syntax:
    `execerror("message1", "message2")`
  Description:
    Raise an error and print the messages along with an interpreter stack trace. If there are no arguments, then nothing is printed.

## interpreter management

`saveaudit`()

  Not completely implemented at this time. Saves all commands executed by the interpreter.

`retrieveaudit`()

  Not completely implemented at this time. See `saveaudit()` .

`quit`()

  Exits the program. Can be used as the action of a button. If edit buffers are open you will be asked if you wish to save them before the final exit.

## math

- math

## mcell_ran4

- mcell_ran4

## namespace-related

`name_declared`()
  Syntax:

    `type = name_declared("name")`

    `type = name_declared("name", 1)`

  Description:

    Return 0 if the name is not in the symbol table. The first form looks for names in the top level symbol table. The second form looks in the current object context.

    If the name exists return

    2 if an `objref()` .

    3 if a Section

    4 if a strdef

    5 if a scalar or double variable.

    1 otherwise

    Note that names can be (re)declared only if they do not already exist or are already of the same type. This is too useful to require the user to waste an objref in creating a `StringFunctions` class to use `is_name()`.

        name_declared("nrnmainmenu_")
        {object_push(nrnmainmenu_) print name_declared("ldfile", 0) object_pop()}
        {object_push(nrnmainmenu_) print name_declared("ldfile", 1) object_pop()}

`symbols`()
  Name:
    symbols — type the names of HOC functions and variables
  Syntax:
    `symbols()`
  Description:
    Types a list of functions and variable names defined in HOC. Dimensions of arrays are also indicated.

  Warning

  No longer works. The nearest replacement is `SymChooser()` .

## object-related

`object_id`()
  Syntax:

    `object_id(objref)`

    `object_id(objref, 1)`

  Description:

    Returns 0 if the object reference does not point to an object instance. (Otherwise returns the pointer cast to a double, not a very useful number)

    If the second argument is 1, it returns the index of the object name. Returns -1 if the object is the NULLObject.

`allobjectvars`()
  Syntax:
    `allobjectvars()`
  Description:
    Prints all the object references (objref variables) that have been declared along with the class type of the object they reference and the number of references.

  Warning

  Instead of printing the address of the object in hex format, it ought also to print the object_id and/or the internal instance name.

`allobjects`()
  Syntax:

    `allobjects()`

    `allobjects("templatename")`

    `nref = allobjects(objectref)`

  Description:

    Prints the internal names of all class instances (objects) available from the interpreter along with the number of references to them.

    With a templatename the list is restricted to objects of that class.

    With an object variable, nothing is printed but the reference count is returned. The count is too large by one if the argument was of the form templatename[index] since a temporary reference is created while the object is on the stack during the call.

`object_push`()
  Syntax:
    `object_push(objref)`
  Description:
    Enter the context of the object referenced by objref. In this context you can directly access any variables or call any functions, even those not declared as public. Do not attempt to create any new symbol names! This function is generally used by the object itself to save its state in a session.

`object_pop`()
  Syntax:
    `object_pop()`
  Description:
    Pop the last object from an `object_push()` .

## session-related

`print_session`()
  Syntax:

    `0 = print_session(useprinter, "name")`

    `0 = print_session(useprinter, "name", useselected)`

    `0 = print_session()`

  Description:

    Print a postscript file consisting of certain windows on the screen.

    If useprinter==1 postscript is piped to the filter given by “name” which should be able to deal with standard input (UNIX). If useprinter==0 the postscript is saved in the file specified by “name”.

    If there is a third arg equal to 1 then the printed windows are those selected and arranged on the paper icon of the Print & File Window Manager and calling this function is equivalent to pressing the Print button. Otherwise all printable windows are printed in landscape mode with a size such that the screen fits on the paper.

    If there are no arguments then all the windows are printed in way that works for mac, mswin, and unix.

`save_session`()
  Syntax:

    `0 = save_session("filename")`

    `0 = save_session("filename", "header")`

  Description:
    Save all the (saveable) windows on the screen to filename. This is equivalent to pressing the SaveAll button on the Print & File Window Manager. If the header argument exists, it is copied to the beginning of the file.

  See also

  `PWManager.save()`

`pwman_place`()
  Syntax:

    `pwman_place(left, top)`

    `pwman_place(left, top, 0)`

  Description:

    moves the PrintWindowManager to the indicated location in pixel coordinates where 0,0 is the top left corner of the screen. It is intended that if you build an interface by placing windows near the top and build right then the session you save will be portable to other window managers and other systems with different screen sizes.

    If the third argument is 0, then the window is placed but hidden.

`checkpoint`()
  Syntax:
    `checkpoint("filename")`
  Description:

    saves the current state of the system in a portable file to allow one to take up where you left off – possibly on another machine. Returning to this state is accomplished by running the program with the checkpoint file as the first argument. If the checkpoint file is inconsistent with the executable the program prints an error message and exits.

    At this time many portions of the computer state are left out of the checkpoint file, i.e. it is not as complete as a core dump. Some things that ARE included are: all interpreter symbols with definitions and values, all hoc instructions, all neuron state/parameters with mechanisms. Many aspects of the GUI are not included.

  Warning

  There is not enough implementation at this time to make this facility useful. Use the `SaveState` class instead.

## stopwatch

`startsw`()

  Initializes a stopwatch with a resolution of 1 second or 0.01 second if gettimeofday system call is available. See `stopsw()` .

`stopsw`()

  > Returns the time in seconds since the stopwatch was last initialized with a `startsw()` .

  >     startsw()
  >     for i=1,1000000 { x = sin(.2) ]
  >     stopsw()

  Warning

  Really the idiom

      x = startsw()
      //...
      startsw() - x

  should be used since it allows nested timing intervals.

## string

`sprint`()
  Syntax:
    `sprint(strdef, "format", args)`
  Description:
    Prints to a string. See `printf()`

`strcmp`()
  Syntax:
    `x = strcmp("string1", "string2")`
  Description:
    return negative, 0, or positive value depending on how the strings compare lexicographically. 0 means they are identical.

## system

`chdir`()
  Syntax:
    `chdir("path")`
  Description:
    Change working directory to the indicated path. Returns 0 if successful otherwise -1, ie the usual unix os shell return style.

`getcwd`()
  Syntax:
    `string = getcwd()`
  Description:
    Returns absolute path of current working directory in unix format. The last character of the path name is ‘/’. Must be less than 1000 characters long.

`machine_name`()
  Syntax:

    `strdef name`

    `machine_name(name)`

  Description:
    returns the hostname of the machine.

`system`()
  Name:
    system — issue a shell command
  Syntax:

    `exitcode = system(cmdstr)`

    `exitcode = system(cmdstr, stdout_str)`

  Description:
    Executes cmdstr as though it had been typed as command to a unix shell from the terminal. HOC waits until the command is completed. If the second strdef arg is present, it receives the stdout stream from the command. Only available memory limits the line length and number of lines.

  Example:

  > `system("ls")`
  >   Prints a directory listing in the console terminal window. will take up where it left off when the user types the `exit` command

  Warning

  Fully functional on unix, mswin under cygwin, and mac osx.

  Does not work on the mac os 9 version.

  Following is obsolete: Under mswin, executes the string under the cygwin sh.exe in `$NEURONHOME/bin` via the wrapper, `$NEURONHOME/lib/nrnsys.sh`. Normally, stdout is directed to the file `tmpdos2.tmp` in the working directory and this is copied to the terminal. The neuron.exe busy waits until the nrnsys.sh script creates a tmpdos1.tmp file signaling that the system command has completed. Redirection of stdout to a file can only be done with the idiom “command > filename”. No other redirection is possible except by modifying `nrnsys.sh`.

`neuronhome`()
  Name:
    neuronhome – installation path
  Syntax:
    `string = neuronhome()`
  Description:

    Returns the full installation path in unix format or, if it exists, the NEUROHOME environment variable in unix format.

    Note that for unix, it isn’t exactly the installation path but the –prefix/share/nrn directory where –prefix is the location specified during installation. For the mswin version it is the location selected during installation and the value is derived from the location of neuron.exe in neuronhome()/bin/neuron.exe. For mac it is the folder that contains the neuron executable program.

`show_winio`()
  Syntax:
    `show_winio(0or1)`
  Description:
    MSWin and Mac version only. Hides or shows the console window.

`WinExec`()
  Syntax:
    `WinExec("mswin command")`
  Description:
    MSWin version only.

`unix_mac_pc`()
  Syntax:
    `type = unix_mac_pc()`
  Description:
    Return 1 if unix, 2 if mac, 3 if mswin, or 4 if mac osx darwin is the operating system. This is useful when deciding if a machine specific function can be called or a dll can be loaded.

`nrn_load_dll`()
  Syntax:
    `nrn_load_dll(dll_file_name)`
  Description:
    Loads a dll containing membrane mechanisms. This works for mswin, mac, and linux.

`nrnversion`()
  Syntax:

    `versionstring = nrnversion()`

    `string = nrnversion(i)`

  Description:

    Returns a string consisting of version information. When this function was introduced the majorstring was “5.6” and the branch string was “2004/01/22 Main (36)”. Now the arg can range from 0 to 6. The value of 6 returns the args passed to configure. When this function was last changed the return values were

        oc>nrnversion()
        NEURON -- VERSION 7.1 (296:ff4976021aae) 2009-02-27
        oc>for i=0,6 print i,": ", nrnversion(i)
        0 : 7.1
        1 : NEURON -- VERSION 7.1 (296:ff4976021aae) 2009-02-27
        2 : VERSION 7.1 (296:ff4976021aae)
        3 : ff4976021aae
        4 : 2009-02-27
        5 : 296
        6 : '--prefix=/home/hines/neuron/nrnmpi' '--srcdir=../nrn' '--with-paranrn' '--with-nrnpython'
        oc>

  Warning

  An arg of 7 now returns a space separated string of the arguments used during launch. e.g.

      $ nrniv -nobanner -c 'nrnversion()' -c 'nrnversion(7)'
      NEURON -- VERSION 7.2 twophase_multisend (534:2160ccb31406) 2010-12-09
      nrniv -nobanner -c nrnversion() -c nrnversion(7)
      $

  An arg of 8 now returns the host-triplet. E.g.

      $ nrniv -nobanner -c 'nrnversion(8)'
      x86_64-unknown-linux-gnu

  An arg of 9 now returns “1” if the neuron main program was launched, “2” if the library was loaded by Python, and “0” if the launch progam is unknown

      $ nrniv -nobanner -c 'nrnversion(9)'
      1

      $ python 2</dev/null
      >>> from neuron import h
      >>> h.nrnversion(9)
      '2'

## user interface

`ivoc_style`()
  Syntax:
    `ivoc_style("name", "attribute")`
  Description:
    Gives the style attribute to name. Any property listed in the file `$(NEURONHOME)/lib/nrn.defaults` or `$(NEURONHOME)/src/ivoc/ivocmain.c` can be changed although it may be that a few of them have already been used by the time the interpreter is invoked.

  Example:

  >     // 7 decimal places in value field editors. Must be done prior to any panel.
  >     ivoc_style("*xvalue_format", "%.7g")
  >     // large fonts in unix. Takes effect on next panel.
  >     ivoc_style("*font", "*helvetica-medium-r-normal*--24*")
  >     ivoc_style("*MenuBar*font", "*helvetica-medium-r-normal*--24*")
  >     ivoc_style("*MenuItem*font", "*helvetica-medium-r-normal*--24*")

`variable_domain`()
  Syntax:

    `variable_domain(&variable, lower_limit, upper_limit)`

    `variable_domain("varname", lower_limit, upper_limit)`

  Description:

    Define the domain limits for any variable for which one can take its address. At this time only field editors check the variable domain. If one attempts to enter a value into a field editor which is not in the domain, the value will be set to the upper or lower limit. Important NEURON variables such as dt, L, diam, and Ra have reasonable default domains. Many parameters defined in model description files also have reasonable domains.

    This function is most useful when a variable makes sense only as a non-negative or positive number.

    One can specify different domains only on a per name basis. Thus there is only one domain specification for L and one for all the instances of IClamp.amp but one can have a different specification for IClamp.amp and VClamp.amp .

`units`()
  Syntax:

    `current_units = units(&variable)`

    `current_units = units(&variable, "units string")`

    `"on or off" = units(1 or 0)`

    `current_units = units("varname", ["units string"])`

  Description:

    When units are on (default on) value editor buttons display the units string (if it exists) along with the normal prompt string. Units for L, diam, Ra, t, etc are built-in and units for membrane mechanism variables are declared in the model description file. See modlunit . Note that units are NOT saved in a session. Therefore, any user defined variables must be given units before retrieving a session that shows them in a panel.

    The units display may be turned off with `units(0)` or by setting the `*units_on_flag: off` in the nrn/lib/nrn.defaults file.

    `units(&variable)` returns the units string for any variable for which an address can be taken.

    `units(&variable, "units string")` sets the units for the indicated variable.

    If the first arg is a string, it is treated as the name of the variable. This is restricted to hoc variable names of the style, “name”, or “classname.name”. Apart from the circumstance that the string arg style must be used when executed from Python, a benefit is that it can be used when an instance does not exist (no pointer to a variable of that type). If there are no units specified for the variable name, or the variable name is not defined, the return value is the empty string.

  Example:

  >     units(&t) // built in as "ms"
  >     units("t")
  >     units("ExpSyn.g") // built in as "uS"
  >     x = 1
  >     {units(&x, "mA/cm2")}       // declare units for variable x
  >     units(&x)           // prints mA/cm2
  >     proc p () {
  >         xpanel("Panel")
  >         xvalue("t")
  >         xvalue("prompt for x", "x", 1)
  >         xpanel()
  >     }
  >     p()         //shows units in panel
  >     units(0)    // turn off units
  >     p()         // does not show units in panel

  Warning

  In the Python world, the first arg must be a string as the pointer style will raise an error.

`boolean_dialog`()
  Syntax:
    `boolean_dialog("label", ["accept", "cancel"])`
  Description:
    Pops up a dialog window at the center of the screen and blocks everything until dealt with. Returns 1 or 0.

See also

`SymChooser`, `VBox.dialog()`

`continue_dialog`()
  Syntax:
    `continue_dialog("label")`
  Description:
    Provides info to the user. Like `boolean_dialog()`, blocks everything until dealt with.

`string_dialog`()
  Syntax:
    `string_dialog("label", strdef)`
  Description:
    Returns 0 if canceled and strdef remains unchanged. Like `boolean_dialog()`, blocks everything until dealt with.

### Navigation

- index
- modules |
- modules |
- next |
- previous |
- NEURON 7.3 documentation »
- neuron.exe/general »