|
The CARPET programming language
(doc version)
Introduction
CARPET is a programming
language for the definition of cellular automata-based models and
their transition functions, designed as an extension to ANSI C. A
CARPET program consists of the following sections: a global
declaration section, known as the
cadef
(CA DEFinition) section; a transition function; and an optional
steering function.
The general layout of a CARPET
program is as follows:
cadef
{
declarations
}
[transition function local
variable declarations and subroutine prototypes]
{
transition
function code
}
[transition function
subroutines]
[
steering
{
steering
function code
}
]
where items in […] brackets
are optional. Note that the steering function must be located after
the transition function and any subroutine functions called by the
transition function.
The extensions to C defined in
the CARPET language are described below.
The transition function (and
its subroutine functions, if any) may contain the following CARPET
statements, in addition to C code:
·
cell_substate
·
DimX, DimY, DimZ
·
GetX, GetY, GetZ
·
NFolds
·
NProcs
·
random()
·
randomise()
·
srandom()
·
step
·
update()
·
parameter references
Syntax
cadef
{
declaration;
declaration;
...
declaration;
}
Remarks
This is the
declaration section of the program; it must precede any statement
except for C pre-processor ones.
declaration
can be any of the following statements:
·
deterministic
·
dimension
·
neighbour
·
parameter
·
radius
·
region
·
state
·
threshold
Example
cadef
{
dimension 3;
radius 1;
region Inside
(start+1:end-2, :,:);
state (float val; int
val2);
neighbour N[6]
([-1,0,0]left,[1,0,0]right,
[0,-1,0]down, [0,1,0]up,
[0,0,-1]in, [0,0,1]out);
parameter (pi 3.14159);
deterministic;
threshold (cell_val ==
3);
}
Syntax
cell_<substate>
Remarks
A user may refer to a
specific substate of a cell by using the string “cell_”
followed by the name of the substate.
N.B.:
A user may modify the value of a substate using the
update
function (section 2.3.25).
Example
cadef
{
state (float
temp);
}
float val;
val = cell_val+3;
Syntax
cpt_abort()
Remarks
Calling this function
causes the program to stop. It is only available inside the
steering
block of the program.
Example
An example is
available in section 2.3.22.
Syntax
cpt_save (char *fname)
Remarks
This function saves all the CA Engine data to project and substate
files. It does not save the AVS/Express related files. It is only
available for steering. It uses the
fname
argument as a root for the generated files, as described in section
2.2.2.1.2 (omitting the AVS/Express related discussion).
Example
An example is
available in section 2.3.22.
Syntax
cpt_set_param (float
*par, float npar)
Remarks
This function alters
the value of the global parameter pointed by
par
to that of
npar. It is only available inside the
steering
statement. See section 2.3.14 for the definition of global parameters.
Example
An example is
available in section 2.3.22.
Syntax
deterministic;
Remarks
This statement signifies the commitment of the
programmer that the cell update function is deterministic [Telford et
al. 1998]. A deterministic program is one where the state of a cell
is guaranteeed to be unchanged if the state of its local neighbourhood
is unchanged. This is one of the necessary conditions for automatic
inactive region detection (the other being that the user has not set
active folds manually).
N.B.:
A program whose update rule depends on
step
or random functions is non-deterministic (except if this only happens
in step 0). Starting with release 1.2 of the software, detection of
the
deterministic keyword and the keyword
step
or any random function in a program is flagged by the parser as a
warning (non-fatal).
Example
The example below gives an example where the
incorrect use of
deterministic
leads to erroneous program execution.
cadef {
...
state (float val);
deterministic;
}
float newval;
{
if (0 == step)
{ // OK
newval =
GetX+GetY+GetZ;
} else if (step
< 20) { // not deterministic!
newval =
0.51*cell_val;
}
...
update(cell_val, newval);
}
Syntax
dimension <n>;
Remarks
Defines the number of
dimensions of the CA Engine. It ranges from 1-3.
Syntax
DimX, DimY, DimZ
Remarks
These values are the CA Engine dimension of the
x, y and z axis respectively. Note that for x,
which is split according to the number of processes, this is the size
of the whole model.
Example
cadef {
...
state (int st);
...
}
{
DimX = 5;
// This is illegal!
if (DimX == cell_st)
{
update(cell_st, DimY);
}
...
}
Syntax
GetX, GetY, GetZ
Remarks
These values are the global x, y and
z coordinates of the cell respectively.
Example
cadef
{
...
state (float
dist);
...
}
float val;
{
if (0 == step) {
val = GetX+GetY+GetZ-3;
update(cell_dist, val);
}
...
}
Syntax
neighbour <Nname>[<n>](<[x,y,z]
alias>, ...,
<[x,y,z] alias>);
Remarks
This statement
defines a logical neighbourhood. The
x,y,z
values must remain within the
[-radius, radius]
interval defined in the
cadef
statement. The alias for each neighbour is not compulsory; a cell can
refer to its neighbour using the
Nname[i]
notation.
Example
cadef {
dimension 2;
radius 1;
state (float
dist);
neighbour
Neumann[4]([0,-1] North, [0,1], [-1,0], [1,0]);
}
float v1, v2;
{
v1 = North_dist;
v2 = Neumann_dist[0];
// Should be the same!
...
}
Syntax
NFolds
Remarks
Returns the number of
folds.
Example
cadef
{
...
}
NFolds = 3; //
illegal!
if (1 == NFolds) {
...
Syntax
NProcs
Remarks
Returns the number of
processes to which the CA is split in the x axis.
Example
cadef
{
...
}
Nprocs = 2; //
illegal!
int strip_length;
strip_length = DimX/(NProcs
* NFolds);
...
Syntax
parameter (param_def_list)
where
param_def_list
is a comma-separated list of parameter definitions, where each
parameter definition has one of the following forms:
·
param_name
·
param_name
value
where value
is a float,
in any C float
syntax.
·
param_array[dim]
·
param_array[dim] {array_list}
where array_list
is a comma-separated list of
floats,
in any C float
syntax, and dim
is an integer
index greater than 1.
Remarks
Declares and defines
global CA parameters. Their values can only be changed during the run
from the GUI, or by means of the
cpt_set_param()
primitive (section 2.3.6), since they are global to all the cells. They are
of type
float. Parameters are accessed in a CARPET
program directly through their symbolic name. The maximum number of
parameters (counting each element of parameter arrays) is 500, as set
by the
MaxNumParam variable in the file
parser.h
of the parser. The same file contains the definition of the maximum
length of a parameter name (30 characters, including the array
indices)
MaxLenParam. The array list may have fewer
than dim
elements, in which case the additional values default to zero
(non-initialised parameters default to 0 in any case).
Example
cadef {
...
parameter (mypar
2.0, par_array[3] {1.0, 4.0});
...
}
Syntax
radius n;
Remarks
Defines the radius of
the neighbourhood of the cells.
N.B.:
radius
is limited to
·
60, if
dimension
is 1;
·
2, if
dimension
is 2;
·
1, if
dimension
is 3.
Syntax
random (n);
Remarks
Returns a pseudo
random integer between 0 and
n,
n
being a positive integer.
N.B.:
random()
returns the same sequence of numbers every time it is called. To avoid
this, the user may use the
randomise()
function. The use of this function could make a program
non-deterministic (see section 2.3.7).
Syntax
randomise();
Remarks
Creates a new seed
for the random number generator.
Syntax
region <region-name> (<min_x>:<max_x>,<min_y>:<max_y>,
<min_z>:<max_z>);
Remarks
The user specifies a
region as part of the
cadef
block of the program, using a declaration of the above form. This is
used to allow global reduction operations within the steering block of
the CARPET program. There is no limit to the number of regions that
can be specified by the user. If the lower or upper bound of a
co-efficient of the region is not defined, the specification defaults
to the corresponding minimum or maximum for the respective dimension.
The bounds of the region range from 1 to the size of the corresponding
dimension. The keywords
start
and end
are defined to be the minimum and maximum of the dimension in which
they are found, thus allowing flexible region specification.
Because the
dimensions of the model are specified at build time while the regions
are declared at compile time, full error checking is not possible.
Nonetheless, the following conditions are flagged as errors:
·
Specifying minimum and maximum values
for dimensions not used by the model;
·
Specifying a negative integer as a
range boundary;
·
Specifying a maximum value less than
a minimum value (this check is possible if the region boundaries are
explicitly defined).
Example
cadef {
dimension 3;
region myregion
(start+2:end-2,:,3:);
...
}
Syntax
region_<op>
(<region-name>, <state>);
Remarks
The
region_<op>()
function is available inside the steering function. It returns a value
of the same type as its
state
argument. It applies the reduction operation
op
to state
state all the cells in region
region-name.
The supported operations are as follows:
·
max
·
min
·
sum
·
prod
·
land
(logical and)
·
band
(binary and)
·
lor
(logical or)
·
bor
(binary or)
·
lxor
(logical exclusive or)
·
bxor
(binary exclusive or)
The user can supply a
global reduction operation inside their CARPET program to cater for
operations other than the ones above. The prototype of a global
reduction function corresponding to the
region_<op>()
function must comply with the following:
<datatype> cpt_<datatype>_<op>
(int min_x, int max_x, int min_y, int max_y, int min_z, int max_z, int
stateid, CptCell *cp)
N.B.:
The automatically generated functions assume that the co-efficients of
the model are in the
[0,DIMw-1]
range, w
Î{X,Y,Z},
in other words, they range from
0
to the maximum dimension of the model minus 1.
Note: the importance of the neutral element
When developing a
global reduction function the user should take into account that a
region can be defined so that the data in it are outside the domain of
one or more processes. The functions automatically generated provide
an algorithm which prevents erroneous calculation. However, because
the operations are global, all the processes contribute to the global
reduction of the result. In order to avoid incorrect global reduction
of the data, the user can set the initial value of the variable
containing the per-process result of the function to be equal to the
neutral element for the corresponding operation.
Example
Examples of such
functions are the ones automatically generated by the parser.
Syntax
srandom (n);
Remarks
Same as
randomise(),
only that the programmer may choose the seed argument through
n.
Syntax
state(type substateA1,
substateA2, …, substateAn,
type substateB1,
substateB2, …, substateBn, …);
Remarks
The state of a cell
consists of various typed substates. The allowed types are:
·
(unsigned) char;
·
(unsigned) short;
·
(unsigned) int;
·
float;
·
double;
·
arrays of the above.
Syntax
steering {
statement;
...
statement;
}
Remarks
The steering function
is an optional feature of a CARPET program by which the user can
affect the flow of the program as a result of global reductions on
regions of the model (see section 2.3.18 for the definition of regions in a CARPET program).
The steering function
is defined in a separate section of the CARPET program, similarly to
the update function. The main difference is that the update
function is applied separately in each cell, whereas the steering
function is global for the model. Any code inside the
steering
statement is copied verbatim to the generated file, with the exception
of the
region_<op>() statements which are
translated to a global reduction function, as shown in section 2.3.19. The user can modify the flow of the program inside
the steering section in either of the following two ways:
·
call the function
cpt_set_param
(float *old_p, float new_p), which sets the
global parameter pointed by
old_p
to the value of
new_p;
·
call the function
cpt_abort(),
which terminates the execution of the program without exiting the CA
Engine.
Inside the steering
code, the user has access only to the following CARPET defined
variables:
·
DimX,
DimY,
DimZ;
·
step;
·
global parameter values.
Example
cadef {
dimension 3;
region Inside
(start+2:end-2,:,:);
...
state (float val);
parameter (pi
3.141);
}
...
steering {
float min =
region_min (Inside, val);
if (min < 4.0) {
cpt_set_param
(&pi, 3.14159);
} else if (min >
100.0) {
cpt_save
(“aborted”);
cpt_abort ();
}
}
Syntax
step
Remarks
This denotes the
current CA Engine iteration. The initial value is 0. Allows
time-dependent update function development.
Syntax
threshold (expression);
Remarks
Defines a C expression, which, if satisfied, is
equivalent to the cell being idle for the past CA Engine evolution. It
is used in conjunction with
deterministic
for the inactive region detection.
Example
cadef
{
...
state ( float val; int
val2; );
threshold (cell_val ==
3);
...
}
Syntax
update (cell_substate,
value);
Remarks
This is the only way to set the value of a cell
substate by means of the program. This is done in order to ensure that
the state of all cells is set in lock step in the next generation
after the update has been issued, thus preventing race conditions.
|