salt

A Chicken Scheme library for equation-based modeling and simulations.

Usage

salt [options...] [input files ...]

Introduction

SALT is an implementation of a domain-specific language for equation-based model. This implementation follows the work of Tom Short and the Julia Sims.jl library (http:https://github.com/tshort/Sims.jl), which is in turn based on David Broman's MKL simulator and the work of George Giorgidze and Henrik Nilsson in functional hybrid modeling. Following Sims.jl, a nodal formulation is used based on David Broman's thesis (http://www.bromans.com/david/publ/thesis-2010-david-broman.pdf) :

David Broman. Meta-Languages and Semantics for
Equation-Based Modeling and Simulation. PhD thesis, Thesis No
1333. Department of Computer and Information Science, Linköping
University, Sweden,; 2010. 

Library procedures

parse :: DECLARATIONS -> ASTDECLS

Parses equation declarations in the syntax described in the next section, and returns an abstract syntax tree structure.

elaborate :: ASTDECLS -> EQUATIION-SET

Performs flattening of the given declarations and returns an equation set. The main steps in flattening are:

• Creation of a name resolution environment (parameters,fields,externals,constants,variables,functions).
• Replacing of fixed initial values.
• Flattening models and populating equation, definition, function lists.
• Populating list of initials.
• Populating event list from event and structural event definitions.
• Handles structural events.

simcreate :: EQUATION-SET -> SIMRUNTIME

Given an equation set, creates a simulation runtime representation.

codegen-ODE :: SIMRUNTIME -> ODE LIST

Given a simulation runtime representation, creates an abstract code representation aimed at ODE solvers.

codegen-ODE/ML

Given a simulation runtime representation, creates a code representation aimed at ODE solvers in the Standard ML language.

Model description language

Definitions

Definitions serve to define unknowns (state variables), parameters (constants during integration), and units of measurement.

    (define millivolt = unit Potential (1e-3 * volt)) 

    (define Vinit = parameter (dim Potential) -65.0 * millivolt) 

    (define v = unknown (dim Potential) -65.0 * mV) 

Equations

Equations serve to define differential and algebraic equations.

     ((der(u)) = (s - u) / tau)
     ((s) = b * ((v - a) ^ 3))

Events

     (event (v - Vthreshold)
            ((v := Vreset))
            )

Examples

;; Van der Pol oscillator
(define vdp 
  (parse 
   `(
     (define x = unknown -0.25)
     (define y = unknown 1.0)
     ((der(x)) = (1 - y ^ 2) * x - y )
     ((der(y)) = x)
     )
   ))


;; Izhikevich Fast Spiking neuron
(define izhfs 
  (parse 
   `(
     (define millivolt = unit Potential (1e-3 * volt))

     (define Isyn = parameter (dim Current) 0.0 * nA)
     (define Iext = parameter (dim Current) 400.0 * nA)

     (define k     = parameter 1.0)
     (define Vinit = parameter (dim Potential)  -65.0 * millivolt)
     (define Vpeak = parameter (dim Potential)   25.0 * mV)
     (define Vt    = parameter (dim Potential)  -55.0 * mV)
     (define Vr    = parameter (dim Potential)  -40.0 * mV)
     (define Vb    = parameter (dim Potential)  -55.0 * mV)
     (define Cm    = parameter (dim Capacitance) 20.0 * uF)

     (define FS_a = parameter  0.2)
     (define FS_b = parameter  (dim Current)   0.025 * nA)
     (define FS_c = parameter  (dim Potential) -45.0 * mV)
     (define FS_U = parameter  (dim Current) FS_b * (Vinit / mV))

     (define v  = unknown (dim Potential) -65.0 * mV)
     (define u  = unknown (dim Current) FS_U)
     (define s  = unknown (dim Current) 0.0 * nA)

     ((der(v)) = (((k * (v - Vr) * (v - Vt) / millivolt) + (((- u) + Iext) * megaohm)) / Cm) / megaohm)
     ((der(u)) = (FS_a * (s - u)) / ms)
     ((s) = FS_b * ((v - Vb) / mV) ^ 3)


     (event (v - Vpeak)
            ((v := FS_c)
             (u := u)
             (s := s)
             )
            )
     ))
  )


;; A routine to generate and compile Standard ML code 
(define (compile-model name model #!key (solver 'rk4b) (compile #f) (dir "tests"))
  (pp model)

  (define elab (elaborate model))
  (print "elaborate is done")
  (pp elab)

  (define sim (simcreate elab))
  (pp sim)
  (pp (codegen-ODE sim solver))
  (let* ((sml-path (make-pathname dir (string-append (->string name) ".sml")))
         (mlb-path (make-pathname dir (string-append (->string name) "_run.mlb")))
         (port (open-output-file sml-path)))
    (codegen-ODE/ML sim out: port solver: solver libs: '(interp))
    (close-output-port port)
    (if compile
        (run (mlton -mlb-path-var ,(sprintf "'SALT_HOME ~A'" SALT-DIR)
                    -mlb-path-var ,(sprintf "'RK_LIB $(SALT_HOME)/sml-lib/rk'")
                    -mlb-path-var ,(sprintf "'DYNAMICS_LIB $(SALT_HOME)/sml-lib/dynamics'")
                    ,mlb-path))))

)

(compile-model 'vdp vdp)
(compile-model 'izhfs izhfs)

Version history

• 0.22-0.28 : Various refactorings in support of CHICKEN 5
• 0.21 : Added step size controller
• 0.20 : Support for precise event time interpolation and adaptive solvers
• 0.5 : Support for using assigned quantities in external init equations
• 0.1 : Initial release

License

Copyright 2015-2020 Ivan Raikov

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A full copy of the GPL license can be found at http://www.gnu.org/licenses/.