> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangrovesystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Operators

> Write mathematical and logical operators in Mangrove's models.

## Standard Mangrove operators

### `map`

Use `map` as a lookup node in nexus\_nodes\_attributes: the child gives the lookup key, and the map node resolves that key through a resource parameter table.

<CodeGroup>
  ```yaml Syntax theme={null}
  - name: Some mapped value
    operator: map
    nexus_resources_library: My Library
    nexus_resources_parameter: My Parameter
    nexus_nodes_attributes:
      - name: Lookup key input
        data_point_type: some-key-slug
  ```

  ```yaml Biochar example theme={null}
  - name: c_hc regression coefficient
    operator: map
    nexus_resources_library: Biochar permanence regression coefficients
    nexus_resources_parameter: c
    nexus_nodes_attributes:
      - name: Biochar end use soil temperature
        data_point_type: soil-temperature
  ```
</CodeGroup>

## Complex expressions

Mangrove uses the [Keisan](https://github.com/project-eutopia/keisan) expression language to evaluate mathematical and logical expressions within model nodes. This allows you to write complex formulas directly in the `operator` field of a node.

### Basic Syntax

Expressions are written as strings in the `operator` field of a calculated node. Child node values are referenced by their slugified names (lowercase, underscores instead of spaces).

```yaml theme={null}
- name: Calculated Value
  operator: "child_a * child_b + 100"
  nexus_nodes_attributes:
  - name: Child A
    data_point_type: input-a-slug
  - name: Child B
    data_point_type: input-b-slug
```

### Notable Operators

Standard operators supported in the equations are [listed here](https://app.gomangrove.com/nexus/952/system/6181). These include:

* Arithmetic operators
* Comparison operators
* Logical operators (e.g. `&&`)
* Built-in mathematical functions (e.g. the below list)
  * **`abs(x)`**: Absolute value\
    Example: `abs(-5)` → `5`
  * **`sqrt(x)`**: Square root\
    Example: `sqrt(16)` → `4`
  * **`exp(x)`**: Exponential (e^x)\
    Example: `exp(1)` → `2.718...`
  * **`log(x)`**: Natural logarithm\
    Example: `log(10)` → `2.302...`
  * **`sin(x)`, `cos(x)`, `tan(x)`**: Trigonometric functions\
    Example: `sin(0)` → `0`
  * **`round(x)`**: Rounds a value. Use `round(x)` for nearest integer or `round(x, n)` for n decimal places.\
    Example: `round(10/2, 2)` → `5.00`
* Conditional logic
  Example: `if(condition, value_if_true, value_if_false)`
* List functions that work with arrays of values
  * **`max(list)`** — Maximum value in a list
  * **`min(list)`** — Minimum value in a list
  * **`range(n)`** — Generate list `[0, 1, ..., n-1]`
  * **`range(start, end)`** — Generate list from start to end-1
  * **`round`** — Rounds a value. Use `round(x)` for nearest integer or `round(x, n)` for n decimal places.
  * **`map`** — Maps a value from a linked library
  * **`duration`** — Converts the time range of the incoming datapoint into a duration
  * **`data_point_proportion`** — Extracts the allocation proportion from an allocated node

### When to Use Mangrove Operators vs Keisan Expressions

| Use Mangrove operators when...        | Use Keisan expressions when...     |
| :------------------------------------ | :--------------------------------- |
| Simple arithmetic on all children     | Complex multi-step formulas        |
| Standard aggregations (sum, avg, max) | Conditional logic (if/else)        |
| Clearer, more readable models         | Custom rounding or transformations |

## Best Practices

1. **Keep expressions simple** — Break complex calculations into multiple nodes rather than one long expression. This improves readability and makes debugging easier.
2. **Use explicit unit conversions** — Create separate nodes for unit conversions rather than embedding them in expressions.
3. **Name child nodes clearly** — Since expressions reference child nodes by slugified name, use descriptive names that make the expression readable.
4. **Test your expressions** — Use the Model Editor's test functionality to verify calculations with sample inputs before saving.

## Further Reading

* [Keisan Documentation](https://github.com/project-eutopia/keisan) — Complete reference for the Keisan expression language