Next: The chanmode Field: Modes Up: Introducing Hsolve for Single Previous: Introducing Hsolve for Single Contents

#
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`.

Next: The chanmode Field: Modes Up: Introducing Hsolve for Single Previous: Introducing Hsolve for Single Contents