DOCSEARCHbyAlgolia
Submit Docs

APSIMX Agricultural Modelling Framework

repository·master·Indexed 41 days ago

https://github.com/apsiminitiative/apsimx

A next-generation agricultural modelling framework for simulating complex agro-ecosystems. It features a hierarchical model structure managed via NodeTree and ModelNodeTree, a C# ScriptCompiler for executable code transformation, and simulation services provided by APSIM.Core. The framework supports remote control via a custom socket protocol (V1) or ZMQ + Msgpack for interactive and one-shot simulations. Additionally, it includes a GTK-based SheetWidget for displaying data via IDataProvider.

Tokens
25K
Snippets
65
Records
89
Agent score
52%

What's inside APSIMX

  1. Overview of APSIM.Core simulation services

    master

    The APSIM.Core assembly provides a collection of classes designed to facilitate simulation services within the APSIM framework. It is organized into several key functional areas:

    • NodeTree: Manages the hierarchical structure of simulation components.
    • ScriptCompiler: Handles the compilation of simulation scripts.
    • Resource: Manages simulation resources.

  2. Overview of ReportGenerator

    master
    ReportGenerator is a tool that converts XML coverage reports from various testing frameworks into human-readable formats. It provides coverage quotas, includes source code visualization, and highlights covered lines. It also supports merging multiple reports into a single output and can process a single XML file containing multiple reports (such as build logs).

  4. Understand the purpose of APSIM.Workflow

    master

    APSIM.Workflow is a specialized utility designed to prepare validation data for large-scale distributed computing. Its primary functions are:

    1. Data Splitting: It takes validation data and splits it by experiment.
    2. File Organization: It organizes all necessary input files for each of the newly created, smaller APSIM files.
    3. Workflow Generation: It generates a workflow.yml file compatible with the CSIRO Workflo tool. This file is used to orchestrate the distribution of these smaller experiments to Azure for parallel execution.
    IMPORTANT

    This project is not intended for general use. It is specifically designed for use by the APSIM Build system (GitHub Action Workflow).

  5. Communication methods for controlling APSIM

    master

    APSIM can be controlled remotely using two primary communication methods depending on your client requirements:

    1. V1 (Custom Socket Protocol): Designed for communication with APSIM.Client (a C application). It uses a custom protocol over sockets to bridge native (C) and managed (.NET) clients.
    2. ZMQ + Msgpack: A multi-language approach using ZeroMQ and msgpack. This method supports two distinct communication paradigms:
      • One-shot protocol: Starts a simulation and collects all output once the simulation terminates.
      • Interactive protocol: Allows the controlling process to pause and resume a simulation, and to get or set data dynamically while the simulation is progressing.

  6. How ModelNodeTree works and why it is used instead of IModel

    master

    While the .apsimx file is deserialized into an IModel hierarchy, most APSIM code (excluding serialization and conversion logic) operates on a ModelNodeTree.

    A ModelNodeTree is a converted representation of the IModel hierarchy. It uses ModelNode objects to store the name of the model, its parent, and its children.

    Key benefits of the ModelNodeTree:

    • Cleaner UI/UX: The ClassAdaptor wrapper is stripped away during conversion, so POCOs appear directly in the GUI rather than being nested under a 'ClassAdaptor' node.
    • Simplified Reporting: Provides a flattened or structured view suitable for reporting and IntelliSense.
    • Standardized Access: Provides a consistent way to traverse the model structure without dealing with the complexities of the underlying IModel implementation details.

  7. How NodeTree and Node work together

    master

    The APSIM model hierarchy is represented by a NodeTree containing a collection of Node objects.

    • NodeTree: The top-level container. It provides access to the Root node, a collection of all Nodes in the tree, and all Models within the tree. It also provides a WalkModels iterator for depth-first traversal of models.
    • Node: An abstraction representing a single model within the tree. Each Node encapsulates an INodeModel and maintains links to its Parent and Children nodes. This structure is what drives the user interface tree view.

    To find the specific Node associated with a model instance, use NodeTree.GetNode(INodeModel model).

  9. How POCOs are integrated into the IModel hierarchy using ClassAdaptor

    master

    In APSIMX, the model hierarchy is primarily composed of IModel instances. Because Plain Old Class Objects (POCOs) cannot directly implement the IModel interface, they are wrapped in a ClassAdaptor instance.

    To include a POCO in a simulation, it must be wrapped in a ClassAdaptor. The ClassAdaptor has a single property, Obj, which holds the reference to the actual POCO instance. This pattern allows POCOs to be serialized and deserialized within the .apsimx file format while maintaining the required IModel hierarchy.

    {
    "$type": "Models.Core.ClassAdaptor, Models",
    "Obj": {
        "$type": "APSIM.Soils.Organic, APSIM.Soils",
        "FOMCNRatio": 40.0,
        "Thickness": [...],
        "Carbon": [...],
        "SoilCNRatio": [...],
        "FBiom": [...],
        "FInert": [...],
        "FOM": [...]
    },
    "Name": "ClassAdaptor",
    "ResourceName": null,
    "Children": [],
    "Enabled": true,
    "ReadOnly": false
}

  10. Implement interactive or one-shot simulation control via ZMQ+Msgpack

    master

    To implement multi-language simulation control, use the ZMQ + Msgpack protocol. This allows for both batch processing (one-shot) and real-time manipulation (interactive).

    For implementation details, sample code and tests are located in the Tests/Simulation/ZMQ-Sync directory of the repository.

    # Refer to Tests/Simulation/ZMQ-Sync for implementation samples

  11. Derive Height, Cover, and Root Depth Patterns

    master

    Once the biomass curve is established, other morphological patterns can be derived by applying different logistic parameters ($X_o$ and $b$) and conditional logic for senescence or maximum limits.

    • Root Depth: Often modeled as a linear increase in relative development up to a maximum stage, then plateauing.
    • Cover and Height: Modeled using logistic curves with different inflection points ($X_o$) and rates ($b$). During senescence, cover can be modeled as a linear decline.
    # Example logic for deriving patterns
for tt in RDs:
    # Root Depth logic
    if tt < Tt_maxRD:
        rd = tt/Tt_maxRD
    else:
        if tt < Tt_EmergtoMat:
            rd = 1.0
    RootDepthScaller.append(rd)

    # Cover and Height logic
    if tt < Tt_sen:
        cover = 1/(1+np.exp(-(tt-Xo_cov)/b_cov))
        height = 1/(1+np.exp(-(tt-Xo_hig)/b_hig))
    else:
        if tt < Tt_EmergtoMat:
            cover = (1-(tt-Tt_sen)/(Tt_EmergtoMat-Tt_sen))
            height = 1.0
    CoverScaller.append(cover)
    HeightScaller.append(height)

  12. Apply model changes via RunCommand

    master

    When initializing a RunCommand, you can provide a collection of IModelCommand objects via the changes parameter. These changes are applied to the simulations by the jobRunner before the actual simulation execution begins. This is useful for dynamically modifying model parameters or configurations as part of a batch run.

    // The changes are passed into the constructor and applied during the Run() method
public RunCommand(IEnumerable<IModelCommand> changes)
{
    this.changes = changes.ToList();
    // ... other defaults
}