VFGEN § Vector Field File

VFGEN Vector Field File Format

VFGEN uses an XML file to define a vector field. The top-level element is a VectorField. The following table gives the elements that can be used to define a vector field.

Element	Attributes	Req?	Default Value	Comment
VectorField	Name	Yes	None
	IndependentVariable		"t"
	Description		""
Constant	Name	Yes	None
	Description		""
	Value	Yes	None	Must be a numerical constant, or a formula that involves only numerical values and previously defined Constants.
Parameter	Name	Yes	None
	Description		""
	DefaultValue		"0"	Can be an expression involving any Constants and previously defined Parameters.
Expression	Name	Yes	None
	Description		""
	Formula	Yes	None
StateVariable	Name	Yes	None
	Description		""
	Formula	Yes	None	The component of the vector (i.e. the "right hand side") for this variable.
	PeriodFrom		None	If either is given, both must be given.
	PeriodTo		None	If either is given, both must be given.
	DefaultInitialCondition		"0"
	DefaultHistory		(value of DefaultInitialCondition)	Used by some commands for delay equations. Defines the value of the variable for t < 0.
Function	Name	Yes	None
	Description		""
	Formula	Yes	None

Some notes:

The first line of the vector field file must be
<?xml version="1.0" ?>
All elements must have a Name attribute.
All elements have an optional Description attribute.
The Formula of an Expression can be a mathematical expression involving Constants, Parameters, StateVariables, or previously defined Expressions.
The Formula of a StateVariable defines the component of the vector field for that state variable. It can be a mathematical expression involving Constants, Parameters, other StateVariables, and Expressions.
If either of the StateVariable attributes PeriodFrom or PeriodTo are specified, they both must be specified. These are used to indicate that the variable is periodic, and they give the fundamental domain of the variable. (See the pendulum.vf example below.)
The Formula of a Function can be a mathematical expression involving Constants, Parameters, StateVariables, and Expressions.
The Formula of a Function must not use the delay() function.
The symbol Pi is predefined and may be used in any formula or expression.

I have followed the convention of always using the extension .vf for vector field files. This is not a requirement.

Delay Equations

The vector field file format allows the definition of delays with the expression delay(expression,h). For example delay(x,1) means x(t-1), and delay(S*I,tau) means S(t-tau)*I(t-tau) (assuming S and I are state variables and tau is a parameter).

Five of the VFGEN commands support delays: dde23, ddebiftool, dde_solver_m, delay2ode and xpp.

Example 1: pendulum.vf

The differential equations are

θ'	=	v
v'	=	-bv/(mL²) - (g/L)sin(θ)

The state variable are θ and v. The parameters are g, b, L, and m.

Here is the file pendulum.vf, in which this vector field is defined:

<?xml version="1.0" ?>
<VectorField
    Name="pendulum"
    Description="Pendulum Vector Field">
<Parameter
    Name="g"
    Description="gravitational constant"
    DefaultValue="9.81" />
<Parameter
    Name="b"
    Description="friction constant"
    DefaultValue="0.0" />
<Parameter
    Name="L"
    Description="pendulum length"
    DefaultValue="1.0" />
<Parameter
    Name="m"
    Description="mass"
    DefaultValue="1.0" />
<StateVariable
    Name="theta"
    Description="Angle, measured from straight down"
    Formula="v"
    PeriodFrom="0"
    PeriodTo="2*Pi"
    DefaultInitialCondition="Pi-0.01" />
<StateVariable
    Name="v"
    Description="angular velocity"
    Formula="-b*v/(m*L^2)-(g/L)*sin(theta)"
    DefaultInitialCondition="0.0" />
<Function
    Name="energy"
    Description="total energy (kinetic plus potential)"
    Formula="m*L^2*v^2/2 - m*g*L*cos(theta)" />
</VectorField>

Example 2: hopftest.vf

The differential equations are

x'	=	μx + ωy + (x²+y²)x
y'	=	- ωx + μy + (x²+y²)y

Here is the file hopftest.vf, in which this vector field is defined:

<?xml version="1.0"?>
<VectorField Name="hopftest">
<Parameter Name="mu" />
<Parameter Name="omega" />
<Expression Name="rr" Formula="x^2+y^2" />
<StateVariable Name="x" Formula="mu*x+omega*y+rr*x" />
<StateVariable Name="y" Formula="-omega*x+mu*y+rr*y" />
</VectorField>

Example 3: MackeyGlass.vf (a delay equation)

The Mackey-Glass equation is

x'(t) = -b*x + a*x(t-τ)/(1+x(t-τ)¹⁰)
A vector field file for this system is MackeyGlass.vf:

<?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>

Note the use of delay(x,tau) in the Expression called delayedx.