# User:Warren Weckesser/Proposed/VFGEN

## Introduction

VFGEN is a computer program for generating system definition files for a wide variety of computational programs and libraries. A system definition file is a file used by a program or library to define the equations to be solved. Typically this file is a function written in the same programming language as the library to be used. A researcher interested in using several different tools to study a set of equations must implement a system definition file for each tool. This can be a tedious and error-prone process. VFGEN alleviates this problem by allowing for the creation of a universal system definition file. From this single file, VFGEN can generate system definition files for a wide variety of tools, including: the programming environments MATLAB, Octave and SciLab; Fortran libraries such as LSODA and DDE_SOLVER; scientific libraries such as the GNU Scientific Library and Python's SciPy; and specialized bifurcation analysis tools such as AUTO.

VFGEN also provides specialized commands for extending a vector field with its variational equation, converting delay equations to finite dimensional approximations, and for generating C code to compute Taylor polynomial approximations (of any given order) to the solution to a differential equation. It also has a command to generate a complete Taylor method solver written in Javascript along with an HTML interface. With this feature, a complete solver with a GUI interface is created that runs in any web browser that supports Javascript.

The tables below show available output formats. The following examples illustrate typical uses of VFGEN. More examples are given on the VFGEN web site.

## Example: The Rössler System of Ordinary Differential Equations

The Rössler system is

$\begin{split} \dot{x} & = -y - z \\ \dot{y} & = x + ay \\ \dot{z} & = b + z(x-c) \\ \end{split}$

(See Rossler attractor.) This system of ordinary differential equations has three state variables, $x$, $y$ and $z$, and three parameters, $a$, $b$ and $c$. A VFGEN system definition file for these equations is:

<?xml version="1.0" ?>
<VectorField Name="rossler" >
<Parameter Name="a" DefaultValue="0.17" />
<Parameter Name="b" DefaultValue="0.4" />
<Parameter Name="c" DefaultValue="8.5" />
<StateVariable Name="x" Formula="-(y+z)"       DefaultInitialCondition="0.01" />
<StateVariable Name="y" Formula="x+a*y"        DefaultInitialCondition="0" />
<StateVariable Name="z" Formula="b + (x-c)*z"  DefaultInitialCondition="0" />
</VectorField>


The outermost XML element is the VectorField. It contains definitions of the three parameters ($a$, $b$, $c$), and the three state variables ($x$, $y$, $z$). Included in the definition of each state variable is the formula for the variable's rate of change (i.e. the right hand side of the differential equation).

Call the Rössler system definition file rossler.vf. From this file, VFGEN can generate system definition files for a variety of differential equation solvers. For example, SciPy is a scientific computing library for the Python language. It includes the function odeint (in the package scipy.integrate) that solves ordinary differential equations. To generate the appropriate Python code for solving the Rössler system with odeint, the VFGEN command scipy can be used as follows:

vfgen scipy:demo=yes rossler.vf


(Note: VFGEN is a command line program. The above is a command that is run in terminal.)

The option demo=yes was used, so VFGEN will generate a program that demonstrates the use of the odeint function with the Python implementation of the Rössler system. The command generates two files: rossler.py and rossler_demo.py. rossler.py defines two Python functions, vectorfield and jacobian, that can be used by the SciPy function odeint to solve the system. rossler_demo.py is a script that uses rossler.py with odeint to generate a solution. Running the script as follows:

python rossler_demo.py x=-14 y=0 z=0 stoptime=100 numpoints=1500 > sol.dat


writes the solution to sol.dat. The command line options set the initial conditions, the stop time, and the number of time samples to include in the output. The following is a plot of the ($x$, $y$) coordinates of this solution:

## Example: The Mackey-Glass Delay-Differential Equation

One form of the Mackey-Glass equation is:

$\dot{x} = -bx + \frac{ax(t-\tau)}{1+x(t-\tau)^{10}}$

This can be encoded in a VFGEN system definition file as:

<?xml version="1.0"?>
<VectorField Name="MackeyGlass">
<Parameter Name="a" DefaultValue="0.2" />
<Parameter Name="b" DefaultValue="0.1" />
<Parameter Name="tau" DefaultValue="17.0" Description="Delay time" />
<Expression Name="delayedx" Formula="delay(x,tau)" Description="x(t-tau)" />
<StateVariable Name="x" Formula="-b*x+a*delayedx/(1+delayedx^10)"
DefaultInitialCondition="0.5" DefaultHistory="0.5+0.02*t" />
</VectorField>


The delay term $x(t - \tau)$ is defined in an Expression element named delayedx. This name is then used in the formula for the rate of change of the state variable $x$.

Assuming the system definition file is called MackeyGlass.vf, VFGEN generates Fortran 90 code suitable for use with the DDE_SOLVER library developed by Shampine and Thompson with the command:

vfgen dde_solver:demo=yes MackeyGlass.vf


The code generated by this command can be compiled with a Fortran 90 compiler such as gfortran as follows:

gfortran MackeyGlass.f90 MackeyGlass_demo.f90 dde_solver_m_unix.f90 -o MackeyGlass_demo


The following is a plot of the data generated by MackeyGlass_demo, after the variable stoptime in MackeyGlass_demo.f90 was changed to 500:

## Available Code Generation Formats

The following table lists the VFGEN commands that generate code for specific libraries, tools or programming environments.

Program/Library Description VFGEN Command
AUTO Continuation program auto
CVODE ODE solver library (part of the SUNDIALS suite) cvode
DDE23 MATLAB delay equation solver dde23
DDE-BIFTOOL MATLAB program for the bifurcation analysis of DDEs ddebiftool
DDE_SOLVER FORTRAN library for solving DDEs dde_solver
DSTool Application for dynamical systems analysis dstool
GNU Scientific Library: ODE solvers C library for solving ODEs gsl
LaTeX Text processer latex
LSODA (and other ODEPACK functions) ODEPACK contains a suite of FORTRAN ODE solvers, including LSODE, LSODA, and LSODAR. lsoda
MatCont MATLAB application for continuation matcont
MATLAB MATLAB ODE solver functions matlab
Octave Octave ODE solver functions octave
PDDE-CONT Continuation of periodic solutions to DDEs pddecont
PyDSTool Python framework for the analysis of dynamical systems pydstool
PyGSL Python binding of the GNU Scientific Library pygsl
Scilab Scilab ODE solver functions scilab
SciPy Scipy ODE solvers scipy
XPPAUT Application for the analysis of dynamical systems xpp

These commands do not generate code for a specific solver or library.

VFGEN Command Description
evf Extend a vector field with its variational equations. This creates a new vector field with twice as many equations as the original.
taylor Generates code for computing derivatives of the solution and the Taylor polynomial at a point.
javascript Generates javascript code that implements a Taylor method solver for the vector field, and generates an HTML page with a GUI for setting parameters and initial conditions, and for animating the solution to the equations.
delay2ode Converts a delay equation into a system of ordinary differential equations, the solutions of which are approximate solutions to the delay equation.