The original version of this package was written by J. Wathey and W. Lytton in 1988. This version was simulator based and permitted automatic saving of parameter files similar to a current NEURON function which dumps parameters. The program also maintained an index file with comments by the user. These modifications also permitted coordination with graphic and file output and insured that simulations would not be run without critical parameters being set, a frequent pitfall of the modeling enterprise.
These modifications had been made directly in NEURON source code. This was a mistake, though it had the advantage of being fully integrated into the simulation system which gave immediate access to all relevant parameters. The disadvantage was that these modifications were directly linked with the program's data structures. Unfortunately, as new versions of the simulator have been developed, these data structures have repeatedly changed, rendering the modifications unworkable. Therefore, the package was rewritten using code external to the simulator. This has required a change in philosophy. In the previous version, files were created that were guaranteed (limited liability warranty anyway) to correspond to the simulation just run. In the new SIMCTRL, the user makes changes directly in parameter files. These changes are secondarily communicated to the NEURON simulator. Therefore, the user must beware the temptation of making changes directly in the simulator, for such changes would be lost. Fortunately, this is never necessary and only rarely an attractive shortcut.
Nomenclature notes: in EMACS a buffer is a text area that can contain the contents of a file or an interactive program such as a simulator. EMACS typically runs in a X-windows window (which it calls a frame) and uses the term "window" to denote one of the subdivided areas which display a buffer. File is used in the normal way to refer to something saved to disk. Usually, a buffer name will be the same as the name of the associated file. However, this is not always the case. For example the RCS handler will append a version number to the name.
The use of RCS in simulation control differs slightly from the way it was originally conceived. RCS is meant to be used by a team of programmers who share code and need to avoid working on the same file at the same time. In simulation control we are generally working on a project alone and don't need all of the added baggage of locking files to prevent access by others while we're working on something. For this reason, and to integrate it into the whole package, SIMCTRL provides simplified commands that cycle through the checkin, checkout and chmod processes to update the archive and restore a writable version.
Standard RCS version numbers consists of 2 numbers separated by a decimal point, used typically to denote version and revision (eg WINDOWS version 3.5). SIMCTRL only uses the number to the right of the decimal point and suppresses the '1.' Thus in SIMCTRL, you might be working with version '17' of a file but when you use RCS directly from the shell you would refer to version '1.17'.
Files checked in under RCS should have a comment at the top of the form
// $Id: neuremacs.dol,v 1.4 1998/08/02 15:58:22 billl Exp $
(or : $Id: neuremacs.dol,v 1.4 1998/08/02 15:58:22 billl Exp $ in a mod file)
at the top. This will expand to give a
details about file creation time, creator, and importantly for
SIMCTRL, a version number: eg
// $Id: neuremacs.dol,v 1.4 1998/08/02 15:58:22 billl Exp $
Under SIMCTRL, the index file defines a set of files used for a particular project located in a particular directory. The EMACS buffer containing this file may have a name that reflects the enclosing directory. NEURON involves mod files and other files in different subdirectories. A single 'index' file is maintained, not one for each subdirectory. However, if one is doing a variety of different projects, different index files will be used for the different projects.
The index file is the key to the management of the simulation and the simulation history. The emacs buffer containing this file is the central control point for simulation parameters. When a simulation is run the buffers name will be changed
Here is how a typical index file might look:
%% geom.hoc templates.hoc syncnl.hoc (5.3.7)
@@ network.hoc params.hoc run.hoc
98feb25.02 [3.21.11] try saving again with inj=0.27
98jan20 params.hoc [3.22.11] remove everything but cat1 and Pass
98feb25 nrnoc.hoc (1.14) syn commands had delay and on mixed up
98feb25.03 [3.23.11] had misprint in all the above params file with
erev capitalized
98feb25 cadxp.mod (1.7) restore old integration routine
98feb25 parameters.multi (1.3) include vardt and cadxp mod files
@@ random.hoc network.hoc params.hoc run.hoc
98feb25.04 [3.1.24.11] seems to be a discrepancy since I can
get repeated spiking with 0.27 for 5 msec
There are two types of files represented, templates and parameters. Templates will typically be loaded only once at the beginning (they do not redefine happily in hoc). These are on a line starting with '%%' along with their version numbers (in this case 5, 3 and 7 respectively). They are loaded using the command 'nrn-load- templates'. (As noted above, version numbers are handled with '1.' assumed).
The '@@' shows files that are needed to run particular simulations and the order in which they should be loaded. A new '@@' line supersedes the previous one as shown here. Therefore, it is possible to change the files that need to be loaded. Specific simulations are identified by date and run number (runnum in NEURON): eg 98feb25.03. The numbers after this show the version numbers of the files required to obtain that simulation. In this case [3.23.11] means RCS versions 1.3, 1.23 and 1.11 of geom.hoc, params.hoc and run.hoc, respectively (the 1. is assumed). When you save a simulation, all of this is put in automatically after you enter the comment. Information on other files that may be important to the simulation are also stored here. These entries are in the full RCS style (eg nrnoc.hoc version 1.24) with the version number in parentheses. If you update an individual sim file by itself using rcs-delta-file, emacs will put the comment in and keep track of the updated version number. 'rcs-delta-file' will also generate a new template line if you change one of the template files.
In order to run neuron, a directory must be initialized containing the proper subdirectories. This is done with mknrndir. which creates the needed directoriess and files for NEURON simulations, including RCS, data and mod directories and an empty version of the needed files. The arguments given are 2 lists of hoc files: template files and simulation files. For example mknrndir "geom.hoc syncnl.hoc" "params.hoc run.hoc". These files must already exist in the directory.
NEURON can be run using the emacs command 'run-neuron'. The easiest way to do this is to start in any buffer associated with that simulation (ie a file in that directory or one of the subdirectories). Alternatively, an emacs prefix arg ^u) can be used to permit you to give a directory.
Having done this you should be in the neuron buffer with the initialization complete. The neuron buffer will either be named neuron or will be named after the directory that the index file is in. The neuron buffer is interactive; it is pretty much the same as a neuron session running in any other shell environment. One pitfall: control characters to be sent to neuron (ie ^c or ^d) must be preceded by ^c in EMACS (eg ^c^d).
When neuron is launched a header will indicate several environmental variables and their values. If some of these are screwed up, neuron may not run. Environment values must then be reset in EMACS (setenv commands in elisp) or EMACS must be relaunched from a shell that has had the environment properly set.
Several methods are available to keep track of simulation organization. First, most of the information is provided in the index file as described above. Second, the command 'sim-rcs-status' ^x?) will allow you to see what versions are current or allow you to show diffs between current files and the original versions. This can also be used to demonstrate differences between sets of files. This is done by using ^x?d with the point located on a particular index line to be compared to. If two old sims need to be compared one of them must first be checked out using ^x?r followed by ^x?d from another line. Note that ^x?r will overwrite the current files which should have already been checked in. Third, the command 'sim-portrait', used with the prefix arg ^u, will give a fuller description of all of the buffers and their use. Also note that ^xz can be used to move around among simulation buffers. This is particularly useful if one is running several different simulations, each of which might have a different file named params.hoc. From any buffer associated with a simulation, ^xz will take one to the proper buffer associated with that same simulation.
The simulation can then be loaded with ^xl or with 'load-sim' under the 'Sim' menu on the emacs menu bar. Either way, it will open up another buffer which may ask you questions if discrepancies are found during the load sequence. The simulation will be loaded and you will be returned to the neuron buffer.
^xz (sim-switch-to-buffer) is a key binding in all simulation files that will give you a completion list for changing to other buffers involved in that simulation. This is therefore an alternative to ^xb (switch-to-buffer). This will restrict your choices to only buffers of interest. The default is to switch to the simulation file. Instead of using an initial string for completion, it is possible to use any substring (eg 'dex' for 'index') and a search will be performed.
The previous solution to this problem was to write a 'dump_parameters()' routine in NEURON which would save the state of the simulator. Since SIMCTRL does not have access to the innards of NEURON, the approach to preserving parameter file correspondence now goes backwards. Ideally, nothing should be entered directly into the interpreter. Instead the various simulation files are edited in emacs. The key binding '^-RET' is used to send one line to NEURON and save the file. There are also key bindings to load a region ^xw) or a procedure ^xp) into NEURON. If point and mark are identical (ie no region) then ^xw will load a block delimited by {}. Simulation files are always up to date since everything is being entered directly into them.
The system comprises three parts which are found in 3 elisp source files: simctrl.el, nrn.el, hoc.el. Simulation control is in simctrl.el. I tried to make this as general as possible so that it can in the future be used with other simulation packages as well. 'simctrl.el' handles the index file, rcs control. 'nrn.el' controls the actual NEURON process. All input and output is filtered by these routines. 'hoc.el' handles editing in the hoc buffer. It also permits lines, regions, or whole procedures to be sent directly to NEURON.
EMACS-RCS permits access to all versions of a file using the command rcs-get-file which will ask for the filename (default current buffer's file) and the version number (default most recent). You will be looking at a version of the file in a buffer. Here is where you can get confused. If you save this file you will save it as "file.tmp" not as "file". This is done because when you are looking at and comparing multiple versions of "file" it is easy to overwrite (and lose) your current version with some old version that you are playing around with. Therefore if you pull up something with 'rcs-get-file' and want to make this the current version that you're working on, immediately save it explicitly as "filename" without ".tmp".
Once you have edited a file. You make a bunch of changes, debug your routines and have gotten far enough along that you want to save the version. You may want to look at the changes you have made by using 'rcs-diffs' in emacs. You can give this 0,1 or 2 version numbers with the default being to compare current buffer to most recent version. Looking at the diff will help you come up with a comment. Then you do 'rcs-delta-file' and it will ask for your comment. You can type as long as you want and can move around with ^a^b^f^e as usual. The comment will be formatted for you in the index file. You will get back your new version of the file in a writable form. This whole process involves the sequence "rcs -l,ci,chmod" as well as multiple writes and reads.
If you make only trivial changes (eg indentation) that do not themselves warrant a version number, you can simply amend the previous version using rcs-fix-file. This will replace the last version of that file with the version you have on the buffer without altering the comment. This should be used sparingly since it is all too easy to replace a working version with a non-working one after having made some innocuous seeming changes.
You can look at the log of version comments for that file by entering 'log' instead of the version number with rcs-get-file. Note that this will just give the comments for this one file while the index will have comments for multiple files. You can also get the log header by enter 'h' for the version (like 'rcs -h'). This contains useful information such as access permissions and locking status.
When using a file that is shared with other people you will need to be concerned with 'locking' and 'unlocking' that file. In EMACS, little utility programs do this: 'rcs-lock-file', 'rcs-unlock-file'. If you are going to be using a file and don't want anyone else to mess with it, then lock it. You may first want to be sure that no one else is already locking it by checking the log or log header (rcs-get-file with 'log' or 'h' for the version). Now you can edit it just as discussed above. When you have a finished version (ie debugged) you can do rcs-delta-file to check it in. This will create a new version that will come up unlocked.
Copyright ©1998 WW Lytton, all rights reserved