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.
	Latex		None	Latex expression to use in the output of the latex command
Parameter	Name	Yes	None
	Description		""
	DefaultValue		"0"	Can be an expression involving any Constants and previously defined Parameters.
	Latex		None	Latex expression to use in the output of the latex command
Expression	Name	Yes	None
	Description		""
	Formula	Yes	None
	Latex		None	Latex expression to use in the output of the latex command
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.
	Latex		None	Latex expression to use in the output of the latex command
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).

Seven of the VFGEN commands support delays: dde23, ddebiftool, dde_solver, delay2ode, pddecont, r 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) = -bx + ax(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.

More Examples

Here are additional examples of vector field files. Many of these are used as examples in various parts of this web site.

Ordinary differential equations

Morris-Lecar equations	MorrisLecar.vf
Bratu equations	bratu.vf
A simple example with a Hopf bifurcation	hopftest.vf
Lorenz equations	lorenz.vf
Pendulum equations	pendulum.vf
Rossler equations	rossler.vf
van der Pol equations	vanderpol.vf
van der Pol equations, with an additional parameter	vanderpola.vf
Hindmarsh-Rose neuron model¹	hr.vf

¹ Contributed by Masoud ---
Delay differential equations

Mackey-Glass delay equation	MackeyGlass.vf
SIR delay equation	SIRdelay.vf
Shayer-Campbell delay equations, a model of coupled neurons	ShayerCampbell2000.vf
A nonautonomous delay equation	nonautdelay.vf
A state-dependent delay equation	sdd.vf
Another state-dependent delay equation	sddfn.vf
A trivial example of using the delay function	simpledelay.vf