Python variable data

Python variable data sources allow you to define certain data items in terms of bespoke mathematical formulae. Each of these data items is labelled by a particular mathematical symbol (e.g. R_c for cover type resistance scale) and you must specify an equation for this quantity in terms of a particular set of input symbols (e.g. H for cover height and D for line diameter). The available input symbols are contingent upon the particular data item being set. For example, one valid formula for R_c is:

where gammaPrime and f are constants. Generically, if the inputs are labelled as $x_1, x_2, \ldots$, the constants as $c_1, c_2, \ldots$, and the outputs as $y_1, y_2, \ldots$, then Python variable data sources allow equations to be specified in the form $y_1 = f_1(x_1, x_2, \ldots; c_1, c_2, \ldots), y_2 = f_2(x_1, x_2, \ldots; c_1, c_2, \ldots), \ldots$, where $f_1, f_2, \ldots$ are user-specified functions.

There are two main advantages of Python variable data sources over tabular ones. Firstly, tabular variable data sources can only have one independent variable, whereas Python variable data can have multiple independent variables. Secondly, entering an exact formula obviates the need for interpolation and may therefore be more accurate. Python variable data sources require less overhead than an external function and (if using SymPy) can automatically compute any derivatives that OrcaFlex might require.

Equation type

This determines whether the output variables defined in the equation script should be interpreted as SymPy expressions or as ordinary Python. The SymPy approach is usually faster and can be automatically differentiated by OrcaFlex if needed (e.g. for computing any Jacobians needed to optimise convergence); the Python approach is faster and more intuitive when there is conditional branching within the equation script (i.e. when different formulae are used in different circumstances).

Equation script

This is where you define your bespoke formulae. You must provide an expression for each of the required output symbols as a function of the allowable input symbols, plus any constants that you have defined. The expected output and allowable input symbols can be found by reading the documentation for the data items associated with the variable data in question. The output symbols can also be seen in the default equation script, which generally sets all the outputs to zero; the input symbols can be seen in the default test input script. It may be that some of the outputs are optional and can be omitted. If this is the case, then it will be made clear in the specific documentation for the feature being modelled.

Here's another example, in which we define cover height, H, to be a Gaussian function of arc length, s:

where H_0, sPeak and wPeak are constants.

Test input/output

This functionality allows you to test that your equation script is working by performing a test evaluation. You achieve this by setting the input symbols to specific values within the test input script. For example, the script to test evaluate the expression for R_c given above might be:

The results of the test evaluation will appear in the test output box when you press the Test button. This box also display any error messages in the event that your equation script could not be evaluated. If your equation script contains any context-sensitive constants (whose value depends on the identity of the model object which is using this variable data source), then you can specify the context to be used for the test evaluation by setting a special context variable. For example:

would use the constants associated with 'Sandy cover type'. You can also use the test input script to plot graphs of your equation script, by setting a testCurve parameter with the following syntax:

This will plot a graph of R_c versus H for D = 1. The H-axis will have data points at H = 0, 0.1, 0.2, ..., 3.8, 3.9, 4. If any of the inputs or outputs are vector quantities, then you can specify which component indices will be plotted by adding the entries inputComp and outputComp to the testCurve dictionary (inputComp and outputComp are 0-based indices). For instance, if your equation script were:

and your test input were:

Then this would plot the first component of $\vec{y} = |\vec{x}| \vec{x}$ versus the second component of $\vec{x}$, varying over the values $1, 1.2, 1.4, 1.6, 1.8, 2$, and with the first and third components of $\vec{x}$ fixed at $1$ and $3$, respectively.

Constants

Some equation scripts may contain constants representing the physical properties of the system being modelled. For instance, a model of soil resistance may include a constant to represent the density of the soil. Every soil type will use the same equation for the soil resistance but each will have a different value for the soil density. You can define a list of constants for your Python variable data source, accessed by pressing the edit constants button (universal, non-dimensional constants could just as well be defined inline within the equation script). There are two main advantages to separating the constants from the equation script itself: firstly, the dimensions of the of the constant can be specified, which means that the units can be adjusted automatically if the units system of the model is altered; secondly, constants can be given different values, depending on which model object is using the variable data. This means that the underlying equations can be shared between model objects with different properties, without having to specify separate equations for each. Each constant is associated with the following data:

Name

The symbolic name of constant. This is the name by which the constant will be referenced in the equation script.

Context

The model object for which this constant applies. All means that the same value applies to all the objects that use this Python variable data source. For example, the gravitational acceleration, $g \approx 9.80665$ m s^-2, can effectively be considered a universal constant, being the same (for all intents and purposes) for every object in a model, whereas the shear strength, $s$, of soil may take a different value for each cover type in the model.

Value

The value of the constant.

Dimensions

A string which defines the dimensions of the constant. The string is made up of zero or more fundamental components, separated by "." or "/". The fundamental components are of the form "<base_dimension>^N", where <base_dimension> denotes the physical quantity, e.g. length, mass, etc., and N is the exponent. If the exponent is omitted, then its value is taken to be 1.

The possible values for the base dimension are:

• "LL": length
• "MM": mass
• "TT": time
• "FF": force
• "$S": stress or pressure
• "$E": energy
• "$P": power

The following examples demonstrate how to specify some commonly used dimensions:

• "LL^2": area
• "FF.LL": moment
• "LL.TT^-1": velocity
• "MM/LL^3": density
• "FF/LL^2": stress or pressure, equivalent to "$S"

Units

This is a read-only data item that tells you the units of the constant, given the units system of the model and the constant's user-specified dimensions. For example, a constant whose dimensions are "LL.TT^-1" would have units of m s^-1 when working in the SI units system.