Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
152 commits
Select commit Hold shift + click to select a range
ea9262e
Extra mapping with status vector test
Samuel-amap Jan 22, 2025
cff3325
XPalm downstream test/benchmark
Samuel-amap Jan 27, 2025
926cbad
Attempt at adding a github action to run several benchmarks and track…
Samuel-amap Jan 27, 2025
9f5c36e
Minor change to the PSE benchmark to try and force GH action to trigg…
Samuel-amap Jan 27, 2025
eb02b86
Fix yml typo
Samuel-amap Jan 27, 2025
34fcc74
Fix more yml typos
Samuel-amap Jan 27, 2025
215d24b
deactivate XPalm benchmark for now
Samuel-amap Jan 27, 2025
7da246c
Also remove XPalm from the project toml, woops
Samuel-amap Jan 27, 2025
2359f87
Attempt to fix output.json path
Samuel-amap Jan 27, 2025
2b5f0c3
Better job naming
Samuel-amap Jan 27, 2025
7a43f53
Attempt to fix output file path on GH actions
Samuel-amap Jan 27, 2025
b1daba9
Typo fix
Samuel-amap Jan 27, 2025
8da1013
typo fix
Samuel-amap Jan 27, 2025
5dc4104
Fix json output file path...
Samuel-amap Jan 27, 2025
d43ea54
Make the CI job run with 4 threads instead of single-threaded
Samuel-amap Jan 27, 2025
0f93474
Remove Manifest.toml preventing branch switch to gh-pages after bench…
Samuel-amap Jan 27, 2025
2482cbb
Add Dates to the test environment for MT tests
Samuel-amap Jan 27, 2025
20af2ae
Typo fix
Samuel-amap Jan 27, 2025
ea108a4
Reintroduce testing on pull-request
Samuel-amap Jan 27, 2025
4fe6ba2
Fix MT test with module/environment issue
Samuel-amap Jan 27, 2025
b071640
Reenable manual workflow triggering, and for pushes on the test branch
Samuel-amap Jan 27, 2025
09837a1
MT test fix, slightly pertube PSE benchmark
Samuel-amap Jan 27, 2025
4ebf71e
Fix attempt for launching with 4 threads
Samuel-amap Jan 27, 2025
d0c81ba
Switch min to median in MT test (more reliable)
Samuel-amap Jan 27, 2025
338cff7
Attempt to distinguish between OSes for benchmark tracking and avoid …
Samuel-amap Jan 27, 2025
80c3c28
Fix typos
Samuel-amap Jan 27, 2025
445892c
Remove 1.9 tests. There currently is a precompilation issue with Stat…
Samuel-amap Jan 27, 2025
38ff559
Add small margin on MT vs ST comparison to avoid false positives on w…
Samuel-amap Jan 27, 2025
f8c971f
Modify MT test to avoid more runner false positives
Samuel-amap Jan 28, 2025
1adb53f
Add Rémi to the cc alert email sending on performance drop
Samuel-amap Jan 28, 2025
53e3c6d
Deliberately crash PSE benchmark, for science
Samuel-amap Jan 28, 2025
6babbb6
Restore PSE benchmark, with a somewhat faster-running model
Samuel-amap Jan 28, 2025
ef330c5
Restore PSE benchmark to full, expecting email from the GH benchmark …
Samuel-amap Jan 28, 2025
16d4bf2
Add multitimestep PBP benchmarks (single-threaded and multi-threaded)
Samuel-amap Jan 28, 2025
e6a8846
Deactivate a basic multithreading check on mac runners for now
Samuel-amap Jan 28, 2025
0804e74
Start Julia with 4 threads in the benchmark GH action
Samuel-amap Jan 28, 2025
04963d9
Merge pull request #129 from VirtualPlantLab/benchmarks-github-action
Samuel-amap Jan 28, 2025
5cee6a2
Extra mapping with status vector test
Samuel-amap Jan 22, 2025
117b679
Merge remote-tracking branch 'origin/Outputs-filtering2' into Outputs…
Samuel-amap Jan 29, 2025
90b3a37
Activate benchmark tracking for this branch
Samuel-amap Jan 29, 2025
a389b1f
Make run! return outputs filtered by the user. Struct is external to …
Samuel-amap Jan 30, 2025
b4daa02
warning message typo fix
Samuel-amap Jan 30, 2025
3c1bfd9
Basic helper functions that return a few commonly used modellists and…
Samuel-amap Jan 30, 2025
4da7c79
Enhance the outputs filtering test (currently errors because some sta…
Samuel-amap Jan 30, 2025
fc89194
Change modellist status to be a single status and not a timesteptable…
Samuel-amap Jan 31, 2025
7963a31
More fixes
Samuel-amap Jan 31, 2025
76f3eaf
Fix multi-object run! function and tests (+ other tests). Not sure th…
Samuel-amap Feb 3, 2025
8bbf9da
Fix some remaining ModelList status issues that break some tests
Samuel-amap Feb 3, 2025
01d7daf
Small changes/fixes/hacks. All tests pass except for documentation. T…
Samuel-amap Feb 3, 2025
5f16eb9
Fix to the modellist outputs filtering test
Samuel-amap Feb 3, 2025
412b542
Remove commented out code and outdated comments, remove vars_not_prop…
Samuel-amap Feb 6, 2025
85e7526
Fix run! behaviour in modellist mode for dataframerow-type meteos. Mu…
Samuel-amap Feb 6, 2025
30f4984
Add tests for #105, #111, #86
Samuel-amap Feb 10, 2025
a0e47cf
oops, forgot #86
Samuel-amap Feb 10, 2025
c9e8d33
Add a mapping bank for more tests
Samuel-amap Feb 10, 2025
21d859f
Removed remaining parallelisation check in multiscale. Made run! retu…
Samuel-amap Feb 10, 2025
634b296
Fix some tests, fix some meteo handling
Samuel-amap Feb 11, 2025
85ea272
Reintroduce XPalm in downstream tests (and benchmarks), now that it i…
Samuel-amap Feb 11, 2025
e5aaf5c
Documentation changes, some drafts
Samuel-amap Feb 14, 2025
66bbdbd
Simple and completely unrealistic example plant simulation to illustr…
Samuel-amap Feb 17, 2025
603bfce
Multiscale : expected default outputs behaviour (save everything if n…
Samuel-amap Feb 17, 2025
283c675
Documentation, lots of changes. Added some multiscale plant examples …
Samuel-amap Feb 21, 2025
41891ed
More documentation updates. This commit is mostly minor edits, fixing…
Samuel-amap Feb 21, 2025
f9e2f0e
Fixed many jldoctests to conform with API changes, documentation now …
Samuel-amap Feb 26, 2025
f24421d
One failing test on the CI side, might be a setup issue... ?
Samuel-amap Feb 26, 2025
5f108e9
Deactivating currently unreliable naive MT vs ST check, pending furth…
Samuel-amap Feb 26, 2025
db5813e
Change the name of the outputs(out, sink ...) functions to convert_ou…
Samuel-amap Feb 26, 2025
5c2331f
Split XPalm downstream benchmark into setup, run and outputs conversi…
Samuel-amap Feb 26, 2025
877dbe6
Oversight, forgot to rename one outputs function
Samuel-amap Feb 26, 2025
9f519f5
Split API into two pages, minor edits
Samuel-amap Feb 26, 2025
5cd5338
Update make.jl
VEZY Feb 28, 2025
36f209d
Documentation : add a third part to the Toy Plant multiscale example …
Samuel-amap Feb 28, 2025
eb5a0e1
Rename mapping kwarg to mapped_variables in mapping declarations, to …
Samuel-amap Mar 3, 2025
c2f73b4
Slightly awkward change to enable proper type promotion in the modell…
Samuel-amap Mar 3, 2025
3d17f29
Several documentation changes : two new pages, one deleted, many smal…
Samuel-amap Mar 4, 2025
1181396
Documentation : many changes : extra pages for single to multiscale c…
Samuel-amap Mar 4, 2025
86f534c
Added a doc page describing multiscale differences from single-scale.…
Samuel-amap Mar 5, 2025
2631878
Add a page for fp summation approximation errors. Edit the already ex…
Samuel-amap Mar 5, 2025
f91394c
Minor documentation edits
Samuel-amap Mar 5, 2025
a61d72e
Quick hackery to ensure documentation builds. Reminder : API page nee…
Samuel-amap Mar 5, 2025
05a7553
Update doc table of contents : some pages hadn't been added
Samuel-amap Mar 5, 2025
2ce1320
Documentation : fixing up TODOs and broken reference, small syntax ch…
Samuel-amap Mar 6, 2025
0d9d215
Update README.md
VEZY Mar 6, 2025
b0ea66c
Update index.md
VEZY Mar 6, 2025
2999bfc
Update why_julia.md
VEZY Mar 6, 2025
2ecf44e
Fixing up many broken refs and TODOs, still a fair few left
Samuel-amap Mar 6, 2025
0f3d8ac
Removed more TODOs, added tables of contents to most of the longer pa…
Samuel-amap Mar 6, 2025
ce40f5e
Update why_julia.md
VEZY Mar 6, 2025
a57aee5
Merge branch 'Outputs-filtering2' of https://github.com/VirtualPlantL…
VEZY Mar 6, 2025
f6ba12d
Update why_plantsimengine.md
VEZY Mar 6, 2025
ca96db2
Update why_julia.md
VEZY Mar 6, 2025
96c5ada
Update why_plantsimengine.md
VEZY Mar 6, 2025
9402635
Avoid hardcoding types in toy plant example. Attempt at proper public…
Samuel-amap Mar 6, 2025
aea2bfe
Merge branch 'Outputs-filtering2' of https://github.com/VirtualPlantL…
VEZY Mar 6, 2025
36d5d2f
Update why_plantsimengine.md
VEZY Mar 7, 2025
816376b
Minor documentation edits
Samuel-amap Mar 7, 2025
143fdaf
Add some more to_initialize tests (only on correct mappings though, n…
Samuel-amap Mar 7, 2025
68b37d0
Update index and readme
VEZY Mar 7, 2025
d258f12
Merge branch 'Outputs-filtering2' of https://github.com/VirtualPlantL…
VEZY Mar 7, 2025
17d92b0
Update why_plantsimengine.md
VEZY Mar 7, 2025
3366791
Patch up more links, document two more types of error, add the ML ima…
Samuel-amap Mar 10, 2025
343e57a
Oops, file wasn't properly saved, ML image was missing
Samuel-amap Mar 10, 2025
2bbab30
Fix ML image path, add MTG images
Samuel-amap Mar 10, 2025
2e7136a
Add more images explaining graphs, couplings, dependencies and fix de…
Samuel-amap Mar 10, 2025
65d9e44
Fix a couple of images, rename visualization page
Samuel-amap Mar 10, 2025
f0c700b
Couple of display fixes, add the single- to multi-scale automatic mod…
Samuel-amap Mar 11, 2025
05d0b9e
Attempt at using @example usepkg in a new page
Samuel-amap Mar 11, 2025
fd7703e
Very minor syntax changes
Samuel-amap Mar 11, 2025
70440af
Several minor fixes, more doc testing implementation
Samuel-amap Mar 11, 2025
d57fff1
Minor doc edits
Samuel-amap Mar 11, 2025
381e657
Make the floating point page, and toy plant part 1 and 2 (not 3) doct…
Samuel-amap Mar 11, 2025
cc1dd3d
Add a section detailing multiscale outputs subtleties, add an example…
Samuel-amap Mar 11, 2025
7fd010b
Clarify toy plant organ growth bug, other minor edits
Samuel-amap Mar 11, 2025
608fe08
Fix a broken ref
Samuel-amap Mar 11, 2025
dd48ffe
Julia basics page now has pointers and links. New PSE setup page, inc…
Samuel-amap Mar 12, 2025
f8e0423
Properly display MTG in toy plant tutorial part 1. API: example model…
Samuel-amap Mar 12, 2025
55762ae
Oops, broke documentation building
Samuel-amap Mar 12, 2025
1a8bbce
Add a page showcasing how to visualize an MTG (no 3D, very basic) + m…
Samuel-amap Mar 17, 2025
17ac0c8
Quick edit to remove two functions from the public API page. Was a mi…
Samuel-amap Mar 17, 2025
f83e791
Changes to avoid large DataFrame outputs + fix TT_cu in single to mul…
Samuel-amap Mar 17, 2025
62c618f
Oops, broke make.jl again
Samuel-amap Mar 17, 2025
4f9d58a
Typo on a df
Samuel-amap Mar 17, 2025
f4e7adf
Julia/PSE installing page completion
Samuel-amap Mar 17, 2025
4715ad2
Minor correction
Samuel-amap Mar 17, 2025
5f4404c
Add @ref links to a shitload of public API keywords in the doc
Samuel-amap Mar 18, 2025
f37877d
Add a link that was missing
Samuel-amap Mar 18, 2025
08f799c
Extra explanations and back-references in the more beginner tutorials…
Samuel-amap Mar 18, 2025
bdf98bb
Fixing more links, general layout and typo cleanup from a quick skimm…
Samuel-amap Mar 18, 2025
057bba8
Reimplement FLoops multi-timestep parallelization. Minor modification…
Samuel-amap Mar 20, 2025
25cc41e
Add a basic developer guidelines page
Samuel-amap Mar 20, 2025
237348b
CI : try and force integration tests to make use of a different branc…
Samuel-amap Mar 20, 2025
f45ff7a
CI : second attempt, use correct branch name
Samuel-amap Mar 20, 2025
de4b5ba
CI : attempt #3 at checking out different branch
Samuel-amap Mar 21, 2025
9957b55
CI : attempt #4...
Samuel-amap Mar 21, 2025
93feb62
Fix situation where user provides a Tables-like status. Was properly …
Samuel-amap Mar 21, 2025
5f43b4a
CI : special character quirk for XPalm
Samuel-amap Mar 21, 2025
79f9b15
CI : typo
Samuel-amap Mar 21, 2025
519107f
Don't force # of threads to be 4 for the MT/performance tests
Samuel-amap Mar 21, 2025
503d6f9
CI : revert previous change, doesn't seem to fix special characters
Samuel-amap Mar 21, 2025
72c17d1
CI : Renamed XPalm branch, see if that works out
Samuel-amap Mar 21, 2025
b7f1d2f
Fix test related to fitting (name export conflict, needs proper inves…
Samuel-amap Mar 21, 2025
4b9ff56
Add a proper 3D Toy Plant visualization demo using PlantGeom (based o…
Samuel-amap Mar 28, 2025
286af71
Update developers.md
VEZY Apr 3, 2025
82f1e7f
Remove credits (we'll work onto that later)
VEZY Apr 5, 2025
565c8ae
Update key_concepts.md
VEZY Apr 5, 2025
d4ded36
Update planned_features.md
VEZY Apr 5, 2025
b6a4ce1
Update model_execution.md
VEZY Apr 5, 2025
6c3ddec
Credits.md page was removed but still included in the doc generation …
Samuel-amap Apr 14, 2025
fba0b66
Docs : a ref also needed fixing
Samuel-amap Apr 14, 2025
3c2e2b5
Deactivate XPalm benchmark, and unregister this branch from benchmarks
Samuel-amap Apr 14, 2025
3d2a8e0
Remove XPalm from downstream project.toml
Samuel-amap Apr 14, 2025
e869589
Remove remaining TODOs from the documentation
Samuel-amap Apr 14, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/CI.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,8 @@ jobs:
- uses: julia-actions/cache@v2
- uses: julia-actions/julia-buildpkg@v1
- uses: julia-actions/julia-runtest@v1
env:
JULIA_NUM_THREADS: 4
- uses: julia-actions/julia-processcoverage@v1
- uses: codecov/codecov-action@v5
with:
Expand Down
5 changes: 3 additions & 2 deletions .github/workflows/Integration.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,8 @@ jobs:
arch:
- x64
package:
#- {user: PalmStudio, repo: XPalm.jl}
- {user: VEZY, repo: PlantBioPhysics.jl}
- {user: PalmStudio, repo: XPalm.jl, branch: PSE-API-changes}
- {user: VEZY, repo: PlantBioPhysics.jl, branch: ModelList-outputs-filtering-changes}
steps:
- uses: actions/checkout@v4
- uses: julia-actions/setup-julia@v2
Expand All @@ -45,6 +45,7 @@ jobs:
uses: actions/checkout@v4
with:
repository: ${{ matrix.package.user }}/${{ matrix.package.repo }}
ref: ${{matrix.package.branch}}
path: downstream
- name: Load this and run the downstream tests
shell: julia --threads 4 --color=yes --project=downstream --depwarn=yes {0}
Expand Down
70 changes: 70 additions & 0 deletions .github/workflows/benchmarks_and_downstream.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
name: BenchmarksAndDownstream
on:
push:
branches:
- main
- benchmarks-github-action
tags: "*"
workflow-dispatch:
permissions:
# deployments permission to deploy GitHub pages website
deployments: write
# contents permission to update benchmark contents in gh-pages branch
contents: write
jobs:
test:
name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
runs-on: ${{ matrix.os }}
timeout-minutes: 60
env:
GROUP: ${{ matrix.package.group }}
strategy:
fail-fast: false
matrix:
version:
- "1"
os:
- ubuntu-latest
- macOS-latest
- windows-latest
arch:
- x64
package:
- {user: VEZY, repo: PlantSimEngine.jl, group: Downstream}
steps:
- uses: actions/checkout@v4
- uses: julia-actions/setup-julia@v2
with:
version: ${{ matrix.version }}
arch: ${{ matrix.arch }}
# TODO handle breaking changes the way downstream tests do ?
# NOTE : manifest toml file is removed otherwise git whines about untracked changes when switching branches for the gh-pages commit
- name: Run benchmarks
run: |
cd test/downstream
julia --project --threads 4 --color=yes -e '
using Pkg;
Pkg.instantiate();
include("test-all-benchmarks.jl")'
rm Manifest.toml
- name: Store benchmark result
uses: benchmark-action/github-action-benchmark@v1
with:
name: Julia benchmark result
tool: 'julia'
output-file-path: ${{ github.workspace }}/test/downstream/output.json
# Use personal access token instead of GITHUB_TOKEN due to https://github.community/t/github-action-not-triggering-gh-pages-upon-push/16096
github-token: ${{ secrets.GITHUB_TOKEN }}
auto-push: true
# Show alert with commit comment on detecting possible performance regression
alert-threshold: '130%'
comment-on-alert: true
fail-on-alert: true
alert-comment-cc-users: '@Samuel-AMAP, @VEZY'

- uses: julia-actions/julia-processcoverage@v1
- uses: codecov/codecov-action@v5
with:
token: ${{ secrets.CODECOV_TOKEN }}
files: lcov.info
fail_ci_if_error: false
104 changes: 66 additions & 38 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,31 +9,54 @@
[![DOI](https://zenodo.org/badge/571659510.svg)](https://zenodo.org/badge/latestdoi/571659510)
[![JOSS](https://joss.theoj.org/papers/137e3e6c2ddc349bec39e06bb04e4e09/status.svg)](https://joss.theoj.org/papers/137e3e6c2ddc349bec39e06bb04e4e09)

- [PlantSimEngine](#plantsimengine)
- [Overview](#overview)
- [Unique Features](#unique-features)
- [Automatic Model Coupling](#automatic-model-coupling)
- [Flexibility with Precision Control](#flexibility-with-precision-control)
- [Batteries included](#batteries-included)
- [Ask Questions](#ask-questions)
- [Installation](#installation)
- [Example usage](#example-usage)
- [Simple example](#simple-example)
- [Model coupling](#model-coupling)
- [Multiscale modelling](#multiscale-modelling)
- [Projects that use PlantSimEngine](#projects-that-use-plantsimengine)
- [Performance](#performance)
- [Make it yours](#make-it-yours)

## Overview

`PlantSimEngine` is a modelling framework for simulating and modelling plants, soil and atmosphere. It provides tools to **prototype, evaluate, test, and deploy** plant/crop models at any scale, with a strong emphasis on performance and efficiency.
`PlantSimEngine` is a comprehensive framework for building models of the soil-plant-atmosphere continuum. It includes everything you need to **prototype, evaluate, test, and deploy** plant/crop models at any scale, with a strong emphasis on performance and efficiency, so you can focus on building and refining your models.

**Key Features:**
**Why choose PlantSimEngine?**

- Process Definition: Easily define new processes such as light interception, photosynthesis, growth, soil water transfer, and more.
- Interactive Prototyping: Fast and interactive prototyping of models with built-in constraints to avoid errors and sensible defaults to streamline the model writing process.
- Control Degrees of Freedom: Fix variables, pass measurements, or use simpler models for specific processes to reduce complexity.
- Automatic Management: The package automatically manages input and output variables, time-steps, objects, and the coupling of models using a dependency graph.
- Flexible Model Switching: Switch between models without changing any code, using a simple syntax to specify the model for a given process.
- Integrated Data Use: Force variables to take measured values instead of model predictions, reducing degrees of freedom during model development and increasing accuracy during production mode.
- High-Performance Computation: Achieve high-speed computations, with benchmarks showing operations in the 100th of nanoseconds range for complex models (see this [benchmark script](https://github.com/VirtualPlantLab/PlantSimEngine.jl/blob/main/examples/benchmark.jl)).
- Parallel and Distributed Computing: Out-of-the-box support for sequential, multi-threaded, or distributed computations over objects, time-steps, and independent processes, thanks to [Floops.jl](https://juliafolds.github.io/FLoops.jl/stable/).
- Scalability: Scale easily with methods for computing over objects, time-steps, and [Multi-Scale Tree Graphs](https://github.com/VEZY/MultiScaleTreeGraph.jl).
- Composability: Use any types as inputs, including [Unitful](https://github.com/PainterQubits/Unitful.jl) for unit propagation and [MonteCarloMeasurements.jl](https://github.com/baggepinnen/MonteCarloMeasurements.jl) for propagating measurement error.
- **Simplicity**: Write less code, focus on your model's logic, and let the framework handle the rest.
- **Modularity**: Each model component can be developed, tested, and improved independently. Assemble complex simulations by reusing pre-built, high-quality modules.
- **Standardisation**: Clear, enforceable guidelines ensure that all models adhere to best practices. This built-in consistency means that once you implement a model, it works seamlessly with others in the ecosystem.
- **Optimised Performance**: Don't re-invent the wheel. Delegating low-level tasks to PlantSimEngine guarantees that your model will benefit from every improvement in the framework. Enjoy faster prototyping, robust simulations, and efficient execution using Julia's high-performance capabilities.

**Benefits:**
## Unique Features

Improved Accuracy and Reliability:
### Automatic Model Coupling

- Enhance the accuracy of plant growth and yield predictions by integrating detailed physiological processes and environmental interactions.
- Reduced Modeling Time: Streamline the modeling process with automated management and fast prototyping capabilities.
- Collaborative Research: Facilitate collaborative research efforts with flexible and composable modeling tools.
**Seamless Integration:** PlantSimEngine leverages Julia's multiple-dispatch capabilities to automatically compute the dependency graph between models. This allows researchers to effortlessly couple models without writing complex connection code or manually managing dependencies.

**Intuitive Multi-Scale Support:** The framework naturally handles models operating at different scales—from organelle to ecosystem—connecting them with minimal effort and maintaining consistency across scales.

### Flexibility with Precision Control

**Effortless Model Switching:** Researchers can switch between different component models using a simple syntax without rewriting the underlying model code. This enables rapid comparison between different hypotheses and model versions, accelerating the scientific discovery process.

## Batteries included

- **Automated Management**: Seamlessly handle inputs, outputs, time-steps, objects, and dependency resolution.
- **Iterative Development**: Fast and interactive prototyping of models with built-in constraints to avoid errors and sensible defaults to streamline the model writing process.
- **Control Your Degrees of Freedom**: Fix variables to constant values or force to observations, use simpler models for specific processes to reduce complexity.
- **High-Speed Computations**: Achieve impressive performance with benchmarks showing operations in the 100th of nanoseconds range for complex models (see this [benchmark script](https://github.com/VirtualPlantLab/PlantSimEngine.jl/blob/main/examples/benchmark.jl)).
- **Parallelize and Distribute Computing**: Out-of-the-box support for sequential, multi-threaded, or distributed computations over objects, time-steps, and independent processes, thanks to [Floops.jl](https://juliafolds.github.io/FLoops.jl/stable/).
- **Scale Effortlessly**: Methods for computing over objects, time-steps, and [Multi-Scale Tree Graphs](https://github.com/VEZY/MultiScaleTreeGraph.jl).
- **Compose Freely**: Use any types as inputs, including [Unitful](https://github.com/PainterQubits/Unitful.jl) for unit propagation and [MonteCarloMeasurements.jl](https://github.com/baggepinnen/MonteCarloMeasurements.jl) for measurement error propagation.

## Ask Questions

Expand All @@ -57,7 +80,7 @@ using PlantSimEngine

The package is designed to be easy to use, and to help users avoid errors when implementing, coupling and simulating models.

### Simple example
### Simple example

Here's a simple example of a model that simulates the growth of a plant, using a simple exponential growth model:

Expand Down Expand Up @@ -193,55 +216,55 @@ fig

![LAI Growth and light interception](examples/LAI_growth2.png)

### Multiscale modelling
### Multiscale modelling

> See the [Multi-scale modeling](#multi-scale-modeling) section for more details.
> See the Multi-scale modeling section of the docs for more details.

The package is designed to be easily scalable, and can be used to simulate models at different scales. For example, you can simulate a model at the leaf scale, and then couple it with models at any other scale, *e.g.* internode, plant, soil, scene scales. Here's an example of a simple model that simulates plant growth using sub-models operating at different scales:

```@example readme
```julia
mapping = Dict(
"Scene" => ToyDegreeDaysCumulModel(),
"Plant" => (
MultiScaleModel(
model=ToyLAIModel(),
mapping=[
mapped_variables=[
:TT_cu => "Scene",
],
),
Beer(0.6),
MultiScaleModel(
model=ToyAssimModel(),
mapping=[:soil_water_content => "Soil"],
mapped_variables=[:soil_water_content => "Soil"],
),
MultiScaleModel(
model=ToyCAllocationModel(),
mapping=[
mapped_variables=[
:carbon_demand => ["Leaf", "Internode"],
:carbon_allocation => ["Leaf", "Internode"]
],
),
MultiScaleModel(
model=ToyPlantRmModel(),
mapping=[:Rm_organs => ["Leaf" => :Rm, "Internode" => :Rm],],
mapped_variables=[:Rm_organs => ["Leaf" => :Rm, "Internode" => :Rm],],
),
),
"Internode" => (
MultiScaleModel(
model=ToyCDemandModel(optimal_biomass=10.0, development_duration=200.0),
mapping=[:TT => "Scene",],
mapped_variables=[:TT => "Scene",],
),
MultiScaleModel(
model=ToyInternodeEmergence(TT_emergence=20.0),
mapping=[:TT_cu => "Scene"],
mapped_variables=[:TT_cu => "Scene"],
),
ToyMaintenanceRespirationModel(1.5, 0.06, 25.0, 0.6, 0.004),
Status(carbon_biomass=1.0)
),
"Leaf" => (
MultiScaleModel(
model=ToyCDemandModel(optimal_biomass=10.0, development_duration=200.0),
mapping=[:TT => "Scene",],
mapped_variables=[:TT => "Scene",],
),
ToyMaintenanceRespirationModel(2.1, 0.06, 25.0, 1.0, 0.025),
Status(carbon_biomass=1.0)
Expand All @@ -254,13 +277,13 @@ mapping = Dict(

We can import an example plant from the package:

```@example readme
```julia
mtg = import_mtg_example()
```

Make a fake meteorological data:

```@example readme
```julia
meteo = Weather(
[
Atmosphere(T=20.0, Wind=1.0, Rh=0.65, Ri_PAR_f=300.0),
Expand All @@ -271,7 +294,7 @@ meteo = Weather(

And run the simulation:

```@example readme
```julia
out_vars = Dict(
"Scene" => (:TT_cu,),
"Plant" => (:carbon_allocation, :carbon_assimilation, :soil_water_content, :aPPFD, :TT_cu, :LAI),
Expand All @@ -285,9 +308,9 @@ out = run!(mtg, mapping, meteo, outputs=out_vars, executor=SequentialEx());

We can then extract the outputs in a `DataFrame` and sort them:

```@example readme
```julia
using DataFrames
df_out = outputs(out, DataFrame)
df_out = convert_outputs(out, DataFrame)
sort!(df_out, [:timestep, :node])
```

Expand All @@ -310,7 +333,6 @@ sort!(df_out, [:timestep, :node])
| 2 | Internode | 8 | 0.0627036 | | | | | | 0.75 |
| 2 | Leaf | 9 | 0.0627036 | | | | | | 0.75 |


An example output of a multiscale simulation is shown in the documentation of PlantBiophysics.jl:

![Plant growth simulation](docs/src/www/image.png)
Expand All @@ -319,11 +341,17 @@ An example output of a multiscale simulation is shown in the documentation of Pl

Take a look at these projects that use PlantSimEngine:

- [PlantBiophysics.jl](https://github.com/VEZY/PlantBiophysics.jl)
- [XPalm](https://github.com/PalmStudio/XPalm.jl)
- [PlantBiophysics.jl](https://github.com/VEZY/PlantBiophysics.jl) - For the simulation of biophysical processes for plants such as photosynthesis, conductance, energy fluxes, and temperature
- [XPalm](https://github.com/PalmStudio/XPalm.jl) - An experimental crop model for oil palm

## Performance

PlantSimEngine delivers impressive performance for plant modeling tasks. On an M1 MacBook Pro, a toy model for leaf area over a year at daily time-scale took only 260 μs to perform (about 688 ns per day), and 275 μs (756 ns per day) when coupled to a light interception model. These benchmarks demonstrate performance on par with compiled languages like Fortran or C, far outpacing typical interpreted language implementations.

For example, PlantBiophysics.jl, which implements ecophysiological models using PlantSimEngine, has been measured to run up to 38,000 times faster than equivalent implementations in other scientific computing languages.

## Make it yours
## Make it yours

The package is developed so anyone can easily implement plant/crop models, use it freely and as you want thanks to its MIT license.
The package is developed so anyone can easily implement plant/crop models, use it freely and as you want thanks to its MIT license.

If you develop such tools and it is not on the list yet, please make a PR or contact me so we can add it! 😃 Make sure to read the community guidelines before in case you're not familiar with such things.
Loading