compute is not available when accessing MARS via the Web API.

Mathematical computations can be done on retrieved GRIB fields using the compute verb. It uses keyword fieldset to store the result of the computation and formula which specifies the actual computation. The following conventions are used in this documentation:

X	upper case characters denote fieldsets
X^k	is the k-th field of fieldset X
X_ij^k	is the point (column i, line j) of field X^k
a	lower case characters denote real scalars
'...'	is a character string
f(...)	is a function call
formula = "..."	is the MARS formula, what is actually computed

See also the fieldset syntax on how to access a subset of a fieldset.

Here is an example, where X and Y are the two input fieldsets and Z is the output fieldset:

compute,
   fieldset = Z,
   formula  = "X/2+log(Y)*X"

Any mathematical formula can be reduced to a series of elementary computations involving only one or two values. So the formula in the example can be reduced to:

[1] compute X/2	[2] compute log(Y)
[3] compute [2]*X	[4] compute [1]+[3]

For each of the fields X^k and Y^k of X and Y, a field Z^k is computed using the formula and added to the fieldset Z.

Any operation involving a missing value will results in a missing value.

All compute operators available with the MARS compute verb are listed in the table below. The sign '-' can also be used to denote negation, in which case it is actually a function, not an operator. All the boolean operators return 1 if the test is true, 0 otherwise. MARS follows the mathematical order of precedence: 1. function calls, 2. power, 3. * and /, 4. + and -, 5. boolean operators. By using brackets, the order of computation can be changed.

MARS compute operators
Arithmetic operators		Boolean operators
+	addition	=	equal to
-	subtraction	>	greater than
*	multiplication	<	less than
/	division	>=	greater or equal to
^	power	<=	less than or equal to
		<>	not equal to

Note: No check is done on the type of data combined in the formulae. It is the user's responsibility to make sure the computations have a physical meaning.

The GRIB header of the resulting fields is copied from the first field encountered. The resulting fields' GRIB headers are marked as being created with the compute facility by setting the model identification number to 255. Users can preserve the model identification number by setting the environment variable MARS_COMPUTE_FLAG to 0 before calling the mars command (see table 3).

The GRIB headers of resulting fields can be further modified using the GRIB tools, e.g. grib_set to read all fields from input file "speed" and write them as parameter "wind speed" to file out.grib:

grib_set -s paramId=10 speed out.grib

or

grib_set -s shortName=ws speed out.grib

Mixing fields and scalars

If the two operands are two fields, the operation is carried out between each pair of corresponding grid points in the two fields. The result is a field.
If one operand is a scalar and the other a field, the operation is carried out by applying the scalar to each grid point. The result is a field.
If both operands are scalars, the result is a scalar.

Calling functions

The same logic applies to mathematical functions, which are listed in the table below. If the argument of a function is a field, the result is a field where each grid point is the result of the function at the corresponding grid point in the input field. If the argument is a scalar the output is also a scalar. Examples:

compute,
   fieldset = X,
   formula  = "A * B"

creates a fieldset X where X_ij^k = A_ij^k * B_ij^k. Note that * is scalar multiplication and not matrix multiplication.

compute,
   fieldset = X,
   formula  = "A * 2"

creates a fieldset X where X_ij^k = A_ij^k * 2.

compute,
   fieldset = X,
   formula  = "(A>10) * B + (A<=10)*C"

Creates a fieldset X, where

X_ij^k = B_ij^k	if	A_ij^k > 10
X_ij^k = C_ij^k	if	A_ij^k < = 10

MARS mathematical functions
Name	No. of param.	Param. type	Result type	Description

max	any	any	fieldset if one of the parameters is a fieldset, scalar otherwise	Maximum
min	any	any	fieldset if one of the parameters is a fieldset, scalar otherwise	Minimum
merge	any	fieldset	fieldset	Merges several fieldsets into a unique fieldset
maxvalue	1	fieldset	scalar	Maximum grid point value of all fields
minvalue	1	fieldset	scalar	Minimum grid point value of all fields
sgn	1	any	same as parameter	0 if the value is 0, +1 if the value is positive, -1 if the value is negative.
int	1	any	same as parameter	Integer part
exp	1	any	same as parameter	Exponential
log	1	any	same as parameter	Natural logarithm
log10	1	any	same as parameter	Base 10 logarithm
sin	1	any	same as parameter	Sine, input in radians
cos	1	any	same as parameter	Cosine, input in radians
tan	1	any	same as parameter	Tangent, input in radians
asin	1	any	same as parameter	Arc-sine, return value(s) in radians
acos	1	any	same as parameter	Arc-cosine, return value(s) in radians
atan	1	any	same as parameter	Arc-tangent, return value(s) in radians
atan2	2	any	fieldset if one of the parameters is a fieldset, scalar otherwise	Arc-tangent of y/x, using the signs of both parameters to determine the quadrant of the result (in radians)
abs	1	any	same as parameter	Absolute value
sqrt	1	any	same as parameter	Square root
count	1	fieldset	scalar	Number of fields in the fieldset
sum	1	fieldset	1 field	Sum of all the fields in the fieldset.
mean	1	fieldset	1 field	Mean of all the fields in the fieldset.
rms	1	fieldset	1 field	Root mean square of all the fields in the fieldset.
stdev	1	fieldset	1 field	Standard deviation of all the fields in the fieldset.
var	1	fieldset	1 field	Variance of all the fields in the fieldset.
covar	2	fieldset, fieldset	1 field	Covariance between the 2 fieldsets.
distribution	2	fieldset, scalar	fieldset	Sorts a set of n (indicated by scalar) fields according to the parameter values, e.g. field 1 will have the lowest values, field 2 will have the second lowest values ..., field n, which will have the largest values
bitmap	2	fieldset, scalar	fieldset	Creates missing values for those grid points equal to scalar
bitmap	2	fieldset, field	fieldset	Creates missing values for those missing values of the second field
bitmap	2	fieldset, fieldset	fieldset	Creates missing values on the first parameter for those grid points with missing values of the second fieldset
nobitmap	2	fieldset, scalar	fieldset	Removes bitmap on the fieldset by changing missing values by the scalar provided
repeat	2	field, scalar	fieldset	Repeats field as many times as indicated by scalar

Bitmaps (Missing values)

Some fields may contain a bitmap, i.e., there is no data (missing values) for certain grid points. Those missing values are not considered in any computation, but copied to the resulting field. Only valid data values are computed. Functions bitmap and nobitmap enable users to handle bitmaps on fieldsets.

Examples:

compute,
   fieldset = X,
   formula  = "bitmap(A,0)"

creates a fieldset X, where

X_ij^k = A_ij^k	if	A_ij^k ≠ 0
X_ij^k = missing value	if	A_ij^k = 0

compute,
   fieldset = X,
   formula  = "bitmap(A,B)"

If B is a field with a bitmap, this request creates a fieldset X, where X^k is a copy of A^k with the bitmap of B.

compute,
   fieldset = X,
   formula  = "nobitmap(A,1)"

creates a fieldset X, where

X_ij^k = A_ij^k	if	A_ij^k ≠ missing value
X_ij^k = 1	if	A_ij^k = missing value

Compute example

MARS request to retrieve the u and v velocity into fieldsets, compute the wind speed and write the result into the target file speed

retrieve, 
   type	    = analysis, 
   time	    = 12, 
   date	    = -1, 
   grid	    = 2.5/2.5, 
   param    = u, 
   fieldset = u 
retrieve, 
   param    = v, 
   fieldset = v 
compute, 
   formula  = "sqrt(u*u + v*v)", 
   target   = "speed"

The GRIB headers of the resulting fields can be further modified by using e.g. grib_set, see above.

Space shortcuts

Page tree

Mixing fields and scalars

Calling functions

Bitmaps (Missing values)

Compute example

4 Comments

Renate Wilcke

Dominique Lucas

Renate Wilcke

Dominique Lucas