Build accounting models

Building models

Models can be edited by Admin users in the Model Editor using a YAML-based scripting language.

Open the Model Editor by clicking on Edit/Test besides the model name

The YAML script constructs carbon accounting models using a tree of interconnected nodes, where each node performs a calculation or holds a value. These nodes are organized in a hierarchical structure.

Example Model

nexus_nodes_attributes:
- name: Output Node
  operator: summation
  data_point_type: output-slug
  nexus_nodes_attributes:
  - name: Intermediate Calc A
    operator: summation
    nexus_nodes_attributes:
    - name: Data Input 1
      data_point_type: data-point-slug
    - name: Constant
      constant: 100
  - name: Intermediate Calc B
    operator: difference
    nexus_nodes_attributes:
    - name: Static Input
      order: 0
      data_point_type: static-input-slug
    - name: Data Input 2
      order: 1
      data_point_type: data-point-2-slug

This is the equivalent of writing the following equation:

(Datapoint1 + 100) + (\alpha - Datapoint2) = Output

As a best practice, Validate the model you have built, and check the results in the Console before saving the model.

Editing models

Saving the model creates a new version. See Model versioning.

Model versioning

Only one version per ledger is active at a time, and new batches use it by default. Every other version stays saved and inactive: you can run a batch on it or activate it later.

Saving a new version

Save your edits as an inactive version to keep working on them while new batches run on the active version.

Open the model and make your edits in the Model Editor
Click Save
In the save dialog, enter a Version Label to name the new version (e.g. 2026 Emissions Update)
Optionally add a Description of what the version is for or what changed, up to 500 characters
Uncheck Set as active version to keep the current active version in use for new batches. Leave it checked to activate the new version on save. It starts checked when you edit the active version.

Validate your edits before saving. A model that fails validation can’t be saved. To check an inactive version’s results, generate a batch with it picked in Override model versions.

Labeling and activating a version

Open the version dropdown on the model to see all versions for the ledger
Click the edit icon next to a version
To rename it, update the Version Label or Description and click Save
To make it the active version, turn on the Activate switch and confirm. The previous active version becomes inactive, and new batches use this one.

Any saved version can be activated, including an older one.

How versions interact with batches

Each batch keeps the version that produced it. Activating a new version doesn’t change batches you’ve already generated.
To run a batch on a version other than the active one, pick it in Override model versions when you generate the batch. See Overriding the model version for a batch.
The model header and model cards show the active version’s number and label.
A batch’s Calculations tab shows the version that produced it.
The ledger total and reports add up batches from every version of the model.

Example: moving to a new methodology version

Say a methodology you report under publishes v5 to replace v4, and your registry tells you which periods to calculate on each. Add v5 as a new version of the same model, on the same ledger. The ledger keeps one batch history, and each batch shows which version calculated it. If v5 calculates a different output unit or needs a different ledger, build a new model instead.

Generating a period that already has a batch, on a different version, adds a second batch for that period. Both count toward the ledger total until you delete one.

Label the version in use today

Open the version dropdown, click the edit icon on the active version, label it Methodology v4, describe the methodology version it implements, and click Save.

Save v5 as an inactive version

Edit the model to match the new methodology, click Save, label it Methodology v5, and uncheck Set as active version. New batches still run on v4.

Preview v5 on a recent period

Generate a batch for a period that already has a v4 batch, with Methodology v5 picked in Override model versions. Compare the two batches’ Calculations tabs, then delete the preview batch.

Generate the remaining v4 periods

While v4 is still active, generate any periods your registry still requires on v4. Doing it now saves picking v4 in the override for each one later.

Activate v5

Turn on the Activate switch for Methodology v5. New batches run on v5 by default, and your v4 batches don’t change.

To calculate a v4 period that has no batch yet after v5 is active, generate it with Methodology v4 picked in Override model versions. You don’t need to activate v4 again.

Recalculating a past period on another model version

To replace a period’s batch with one calculated on another version:

Open the batch’s Calculations tab and note its results. Note the version each downstream batch for the same period ran on, too.
Check that the batch can be deleted. A batch allocated to a report or an issuance, or used by a downstream batch, can’t be: the delete action names what’s blocking it. Remove it from a draft report, and delete the downstream batches that use it. A batch in a report that is pending, completed or verified can’t be deleted, and that period stays as reported.
Delete the batch, then generate the period again with the version you want picked in Override model versions.
Regenerate the downstream batches you deleted, picking the version each one ran on before in Override model versions. Then add the batch back to its report.

Defining new nodes

Nodes can be added to the model to represent specific variables in the accounting equations. Each node can:

Receive a value from a data source (data_point_type)
Use a constant/mapped value from a library, or
Have its value calculated from child nodes through the defined operator

    - name: Input Node
      data_point_type: {{input-data-point-slug}}
    - name: Static Input Node
      data_point_type: {{static-input-slug}}
    - name: Constant Node
      constant: {{value}}

    - name: Calculated Node
      operator: summation
      nexus_nodes_attributes:
      - name: Child Node 1
        data_point_type: {{child-data-point-slug}}
      - name: Child Node 2
        data_point_type: {{child-data-point-slug2}}

- name: Output Node
  operator: summation
  data_point_type: output-slug
  nexus_nodes_attributes:
  - name: Intermediate Calc A
    ...
  - name: Intermediate Calc B
    ...
}

See Reference below for the full list of parameters that can be defined on each node.

Units

Units are not always required to be defined on nodes, but are very helpful for legibility especially when data is run through operator expressions. Use output_unit to define the expected result unit:

Example with units

nexus_nodes_attributes:
- name: Calculated EF
  output_unit: tCO2e/tonne
  operator: quotient
  nexus_nodes_attributes:
  - name: Emissions
    order: 0
    output_unit: kgCO2e  // note that Mangrove supports unit conversion above
    data_point_type: emissions-datapoint-slug
  - name: Mass
    order: 1
    output_unit: U.S. ton  // note that Mangrove supports unit conversion above
    data_point_type: mass-datapoint-slug

See Reference below: units have to conform to the supported syntax from the Unitwise library. Mismatched units between inputs on the same tier of nodes can result in errors unless explicitly converted upstream.

Testing models

Models can be tested by running them with a set of inputs to confirm the calculations. How to test the models:

Open the Model Editor by clicking on Edit/Test besides the model name
Switch to Test Model
Define a time range (this is necessary for certain calculations that consider duration), enter values for the model’s required inputs, and Run Test
Review the output calculations in the Console

Reference

Below is the full list of fields that can be configured on nodes within a model.

required

Name of the variable

Unit. We use the Unitwise library to interpret units. Here’s a list of library-supported units.

Specifies whether the values of that node represent a type of GHG calculation. Possible values: co2e

Specifies the node’s order in the parent node’s equation

Defines a new tier of child nodes.

Specifies the datapoint slug that the nodes is associated with, defining the node as either an input node that expects incoming data, or an input node tied to a Static Input.

Operation performed on the child nodes. A detailed guide to operations can be found here.

Operator	Function
Keisan expressions	Mathematical expressions using the Keisan library. See the Model Expressions guide for syntax and examples.
summation	Sums all child node values
difference	Subtracts subsequent values from the first. Child nodes have to be set in the right `order`.
product	Multiplies all child node values
quotient	Divides subsequent values from the first. Child nodes have to be set in the right `order`.
max	Finds the maximum value across all child node values
min	Finds the minimum value across all child node values
average	Finds the average of all child node values
count	Returns the count of child node values
data_point_proportion	Special operator used to extract the allocation proportion from an allocated node
duration	Special operator used to convert the time range of the incoming datapoint into a duration
map	Maps a value from a linked library

Sets a constant value on the node.

default:"true"

If set to false, the node’s computation behaviour will change such that it will always return an array in which the computation is applied to each element of the input. If the node is using data points as input, the array will have the same length as the number of data points found for that data flow. If the node is using multiple child nodes as input, the operator is applied piece-wise across each child’s output array to derive one output array.

Model Operators

Read more on how to write mathematical and logical expressions in Mangrove models.

Overview

Production Accounting

Data Collection

Data Rules

Reporting

Inventory

Account Admin

Portfolio

Building models

Editing models

Model versioning

Saving a new version

Labeling and activating a version

How versions interact with batches

Example: moving to a new methodology version

Recalculating a past period on another model version

Defining new nodes

Units

Testing models

Reference

Further Reading

Model Operators

​Building models

​Editing models

​Model versioning

​Saving a new version

​Labeling and activating a version

​How versions interact with batches

​Example: moving to a new methodology version

​Recalculating a past period on another model version

​Defining new nodes

​Units

​Testing models

​Reference

​Further Reading

Model Operators

Building models

Editing models

Model versioning

Saving a new version

Labeling and activating a version

How versions interact with batches

Example: moving to a new methodology version

Recalculating a past period on another model version

Defining new nodes

Units

Testing models

Reference

Further Reading