Descriptions
Each attribute and constraint object has a defined value. For attributes, this includes the unit, the type of value, and any associated equations. For constraints, the value is simply a boolean statement. These values can either be simple scalar values, supported arrays, or complex mathematical relations involving values from other objects.
Special handling is applied when resolving values containing strings of TBD (To Be Determined). This can be useful during the early stages of model formation to not resolve errors when the value is still being defined.
Math Syntax
Equations are powered by Math.js, providing a comprehensive set of mathematical operations and functions. The syntax follows standard mathematical conventions:
Basic Operations
| Operation | Syntax |
|---|
| Addition | A + B |
| Subtraction | A - B |
| Multiplication | A * B |
| Division | A / B |
| Modulus | A % B |
| Exponentiation | A ^ B |
Comparison Operators
| Operator | Syntax |
|---|
| Equal | == |
| Not Equal | != |
| Less Than | < |
| Greater Than | > |
| Less or Equal | <= |
| Greater or Equal | >= |
Mathematical Functions
| Function | Syntax | Description |
|---|
| Absolute Value | abs(x) | Returns the absolute value |
| Square Root | sqrt(x) | Returns the square root |
| Cube Root | cbrt(x) | Returns the cube root |
| Power | pow(x, y) | Returns x raised to power y |
| Exponential | exp(x) | Returns e raised to power x |
| Natural Log | log(x) | Returns the natural logarithm |
| Base-10 Log | log10(x) | Returns the base-10 logarithm |
| Minimum | min(a, b, ...) | Returns the minimum value |
| Maximum | max(a, b, ...) | Returns the maximum value |
| Round | round(x) | Rounds to nearest integer |
| Floor | floor(x) | Rounds down to integer |
| Ceil | ceil(x) | Rounds up to integer |
| Sign | sign(x) | Returns -1, 0, or 1 |
Trigonometric Functions
| Function | Syntax | Description |
|---|
| Sine | sin(x) | Sine of x (in radians) |
| Cosine | cos(x) | Cosine of x (in radians) |
| Tangent | tan(x) | Tangent of x (in radians) |
| Arcsine | asin(x) | Inverse sine |
| Arccosine | acos(x) | Inverse cosine |
| Arctangent | atan(x) | Inverse tangent |
| Arctangent2 | atan2(y, x) | Angle from x-axis to point |
| Hyperbolic Sine | sinh(x) | Hyperbolic sine |
| Hyperbolic Cosine | cosh(x) | Hyperbolic cosine |
| Hyperbolic Tangent | tanh(x) | Hyperbolic tangent |
Statistical Functions
| Function | Syntax | Description |
|---|
| Mean | mean(a, b, ...) | Returns the average value |
| Median | median(a, b, ...) | Returns the median value |
| Mode | mode(a, b, ...) | Returns the most frequent value |
| Standard Deviation | std(a, b, ...) | Returns standard deviation |
| Variance | variance(a, b, ...) | Returns variance |
| Sum | sum(a, b, ...) | Returns the sum of all values |
| Product | prod(a, b, ...) | Returns the product of all values |
Logical Functions
| Function | Syntax | Description |
|---|
| AND | and(a, b) | Logical AND |
| OR | or(a, b) | Logical OR |
| NOT | not(x) | Logical NOT |
| XOR | xor(a, b) | Logical XOR |
Constants
| Constant | Syntax | Value |
|---|
| Pi | pi | 3.14159… |
| Euler’s Number | e | 2.71828… |
| Golden Ratio | phi | 1.61803… |
Value Types
Attributes can have the following kind associated to a value, which handles how it is displayed or computed:
| Value Type | Scalar | 1D array | 2D array | 3D array | Description |
|---|
Boolean | ✅ | ✅ | ✅ | ✅ | Represents true or false values. Does not use a unit and clears any existing unit. |
Date | ✅ | ❌ | ❌ | ❌ | Used for date values. Does not use a unit and clears any existing unit. |
Number | ✅ | ✅ | ✅ | ✅ | Represents standard numeric values. Optionally includes a unit. |
String | ✅ | ❌ | ❌ | ❌ | Represents string values. Does not use a unit and clears any existing unit. |
Array Values
Equations can produce scalar values or supported array values. Arrays use bracket syntax:
[1, 2, 3]
[[1, 2], [3, 4]]
[[[1], [2]], [[3], [4]]]
- 1D arrays, such as vectors.
- 2D arrays, such as matrices.
- 3D arrays, such as grouped matrices or tensor-like values.
Array values are supported for numbers and booleans. Strings and dates are scalar-only, so arrays of strings and arrays of dates are not supported.
Numeric arrays use one shared unit for the entire array value. Individual elements do not have separate units.
Callable Code Functions
Attribute equations can call functions defined in Code objects. This lets an equation delegate calculation logic to Python or JavaScript while still using model attributes as inputs.
Use the direct call syntax:
[@CodeObject].functionName(@InputA, @InputB)
- Number
- Boolean
- String
- Date
- Numeric array
- Boolean array
For numeric results with units, return an object with value and unit:
def calculate_mass(volume, density):
return { "value": volume * density, "unit": "kg" }
Unit Referencing
Values can reference units inline, such as 10 kg, where the number is associated with the unit.
Object Referencing
To reference other objects within an equation, use the @ symbol followed by the object’s name. This will automatically resolve the object’s value and unit.
