Basic Use: A short overview

Since hsolve is only a computation engine, it has no knowledge of your model (number of equations, morphology, ...). The first step in using hsolve is always a step of model construction without using hsolve at all. The next step is creating and configuring hsolve such that it knows what (part of) the model to compute and how to compute it. Then you inform hsolve that everything is in place and it may do its internal initialization. After the usual 'reset', you can start the simulation.

If we want to compute two coupled compartments with Hodgkin-Huxley channels, this may look like the following:

1. Write your scripts as if you are not using hsolve at all:
   1. Set the simulation clock(s).

       genesis > setclock 0 0.0000030
      

      
      
      

      NOTE: Never forget to set the main simulation clock. If you do not do so, hsolve will be confused and can produce unexpected results.

      
      
      

   2. Create the model you want to simulate: create all the elements, set all their fields and create messages between them. In this example we create two coupled compartments each containing a fast sodium conductance and a delayed rectifier conductance. For hsolve it is important that these channels are below the compartments they belong to in the Genesis element hierarchy:

       genesis > create neutral /cell
       genesis > ce /cell
       genesis > create compartment c1
       genesis > setfield c1 Ra 0.5 Rm 10 Cm 0.01 Em -0.065
       genesis > copy /library/NaF c1/NaF
       genesis > addmsg c1 c1/NaF VOLTAGE Vm ; addmsg c1/NaF c1 CHANNEL Gk Ek
       genesis > copy /library/Kdr c1/Kdr
       genesis > addmsg c1 c1/Kdr VOLTAGE Vm ; addmsg c1/Kdr c1 CHANNEL Gk Ek
       genesis > copy c1 c2
       genesis > addmsg c1 c2 AXIAL Vm ; addmsg c2 c1 RAXIAL Ra Vm
      

      
      
      

      NOTE: In this example all elements use the same simulation clock i.e. clock 0. When you want to use hsolve on elements that use different simulations clocks, reconfigure the model such that they all use the same simulation clock. Afterwards migrate to hsolve.

      
      
      

2. Create and configure hsolve:
   1. Create hsolve element at the right location.

       genesis > ce /cell
       genesis > create hsolve solver
      

   2. Set the 'path' field with a wild card to match the compartments to be computed. The 'path' field is always specified relative to the hsolve element (not to the current working element). In this example the full path specification is "/cell/solver/../##[][TYPE=compartment]", which is the same as "/cell/##[][TYPE=compartment]". Configure hsolve further by setting other fields like chanmode and calcmode if needed (it is not needed in this example). We will cover these fields in one of the next sections.

       genesis > setfield solver path "../##[][TYPE=compartment]"
      

   3. Set the numerical method to use for the computations done by hsolve (normally one always uses Crank-Nicolson, i.e. method 11).

       genesis > setmethod solver 11
      

      
      
      

      NOTE: Never forget to set the method to backward-Euler (method 10) or Crank-Nicolson (method 11). If you do not do so, hsolve will be confused and can produce unexpected results.

      
      
      

3. Initialize hsolve:
   1. Call the SETUP action on hsolve. This allows hsolve to do its internal initialization. Basically hsolve will examine the structure of the model and compile it into an internal efficient representation. All operations up till this step may only be performed once.

       genesis > call solver SETUP
      

   2. Do other things of interest to your simulation (don't touch the elements that will be computed by hsolve).

       genesis > ...
      

   3. Call the RESET action on hsolve (this is automatically done by the Genesis 'reset' command). This will transfer and convert all initial values into hsolve's internal data structures. This step can be repeated as many times as needed since it does not alter the model's structure.

       genesis > reset
      

4. Do the simulation ('step' command).

    genesis > step 1 -time
   

That's it, here is again the full code:

       genesis > create neutral /cell
       genesis > ce /cell
       genesis > create compartment c1 -initVm
       genesis > setfield c1 Ra 0.5 Rm 10 Cm 0.01 Em -0.065
       genesis > copy /library/NaF c1/NaF
       genesis > addmsg c1 c1/NaF VOLTAGE Vm ; addmsg c1/NaF c1 CHANNEL Gk Ek
       genesis > copy /library/Kdr c1/Kdr
       genesis > addmsg c1 c1/Kdr VOLTAGE Vm ; addmsg c1/Kdr c1 CHANNEL Gk Ek
       genesis > copy c1 c2
       genesis > addmsg c1 c2 AXIAL Vm ; addmsg c2 c1 RAXIAL Ra Vm
       genesis > ce /cell
       genesis > create hsolve solver
       genesis > setfield solver path "../##[][TYPE=compartment]"
       genesis > setmethod solver 11
       genesis > call solver SETUP
       genesis > ...
       genesis > reset
       genesis > step 1 -time

NOTE: Depending on the circumstances, the hsolve element can be created automatically. An example is the use of the '-hsolve' option of the 'readcell' command in which case the path field is also set to point to the compartments of the cell that is being read. Currently an annoying bug in the readcell code obliges you to use absolute pathnames for the created elements if you use this option.

NOTE: In the example given above all elements use clock zero. It must be noted that hsolve computes all variables using the same clock (so the same time step). If you only use the elements that act as a model for hsolve, you have the flexibility to use different clocks for different elements (so different time steps for different elements).

It is useful to discuss how Genesis deals with hsolve. Without hsolve, all elements you create, are responsible for their own calculations. A compartment for example will compute a (cylindrical) cable equation using the exponential-Euler rule and has some facilities to communicate certain variables to or from other elements (via the Genesis message system). When using hsolve however, hsolve does the computations as shown in figure 2.1. Depending on the configuration of hsolve - something that will be discussed in the next section - hsolve is able to use the facilities of the original objects to communicate with other elements, but it is also able to use its own internally optimized communication facilities.

Figure 2.1: Normally all Genesis elements in the element hierarchy - represented by the boxes in these pictures - do their own computations (as indicated by the toot-wheels). When using hsolve, computations of some or all of the elements in the model are done by hsolve, the original elements for which hsolve does the computations only serve as a model description. In chanmode 0 (middle panel) only compartments are computed by hsolve, while in chanmode 4 (lower panel) all elements are computed by hsolve.