Ganymed 1.0 User's Guide: Difference between revisions

Line 257:

===Outputting Derived Fields===

In addition to writing exports fields created by model components the user may specify new fields that will be evaluated using the MAPL parser. These will be referred to as derived fields in the following discussion. The derived fields are evaluated using an expression that involves other fields in the collection as variables. The expression is evaluated element by element to create a new field. Derived fields are specified like a regular field from a gridded component in a history collection with 3 comma separated strings. The difference is now that in place of a variable name string, an expression string that will be evaluated is entered. Following this comes the string specifying the gridded component~~. For derived fields this is just a placeholder~~. You MUST put a string here ~~but it will~~ be ~~ignored~~. Finally a string MUST be entered which is the name of the new variable. This will be the name of the variable in the ~~resultant~~ file. In general the expression entered will involve variables, functions, and real numbers. To learn what legal expressions are see the documentation for the MAPL parser component. A few general notes about using the parser. Expression entered can use any field requested for output in the collection as a variable in the expression so long as it is an actual export field of a gridded component. In others words, you can not use a derived ~~field as a variable in an expression. Secondly the~~ fields ~~must be conformal. For example, an expression involving fields with different~~ vertical ~~levels (a center~~ and ~~an edge level~~) ~~is illegal regardless of whether you are requesting that the variables be vertically interpolated for output~~.

In addition to writing exports fields created by model components (we will refer to these as model fields), the user may specify new fields that will be evaluated using the MAPL parser. These will be referred to as derived fields in the following discussion. The derived fields are evaluated using an expression that involves other fields in the collection as variables. The expression is evaluated element by element to create a new field. Derived fields are specified like a regular field from a gridded component in a history collection with 3 comma separated strings. The difference is now that in place of a variable name string, an expression string that will be evaluated is entered. Following this comes the string specifying the gridded component. You MUST put a string here, which should be the name of a gridded component. Finally a string MUST be entered which is the name of the new variable. This will be the name of the variable in the output file. In general the expression entered will involve variables, functions, and real numbers. The derived fields are evaluated before time and spatial (vertical and horizontal) averaging.

In the following example we create a collection that has ~~two~~ derived fields, the magnitude of the wind ~~and~~ the temperature in farenheit:

Here are some rules about expressions

#Fields in expression can only be model fields.

#If the model field has an alias you must use the alias in the expression.

#You can not mix center and edge fields in an expression. You can mix 2D and 3D fields if the 3D fields are all center or edge. In this case each level of the 3D field operated with the 2D field. Another way to think of this is that in an expression involving a 2D and 3D field the 2D field gets promoted to a 3D field with the same data in each level.

#When parsing an expression the parser first checks if the fields in an expression are part of the collection. Any model field in a collection can be used in an expression in the same collection. However, there might be cases where you wish to output an expression but not the model fields used in the expression. In this case if the parser does not find the field in the collection it checks the gridded component name after the expression for the model field. If the field is found in the gridded component it can use it in the expression. Note that if you have an expression with two model fields from different gridded components you can not use this mechanism to output the expression without outputting either field. One of them must be in the collection.

#The alias of an expression can not be used in a subsequent expression.

Here are the rules for the expressions themselves

The following can appear in the expression string

#The function string can contain the following mathematical operators +, -, *, /, ^ and ()

#Variable names - Parsing of variable names is case sensitive.

#The following single argument fortran intrinsic functions and user defined functions are implmented: exp, log10, log, sqrt, sinh, cosh, tanh, sin, cos, tan, asin, acos, atan, heav (the Heaviside step function). Parsing of functions is case insensitive.

#Integers or real constants. To be recognized as explicit constants these must conform to the format [+|-][nnn][.nnn][e|E|d|D[+|-][nnn] where nnn means any number of digits. The mantissa must contain at least one digit before or following an optional decimal point. Valid exponent identifiers are 'e', 'E', 'd' or 'D'. If they appear they must be followed by a valid exponent!

#Operations are evaluated in the order

##expressions in brackets

##-X unary minux

##X^Y exponentiation

##X*Y X/Y multiplicaiton and division

##A+B X-Y addition and subtraction

In the following example we create a collection that has three derived fields, the magnitude of the wind, the temperature in farenheit, and temperature cubed:

<pre>

Line 272:

Line 294:

'sqrt(U*U+V*V)' , 'DYN' , 'Wind_Magnitude' ,

'(T-273.15)*1.8+32.0' , 'DYN' , 'TF' ,

'T^3' , 'DYN', 'T3' ,

::

</pre>

@@ Line 257: / Line 257: @@
 ===Outputting Derived Fields===
-In addition to writing exports fields created by model components the user may specify new fields that will be evaluated using the MAPL parser. These will be referred to as derived fields in the following discussion. The derived fields are evaluated using an expression that involves other fields in the collection as variables. The expression is evaluated element by element to create a new field. Derived fields are specified like a regular field from a gridded component in a history collection with 3 comma separated strings. The difference is now that in place of a variable name string, an expression string that will be evaluated is entered. Following this comes the string specifying the gridded component. For derived fields this is just a placeholder. You MUST put a string here but it will be ignored. Finally a string MUST be entered which is the name of the new variable. This will be the name of the variable in the resultant file. In general the expression entered will involve variables, functions, and real numbers. To learn what legal expressions are see the documentation for the MAPL parser component. A few general notes about using the parser. Expression entered can use any field requested for output in the collection as a variable in the expression so long as it is an actual export field of a gridded component. In others words, you can not use a derived field as a variable in an expression. Secondly the fields must be conformal. For example, an expression involving fields with different vertical levels (a center and an edge level) is illegal regardless of whether you are requesting that the variables be vertically interpolated for output.
+In addition to writing exports fields created by model components (we will refer to these as model fields), the user may specify new fields that will be evaluated using the MAPL parser. These will be referred to as derived fields in the following discussion. The derived fields are evaluated using an expression that involves other fields in the collection as variables. The expression is evaluated element by element to create a new field. Derived fields are specified like a regular field from a gridded component in a history collection with 3 comma separated strings. The difference is now that in place of a variable name string, an expression string that will be evaluated is entered. Following this comes the string specifying the gridded component. You MUST put a string here, which should be the name of a gridded component. Finally a string MUST be entered which is the name of the new variable. This will be the name of the variable in the output file. In general the expression entered will involve variables, functions, and real numbers. The derived fields are evaluated before time and spatial (vertical and horizontal) averaging.
-In the following example we create a collection that has two derived fields, the magnitude of the wind and the temperature in farenheit:
+Here are some rules about expressions
+#Fields in expression can only be model fields.
+#If the model field has an alias you must use the alias in the expression.
+#You can not mix center and edge fields in an expression. You can mix 2D and 3D fields if the 3D fields are all center or edge. In this case each level of the 3D field operated with the 2D field. Another way to think of this is that in an expression involving a 2D and 3D field the 2D field gets promoted to a 3D field with the same data in each level.
+#When parsing an expression the parser first checks if the fields in an expression are part of the collection. Any model field in a collection can be used in an expression in the same collection. However, there might be cases where you wish to output an expression but not the model fields used in the expression. In this case if the parser does not find the field in the collection it checks the gridded component name after the expression for the model field. If the field is found in the gridded component it can use it in the expression. Note that if you have an expression with two model fields from different gridded components you can not use this mechanism to output the expression without outputting either field. One of them must be in the collection.
+#The alias of an expression can not be used in a subsequent expression.
+Here are the rules for the expressions themselves
+The following can appear in the expression string
+#The function string can contain the following mathematical operators +, -, *, /, ^ and ()
+#Variable names - Parsing of variable names is case sensitive.
+#The following single argument fortran intrinsic functions and user defined functions are implmented: exp, log10, log, sqrt, sinh, cosh, tanh, sin, cos, tan, asin, acos, atan, heav (the Heaviside step function). Parsing of functions is case insensitive.
+#Integers or real constants. To be recognized as explicit constants these must conform to the format [+|-][nnn][.nnn][e|E|d|D[+|-][nnn] where nnn means any number of digits. The mantissa must contain at least one digit before or following an optional decimal point. Valid exponent identifiers are 'e', 'E', 'd' or 'D'. If they appear they must be followed by a valid exponent!
+#Operations are evaluated in the order
+##expressions in brackets
+##-X      unary minux
+##X^Y  exponentiation
+##X*Y X/Y multiplicaiton and division
+##A+B X-Y addition and subtraction
+In the following example we create a collection that has three derived fields, the magnitude of the wind, the temperature in farenheit, and temperature cubed:
 <pre>
@@ Line 272: / Line 294: @@
                            'sqrt(U*U+V*V)' , 'DYN'          , 'Wind_Magnitude'   ,
                            '(T-273.15)*1.8+32.0' , 'DYN'    , 'TF' ,
+                          'T^3'           , 'DYN',         'T3' ,
                            ::
 </pre>