### Running Examples with Pluto.jl

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/examples.md

Instructions on how to run the provided example notebooks using Pluto.jl. This involves copying a download URL and pasting it into the Pluto.jl interface.

```Markdown
Any example found in the online documentation is most easily run using [Pluto.jl](https://github.com/fonsp/Pluto.jl). Just copy the corresponding `download / url` link (see above) and paste into the [Pluto.jl interface](https://github.com/fonsp/Pluto.jl/wiki/🔎-Basic-Commands-in-Pluto).
```

--------------------------------

### Running Examples via Command Line

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/examples.md

Instructions for running the example notebooks from the command line using Julia's `include` function. Highlights the need to manually add packages when not using Pluto.jl.

```Julia
julia -e 'include("defaults.jl")'
```

--------------------------------

### Install PlanktonIndividuals.jl

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/README.md

Adds the PlanktonIndividuals.jl package to the current Julia environment. This is the standard method for installing Julia packages.

```julia
using Pkg; Pkg.add("PlanktonIndividuals.jl")
```

--------------------------------

### Closer Look Into One Grid Box Example

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/README.md

Provides an example for analyzing PlanktonIndividuals.jl behavior within a single grid box (0D experiment). It loads the package and runs a specific 0D experiment script.

```julia
using PlanktonIndividuals
p = dirname(pathof(PlanktonIndividuals))
include(joinpath(p,"../examples/0D_experiment.jl"))
```

--------------------------------

### Simple Flow Fields In Two Dimensions Example

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/README.md

Demonstrates the use of PlanktonIndividuals.jl with simple 2D flow fields. It includes loading the package and executing an example script for horizontal 2D simulations.

```julia
using PlanktonIndividuals
p = dirname(pathof(PlanktonIndividuals))
#include(joinpath(p,"../examples/vertical_2D_example.jl"))
include(joinpath(p,"../examples/horizontal_2D_example.jl"))
```

--------------------------------

### 0-Dimensional Model Benchmark Results

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/benchmarks.md

Presents benchmark results for a 0-dimensional PlanktonIndividuals model setup. It includes performance metrics (min, median, mean, max time), memory usage, and allocations for CPU and GPU architectures with varying numbers of individuals.

```julia
PlanktonIndividuals v0.6.1
Julia Version 1.8.0
Commit 5544a0fab76 (2022-08-17 13:38 UTC)
Platform Info:
  OS: Linux (x86_64-pc-linux-gnu)
  CPU: Intel(R) Xeon(R) CPU E5-2680 v4 @ 2.40GHz
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-13.0.1 (ORCJIT, broadwell)
  GPU: Tesla P100-PCIE-12GB
  CUDA runtime 11.8, artifact installation
  CUDA driver 11.2
  NVIDIA driver 460.84.0

| Arch |       N |        min |     median |       mean |        max |     memory | allocs |
|------|---------|------------|------------|------------|------------|------------|--------|
|  CPU |    1024 |   2.945 ms |   3.016 ms |   3.167 ms |   4.328 ms | 478.67 KiB |   2992 |
|  CPU |   32768 |  69.741 ms |  69.812 ms |  71.594 ms |  80.231 ms | 477.72 KiB |   2931 |
|  CPU |  131072 | 276.553 ms | 276.966 ms | 280.569 ms | 300.907 ms | 477.72 KiB |   2931 |
|  CPU | 1048576 |    2.582 s |    2.590 s |    2.590 s |    2.598 s | 477.72 KiB |   2931 |
|  GPU |    1024 |   7.085 ms |   7.158 ms |   7.364 ms |   9.323 ms |   1.92 MiB |  21327 |
|  GPU |   32768 |   7.435 ms |   7.520 ms |   7.925 ms |  10.173 ms |   1.92 MiB |  21327 |
|  GPU |  131072 |   7.053 ms |   9.161 ms |   9.851 ms |  19.812 ms |   1.92 MiB |  21294 |
|  GPU | 1048576 |   8.005 ms |  46.217 ms |  47.484 ms | 122.516 ms |   1.92 MiB |  21294 |
```

--------------------------------

### 3D Model Benchmark Results (CPU vs GPU)

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/benchmarks.md

Tabular data comparing the performance of a 3-Dimensional model setup for PlanktonIndividuals across CPU and GPU. It includes metrics like minimum, median, mean, and maximum execution times, memory usage, and allocation counts for different grid sizes (Ns) and problem sizes (N).

```text
| Arch |       N |  Ns |        min |     median |       mean |        max |   memory | allocs |
|------|---------|-----|------------|------------|------------|------------|----------|--------|
|  CPU |    1024 |  32 |  50.081 ms |  50.249 ms |  50.421 ms |  51.994 ms | 1.38 MiB |   2820 |
|  CPU |    1024 |  64 | 410.840 ms | 459.105 ms | 451.043 ms | 459.516 ms | 8.43 MiB |   2821 |
|  CPU |   32768 |  32 | 124.176 ms | 124.312 ms | 126.438 ms | 138.224 ms | 1.38 MiB |   2820 |
|  CPU |   32768 |  64 | 498.713 ms | 534.237 ms | 534.148 ms | 554.501 ms | 8.43 MiB |   2821 |
|  CPU |  131072 |  32 | 351.282 ms | 351.674 ms | 355.733 ms | 387.071 ms | 1.38 MiB |   2820 |
|  CPU |  131072 |  64 | 790.994 ms | 808.337 ms | 816.691 ms | 848.149 ms | 8.43 MiB |   2821 |
|  CPU | 1048576 |  32 |    3.019 s |    3.072 s |    3.072 s |    3.125 s | 1.38 MiB |   2820 |
|  CPU | 1048576 |  64 |    3.258 s |    3.258 s |    3.258 s |    3.258 s | 8.43 MiB |   2821 |
|  GPU |    1024 |  32 |   6.229 ms |   6.286 ms |   6.466 ms |   7.329 ms | 2.94 MiB |  21053 |
|  GPU |    1024 |  64 |   9.194 ms |  11.891 ms |  11.689 ms |  12.604 ms | 9.99 MiB |  21077 |
|  GPU |   32768 |  32 |   6.570 ms |   6.638 ms |   6.966 ms |   8.974 ms | 2.94 MiB |  21053 |
|  GPU |   32768 |  64 |   9.143 ms |  12.882 ms |  12.712 ms |  15.781 ms | 9.99 MiB |  21077 |
|  GPU |  131072 |  32 |   6.481 ms |   9.150 ms |   9.469 ms |  16.907 ms | 2.94 MiB |  21081 |
|  GPU |  131072 |  64 |   9.212 ms |  16.623 ms |  16.438 ms |  25.557 ms | 9.99 MiB |  21105 |
|  GPU | 1048576 |  32 |   7.257 ms |  39.894 ms |  40.268 ms |  96.189 ms | 2.94 MiB |  21020 |
|  GPU | 1048576 |  64 |   9.586 ms |  54.934 ms |  53.741 ms | 118.675 ms | 9.99 MiB |  21105 |
```

--------------------------------

### 2-Dimensional Model Benchmark Results

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/benchmarks.md

Details benchmark results for a 2-dimensional PlanktonIndividuals model setup with varying grid cell resolutions (Ns). It provides performance metrics, memory usage, and allocations for CPU and GPU architectures.

```julia
PlanktonIndividuals v0.6.1
Julia Version 1.8.0
Commit 5544a0fab76 (2022-08-17 13:38 UTC)
Platform Info:
  OS: Linux (x86_64-pc-linux-gnu)
  CPU: Intel(R) Xeon(R) CPU E5-2680 v4 @ 2.40GHz
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-13.0.1 (ORCJIT, broadwell)
  GPU: Tesla P100-PCIE-12GB
  CUDA runtime 11.8, artifact installation
  CUDA driver 11.2
  NVIDIA driver 460.84.0

| Arch |       N |  Ns |        min |     median |       mean |        max |    memory | allocs |
|------|---------|-----|------------|------------|------------|------------|-----------|--------|
|  CPU |    1024 |  32 |   8.096 ms |   8.132 ms |   8.211 ms |   8.688 ms |  2.70 MiB |   3109 |
|  CPU |    1024 |  64 |  19.889 ms |  19.940 ms |  20.064 ms |  20.952 ms |  8.68 MiB |   3052 |
|  CPU |    1024 | 128 |  68.735 ms |  69.030 ms |  69.672 ms |  75.046 ms | 31.72 MiB |   3052 |
|  CPU |   32768 |  32 |  74.115 ms |  74.154 ms |  76.313 ms |  85.288 ms |  2.70 MiB |   3048 |
|  CPU |   32768 |  64 |  89.999 ms |  90.163 ms |  92.340 ms | 101.475 ms |  8.68 MiB |   3052 |
|  CPU |   32768 | 128 | 162.286 ms | 162.618 ms | 168.129 ms | 190.011 ms | 31.72 MiB |   3052 |
|  CPU |  131072 |  32 | 282.810 ms | 282.913 ms | 286.631 ms | 307.620 ms |  2.70 MiB |   3048 |
|  CPU |  131072 |  64 | 328.584 ms | 328.962 ms | 332.448 ms | 357.787 ms |  8.68 MiB |   3052 |
|  CPU |  131072 | 128 | 447.271 ms | 453.263 ms | 470.108 ms | 509.040 ms | 31.72 MiB |   3052 |
|  CPU | 1048576 |  32 |    2.476 s |    2.476 s |    2.501 s |    2.552 s |  2.70 MiB |   3048 |
|  CPU | 1048576 |  64 |    2.910 s |    2.911 s |    2.911 s |    2.911 s |  8.68 MiB |   3052 |
|  CPU | 1048576 | 128 |    2.905 s |    2.909 s |    2.909 s |    2.914 s | 31.72 MiB |   3052 |
|  GPU |    1024 |  32 |   6.902 ms |   6.920 ms |   7.101 ms |   8.719 ms |  1.98 MiB |  21513 |
|  GPU |    1024 |  64 |   7.417 ms |   7.622 ms |   7.755 ms |   8.430 ms |  2.07 MiB |  21632 |
|  GPU |    1024 | 128 |   7.734 ms |   8.071 ms |   8.141 ms |   8.854 ms |  2.45 MiB |  21713 |
|  GPU |   32768 |  32 |   7.011 ms |   7.092 ms |   7.392 ms |  10.142 ms |  1.98 MiB |  21513 |
|  GPU |   32768 |  64 |   6.769 ms |   6.837 ms |   7.152 ms |  10.035 ms |  2.07 MiB |  21632 |
|  GPU |   32768 | 128 |   7.027 ms |   8.381 ms |   8.561 ms |  11.845 ms |  2.45 MiB |  21713 |
|  GPU |  131072 |  32 |   6.580 ms |   8.054 ms |   8.560 ms |  15.323 ms |  1.98 MiB |  21541 |
|  GPU |  131072 |  64 |   7.491 ms |   9.106 ms |   9.664 ms |  16.128 ms |  2.07 MiB |  21599 |
|  GPU |  131072 | 128 |   7.918 ms |  12.640 ms |  12.791 ms |  23.534 ms |  2.45 MiB |  21680 |
|  GPU | 1048576 |  32 |   9.781 ms |  35.539 ms |  36.437 ms |  59.171 ms |  1.98 MiB |  21528 |
|  GPU | 1048576 |  64 |  10.682 ms |  37.958 ms |  39.055 ms |  65.476 ms |  2.08 MiB |  21647 |
|  GPU | 1048576 | 128 |   7.994 ms |  50.094 ms |  50.772 ms | 126.537 ms |  2.45 MiB |  21680 |
```

--------------------------------

### Dict for Nutrient Initial Conditions from Files

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/model_setup.md

Defines the structure for initial nutrient conditions using a Dict, where keys are nutrient names and values are file paths to pre-existing initial condition data.

```julia
nut_init = Dict(
    "DIC" => "path/to/DIC.bin",
    "NH4" => "path/to/NH4.bin",
    "NO3" => "path/to/NO3.bin",
    "PO4" => "path/to/PO4.bin",
    "DOC" => "path/to/DOC.bin",
    "DON" => "path/to/DON.bin",
    "DOP" => "path/to/DOP.bin",
    "POC" => "path/to/POC.bin",
    "PON" => "path/to/PON.bin",
    "POP" => "path/to/POP.bin"
);
```

--------------------------------

### PlanktonIndividuals v0.6.1 System Information

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/benchmarks.md

Provides system and environment details for the PlanktonIndividuals v0.6.1 benchmark, including Julia version, commit hash, platform information (OS, CPU, GPU), and CUDA/NVIDIA driver versions.

```text
PlanktonIndividuals v0.6.1
Julia Version 1.8.0
Commit 5544a0fab76 (2022-08-17 13:38 UTC)
Platform Info:
  OS: Linux (x86_64-pc-linux-gnu)
  CPU: Intel(R) Xeon(R) CPU E5-2680 v4 @ 2.40GHz
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-13.0.1 (ORCJIT, broadwell)
  GPU: Tesla P100-PCIE-12GB
  CUDA runtime 11.8, artifact installation
  CUDA driver 11.2
  NVIDIA driver 460.84.0
```

--------------------------------

### Turbulent Flow Fields In Three Dimensions Example

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/README.md

Illustrates simulating turbulent 3D flow fields using PlanktonIndividuals.jl, integrating with Oceananigans.jl for velocity field generation. This example drives the individual-based model with these fields.

```julia
using PlanktonIndividuals
p = dirname(pathof(PlanktonIndividuals))
include(joinpath(p,"../examples/surface_mixing_3D_example.jl"))
```

--------------------------------

### PlanktonModel Configuration

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/model_setup.md

Specifies the configuration for the PlanktonModel using keyword arguments. This includes setting the computational architecture (CPU or GPU).

```julia
PlanktonModel(arch = CPU()) # or arch = GPU()
```

--------------------------------

### Future Development Plans

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/joss/paper.md

Outlines the planned future developments for PlanktonIndividuals.jl, including the implementation of a macro-molecular model and support for distributed parallelism with CUDA-aware MPI.

```markdown
Further development plans include implementation of macro-molecular model [@Inomura2020] and support for distributed parallelism with CUDA-aware MPI.
```

--------------------------------

### Parameter Sets

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/joss/paper.md

The package includes default parameter sets for biogeochemical properties of nutrients and physiological parameters for individual phytoplankton cells. These parameters can be customized to simulate different phytoplankton species and biogeochemical scenarios.

```Julia
# Loading default parameters:
# biogeochem_params = load_default_biogeochem_params()
# phyto_params = load_default_phytoplankton_params()

# Customizing parameters:
# custom_phyto_params = Dict(:max_growth_rate => 0.5, :quota_yield => 0.1)
# merged_params = merge(phyto_params, custom_phyto_params)
```

--------------------------------

### Plankton Model Parameters

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/phyto_equations.md

This section lists and describes the parameters used in the plankton individuals model. Each parameter includes its symbol, common name, default value, unit of measurement, and a detailed description of its role in the model.

```APIDOC
Cquota:
  Symbol: Cquota
  Default: 1.8e-11
  Unit: mmol C cell^-1
  Description: Carbon quota when Sz = 1.0

PCmax:
  Symbol: PCmax
  Default: 4.2e-5
  Unit: s^-1
  Description: Maximum photosynthesis rate

alpha:
  Symbol: \alpha
  Default: 2.0e-2
  Unit: m^2 mgChl^-1
  Description: Irradiance absorption coeff

Phi:
  Symbol: \Phi
  Default: 4.0e-5
  Unit: mmol C / \mu mol photons
  Description: Maximum quantum yield

VNH4max:
  Symbol: VNH4max
  Default: 6.9e-6
  Unit: s^-1
  Description: Maximum ammonium uptake rate

VNO3max:
  Symbol: VNO3max
  Default: 6.9e-6
  Unit: s^-1
  Description: Maximum nitrate uptake rate

VPO4max:
  Symbol: VPO4max
  Default: 1.2e-6
  Unit: s^-1
  Description: Maximum phosphate uptake rate

PC_b:
  Symbol: PC_b
  Default: 0.6
  Description: Shape parameter for PC

VN_b:
  Symbol: VN_b
  Default: 0.6
  Description: Shape parameter for VNH4 and VNO3

VP_b:
  Symbol: VP_b
  Default: 0.6
  Description: Shape parameter for VPO4

KsatNH4:
  Symbol: K^{sat}_{NH4}
  Default: 0.005
  Unit: mmol N/m^3
  Description: Half-saturation constant for NH4

KsatNO3:
  Symbol: K^{sat}_{NO3}
  Default: 0.010
  Unit: mmol N/m^3
  Description: Half-saturation constant for NO3

KsatPO4:
  Symbol: K^{sat}_{PO4}
  Default: 0.003
  Unit: mmol P/m^3
  Description: Half-saturation constant for PO4

Nqmax:
  Symbol: Nqmax
  Default: 0.12
  Unit: mmol N/mmol C
  Description: Maximum N quota in cell

Nqmin:
  Symbol: Nqmin
  Default: 0.05
  Unit: mmol N/mmol C
  Description: Minimum N quota in cell

Pqmax:
  Symbol: Pqmax
  Default: 0.01
  Unit: mmol P/mmol C
  Description: Maximum P quota in cell

Pqmin:
  Symbol: Pqmax
  Default: 0.004
  Unit: mmol P/mmol C
  Description: Minimum P quota in cell

R_NC:
  Symbol: R_{NC}
  Default: 16/106
  Unit: mmol N/mmol C
  Description: N:C ratio in function biomass

R_PC:
  Symbol: R_{PC}
  Default: 1/106
  Unit: mmol P/mmol C
  Description: P:C ratio in function biomass

k_mtb:
  Symbol: kmtb_{max}
  Default: 3.5e-5
  Unit: s^-1
  Description: Maximum metabolic rate

k_mtb_b:
  Symbol: k_mtb_b
  Default: 0.25
  Description: Shape parameter for k_mtb

respir_a:
  Symbol: respir_a
  Default: 1.2e-6
  Unit: s^-1
  Description: Maximum respiration rate

respir_b:
  Symbol: respir_b
  Default: 0.6
  Description: Shape parameter for respir_a

Chl2N:
  Symbol: chl:N
  Default: 3.0
  Unit: mg chl/mmol N
  Description: Maximum Chl:N in cell

P_dvid:
  Symbol: P_{dvid}
  Default: 5.0e-5
  Unit: s^-1
  Description: Probability of division per second

dvid_stp:
  Symbol: stp1_D
  Default: 6.0
  Description: Steepness of division function

dvid_reg:
  Symbol: reg1_D
  Default: 1.9
  Description: Regulation of division function

dvid_stp2:
  Symbol: stp2_D
  Default: 2.0
  Description: Steepness of division function

dvid_reg2:
  Symbol: reg2_D
  Default: 12.0
  Description: Regulation of division function

P_graz:
  Symbol: P_{graz}
  Default: 0.0
  Unit: s^-1
  Description: Probability of grazing per second
```

--------------------------------

### PlanktonIndividuals.jl vs. Other Frameworks

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/joss/paper.md

Compares PlanktonIndividuals.jl with other agent-based modeling frameworks like Netlogo and Agents.jl, as well as Lagrangian simulation packages like oceanParcels and IndividualDisplacements.jl. It highlights PlanktonIndividuals.jl's focus on detailed phytoplankton physiology and biogeochemistry and its unique combination of Eulerian and Lagrangian perspectives.

```markdown
There are many software packages for individual-based modeling, both in Julia and other programming languages, aimed at different purposes. For example, `Netlogo` [@NetLogo1999] and `Agents.jl` [@Agents2022; @Agents2019] provide generic agent-based frameworks -- with a focus on generality but lack of physical and biogeochemical equations, which are the core of `PlanktonIndividuals.jl`. In contrast, `oceanParcels` [@gmd-10-4175-2017] and `IndividualDisplacements.jl` [@Forget2021] focus on the Lagrangian simulation of individual displacements in the ocean and climate system. However, these packages mainly focus on simulation of passive particles that do not feed back on gridded variables. In addition, they do not include detailed equations of phytoplankton physiology and biochemistry.

Our package is unique in the way that it is tailored to the analysis of marine ecosystems across a wide range of scales using HPC systems. To this end, `PlanktonIndividuals.jl` provides a comprehensive description of phytoplankton physiology and biogeochemistry, written in a fast language, Julia, and with GPU support. It further innovates in combining the Eulerian and Lagrangian perspectives. Plankton individuals (Lagrangian) indeed have two-way interactions with gridded nutrient fields (Eulerian) that are advected by the same flow fields (in one-, two-, or three-dimensions) in our package.
```

--------------------------------

### PlanktonIndividuals.jl Parameters Documentation

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/library.md

This section provides documentation for the Parameters module within the PlanktonIndividuals.jl library. It includes public API documentation for the module and its associated pages, covering parameter definitions and updates.

```APIDOC
Modules = [PlanktonIndividuals.Parameters]
Private = false
Pages   = [
    "Parameters/Parameters.jl",
    "Parameters/param_default.jl",
    "Parameters/param_update.jl"
]
```

--------------------------------

### PlanktonIndividuals.jl Overview

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/joss/paper.md

This section provides a high-level overview of the PlanktonIndividuals.jl package, its purpose, and its unique features compared to other modeling frameworks. It highlights the use of individual-based modeling, GPU acceleration, and the combination of Eulerian and Lagrangian approaches.

```markdown
Project: /juliaocean/planktonindividuals.jl

# Statement of need
Phytoplankton models, like those incorporated in ecological and biogeochemical models, are essential tools to explore and understand phytoplankton life cycles, interactions between species, population dynamics, and community structures in various water bodies [e.g., lakes, coastal waters, and open ocean, @follows2007emergent; @geider1997dynamic]. Individual-based / Lagrangian models differ from Eulerian models in the way they represent heterogeneous populations like cells of different sizes, nutrient quotas, and life cycle stages [@hellweger2016advancing; @hellweger2014biogeographic; @clark2011individual]. 

The unique power of individual-based modeling lies in the ability to track the position, biomass, and physiological state of individual cells or plankton patches, as they move through space over time. Eulerian models in turn can only track the density of plankton biomass in “well-mixed” grids of simulated water bodies. Furthermore, individual-based models are able to introduce randomness in individuals which allows stochastic processes (e.g., cell division, grazing, and death) to reproduce the diversity found in real ecosystems.

Due to computational limitations, previous microbial individual-based models could only simulate a limited number of individuals, with each individual representing cell populations rather than individual cells [@hellweger2016advancing]. In order to overcome this obstacle, `PlanktonIndividuals.jl` exploits the power of GPU which was first developed for video rendering but now offer extremely efficient, highly parallelized computing power. With GPU support, the simulations in `PlanktonIndividuals.jl` are sped up over 50 times compared with CPU simulations.

There are many software packages for individual-based modeling, both in Julia and other programming languages, aimed at different purposes. For example, `Netlogo` [@NetLogo1999] and `Agents.jl` [@Agents2022; @Agents2019] provide generic agent-based frameworks -- with a focus on generality but lack of physical and biogeochemical equations, which are the core of `PlanktonIndividuals.jl`. In contrast, `oceanParcels` [@gmd-10-4175-2017] and `IndividualDisplacements.jl` [@Forget2021] focus on the Lagrangian simulation of individual displacements in the ocean and climate system. However, these packages mainly focus on simulation of passive particles that do not feed back on gridded variables. In addition, they do not include detailed equations of phytoplankton physiology and biochemistry.

Our package is unique in the way that it is tailored to the analysis of marine ecosystems across a wide range of scales using HPC systems. To this end, `PlanktonIndividuals.jl` provides a comprehensive description of phytoplankton physiology and biogeochemistry, written in a fast language, Julia, and with GPU support. It further innovates in combining the Eulerian and Lagrangian perspectives. Plankton individuals (Lagrangian) indeed have two-way interactions with gridded nutrient fields (Eulerian) that are advected by the same flow fields (in one-, two-, or three-dimensions) in our package.

To illustrate the two representations of advective processes in the model (Eulerian + Lagrangian), we performed a one-year simulation of a passive tracer, initialized to a concentration of 1 below 50m depth and 0 above 50m depth, along with 512 particles moving in three dimensions (\autoref{fig:3D}).

![Model results of a three-dimensional setup. The map shows the concentration of a passive tracer. White dots represent the individuals with their trajectories shown in white lines. \label{fig:3D}](global_ocean_3D_example.png)

Further development plans include implementation of macro-molecular model [@Inomura2020] and support for distributed parallelism with CUDA-aware MPI.

# Acknowledgements

We acknowledge contributions from the open source community at large, the paper reviewers and journal editor, as well as developers of `Julia` and its packages upon which `PlanktonIndividuals.jl` crucially depends. 

Funding that supported this work was provided by the Simons Collaboration on Computational Biogeochemical Modeling of Marine Ecosystems (CBIOMES) (grant no. 549931) and Simons Collaboration on Ocean Processes and Ecology (SCOPE) (grant no. 329108). GF was additionally funded by National Aeronautics and Space Administration award 19-PO19-0001 (NNH19ZDA001N-PO) and 19-MAP19-0018 (NNH19ZDA001N-MAP).

# References

```

--------------------------------

### PlanktonIndividuals.jl Simulation Documentation

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/library.md

This section provides documentation for the Simulation module within the PlanktonIndividuals.jl library. It includes public API documentation for the module and its associated pages, covering simulation execution, updates, and utilities.

```APIDOC
Modules = [PlanktonIndividuals.Simulation]
Private = false
Pages   =[
    "Simulation/Simulation.jl",
    "Simulation/simulations.jl",
    "Simulation/update.jl",
    "Simulation/utils.jl"
]
```

--------------------------------

### PlanktonIndividuals.jl GPU Acceleration

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/joss/paper.md

Details the significant performance improvements achieved by PlanktonIndividuals.jl through the use of GPU acceleration. Simulations are reported to be over 50 times faster compared to CPU-based simulations.

```markdown
Due to computational limitations, previous microbial individual-based models could only simulate a limited number of individuals, with each individual representing cell populations rather than individual cells [@hellweger2016advancing]. In order to overcome this obstacle, `PlanktonIndividuals.jl` exploits the power of GPU which was first developed for video rendering but now offer extremely efficient, highly parallelized computing power. With GPU support, the simulations in `PlanktonIndividuals.jl` are sped up over 50 times compared with CPU simulations.
```

--------------------------------

### NamedTuple for Nutrient Initial Conditions

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/model_setup.md

Defines the structure for initial nutrient conditions using a NamedTuple, including base concentrations and optional random noise. This is used by the `generate_nutrients` function.

```julia
initial_condition = (DIC=20.0, NH4=0.2, NO3=0.5, PO4=0.03, DOC=1.0, DON=0.1, DOP=0.05, POC=0.0, PON=0.0,POP=0.0);
rand_noise = (DIC=0.0, NH4=0.0, NO3=0.0, PO4=0.0, DOC=0.0, DON=0.0, DOP=0.0, POC=0.0, PON=0.0,POP=0.0);
nut_initial = (initial_condition = initial_condition, rand_noise = rand_noise)
```

--------------------------------

### PlanktonIndividuals.jl Output Documentation

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/library.md

This section provides documentation for the Output module within the PlanktonIndividuals.jl library. It includes public API documentation for the module and its associated pages, covering output writing mechanisms.

```APIDOC
Modules = [PlanktonIndividuals.Output]
Private = false
Pages   =[
    "Output/Output.jl",
    "Output/output_writers.jl"
]
```

--------------------------------

### Simulation Domain and Input Fields

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/joss/paper.md

The model supports simulations in zero-dimensional (lab-like) to three-dimensional domains. It requires external input fields for velocity, temperature, and photosynthetically active radiation (PAR). These fields can be sourced from various fluid dynamic models or observational data.

```Julia
# Example of loading external data (conceptual):
# velocity_data = load_netcdf("velocity.nc")
# temperature_data = load_netcdf("temperature.nc")
# par_data = load_netcdf("par.nc")

# Setting up simulation domain:
# sim = Simulation(domain_size=(10, 10, 10), time_step=dt)
# set_velocity_field!(sim, velocity_data)
# set_temperature_field!(sim, temperature_data)
# set_par_field!(sim, par_data)
```

--------------------------------

### Available Plankton Diagnostics

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/model_run.md

Lists the available diagnostics for individual plankton, including counts (number, grazed, died, divided), physiological rates (photosynthesis, biosynthesis, uptake, respiration, exudation), and biomass/pool sizes (functional biomass, Carbon, Nitrogen, Phosphorus pools, Chlorophyll a).

```julia
plankton = (:num,  # number of individuals
              :graz, # number of grazed individuals
              :mort, # number of died individuals
              :dvid, # number of divided individuals
              :PS,   # photosynthesis rate
              :BS,   # biosynthesis rate
              :VDOC, # DOC uptake rate
              :VHN4, # NH4 uptake rate
              :VNO3, # NO3 uptake rate
              :VPO4, # PO4 uptake rate
              :resp, # respiration rate
              :exu,  # exudation rate
              :Bm,   # functional biomass
              :Cq,   # Carbon pool
              :Nq,   # Nitrogen pool
              :Pq,   # Phosphorus pool
              :Chl   # Chla
             )
```

--------------------------------

### PlanktonIndividuals.jl Grids Documentation

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/library.md

This section provides documentation for the Grids module within the PlanktonIndividuals.jl library. It includes public API documentation for the module and its associated pages, covering different grid types.

```APIDOC
Modules = [PlanktonIndividuals.Grids]
Private = false
Pages   = [
    "Grids/Grids.jl",
    "Grids/regular_rectilinear_grid.jl",
    "Grids/regular_lat_lon_grid.jl",
    "Grids/vertically_stretched_lat_lon_grid.jl"
]
```

--------------------------------

### LatLonGrid Construction

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/model_setup.md

Constructs a Latitude-Longitude grid for the model. Requires specifying the grid size and the start/end points for latitude, longitude, and depth (z). Supports constant grid spacing.

```julia
grid = LatLonGrid(size=(360,160,20), lat = (-80,80), lon = (-180,180), z = (0,-200))
```

--------------------------------

### PlanktonIndividuals.jl Diagnostics Documentation

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/library.md

This section provides documentation for the Diagnostics module within the PlanktonIndividuals.jl library. It includes public API documentation for the module and its associated pages, covering diagnostic calculations and structures.

```APIDOC
Modules = [PlanktonIndividuals.Diagnostics]
Private = false
Pages   = [
    "Diagnostics/Diagnostics.jl",
    "Diagnostics/diagnostics_struct.jl"
]
```

--------------------------------

### PlanktonIndividuals.jl Eulerian and Lagrangian Integration

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/joss/paper.md

Explains the integrated approach of PlanktonIndividuals.jl, which combines Eulerian (gridded fields) and Lagrangian (individual particles) perspectives. This allows for two-way interactions between plankton individuals and their environment.

```markdown
To illustrate the two representations of advective processes in the model (Eulerian + Lagrangian), we performed a one-year simulation of a passive tracer, initialized to a concentration of 1 below 50m depth and 0 above 50m depth, along with 512 particles moving in three dimensions (\autoref{fig:3D}).
```

--------------------------------

### Available Tracer Diagnostics

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/model_run.md

Lists the available diagnostics for tracers, including photosynthetically active radiation (PAR), dissolved inorganic carbon (DIC), and various nutrient and organic carbon/nitrogen/phosphorus compounds.

```julia
tracer = (:PAR, # photosynthetically active radiation
          :DIC, # dissolved inorganic carbon
          :NH4, # ammonia
          :NO3, # nitrate
          :PO4, # phosphate
          :DOC, # dissolved organic carbon
          :DON, # dissolved organic nitrogen
          :DOP, # dissolved organic phosphorus
          :POC, # particulate organic carbon
          :PON, # particulate organic nitrogen
          :POP  # particulate organic phosphorus
         )
```

--------------------------------

### PlanktonIndividuals.jl Architectures Documentation

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/library.md

This section provides documentation for the Architectures module within the PlanktonIndividuals.jl library. It includes public API documentation for the module and its associated pages.

```APIDOC
Modules = [PlanktonIndividuals.Architectures]
Private = false
Pages   = [ "Architectures.jl"]
```

--------------------------------

### PlanktonIndividuals.jl Fields Documentation

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/library.md

This section provides documentation for the Fields module within the PlanktonIndividuals.jl library. It includes public API documentation for the module and its associated pages, covering field definitions and boundary conditions.

```APIDOC
Modules = [PlanktonIndividuals.Fields]
Private = false
Pages   =[
    "Fields/Fields.jl",
    "Fields/boundary_conditions.jl"
]
```

--------------------------------

### Reserve Update Equations

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/phyto_equations.md

Updates the carbon (Cq), Nitrogen (Nq), and Phosphorus (Pq) reserves based on photosynthesis (PS) and nutrient uptake rates (VNH4, VNO3, VPO4) over a time step (ΔT).

```math
Cq = Cq+PS \cdot \Delta T 
Nq = Nq+(VNO3+VNH4) \cdot \Delta T 
Pq = Pq+VPO4 \cdot \Delta T
```

--------------------------------

### PlanktonIndividuals.jl Model Documentation

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/library.md

This section provides documentation for the Model module within the PlanktonIndividuals.jl library. It includes public API documentation for the module and its associated pages, covering model definitions and implementations.

```APIDOC
Modules = [PlanktonIndividuals, PlanktonIndividuals.Model]
Private = false
Pages   =[
    "PlanktonIndividuals.jl",
    "Model/Model.jl",
    "Model/models.jl"
]
```

--------------------------------

### Adder+Timer Cell Division Strategy

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/phyto_equations.md

Defines the cell division probability function (S_dvid) for the Adder+Timer strategy, combining the difference between current and initial cell size (Sz - iSz) and clock time (t) dependencies multiplicatively.

```math
S_{dvid} = (tanh(stp1_D * (Sz - iSz - reg1_D)) + 1.0) * (tanh(stp2_D * (t - reg2_D)) + 1.0)
```

--------------------------------

### PlanktonIndividuals.jl Biogeochemistry Documentation

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/library.md

This section provides documentation for the Biogeochemistry module within the PlanktonIndividuals.jl library. It includes public API documentation for the module and its associated pages, covering biogeochemical processes and nutrient fields.

```APIDOC
Modules = [PlanktonIndividuals.Biogeochemistry]
Private = false
Pages   = [
    "Biogeochemistry/Biogeochemistry.jl",
    "Biogeochemistry/nutrient_fields.jl"
]
```

--------------------------------

### Sizer+Timer Cell Division Strategy

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/phyto_equations.md

Defines the cell division probability function (S_dvid) for the Sizer+Timer strategy, combining cell size (Sz) and clock time (t) dependencies multiplicatively.

```math
S_{dvid} = (tanh(stp1_D * (Sz - reg1_D)) + 1.0) * (tanh(stp2_D * (t - reg2_D)) + 1.0)
```

--------------------------------

### Potential Biosynthesis Rates

Source: https://github.com/juliaocean/planktonindividuals.jl/blob/master/docs/src/phyto_equations.md

Calculates the potential biosynthesis rates for Carbon (BS_C), Nitrogen (BS_N), and Phosphorus (BS_P) based on the updated nutrient reserves and a metabolic rate (k_mtb) that is scaled by cell size (Sz).

```math
BS_C = Cq \cdot k_{mtb} 
BS_N = Nq/R_{NC} \cdot k_{mtb} 
BS_P = Pq/R_{PC} \cdot k_{mtb}
```