.github/workflows/CI.yml

@@ -11,6 +11,12 @@ on:
     branches:
       - main
     tags: '*'
+
+# needed to allow julia-actions/cache to delete old caches that it has created
+permissions:
+  actions: write
+  contents: read
+
 jobs:
   test:
     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
@@ -26,21 +32,12 @@ jobs:
         arch:
           - x64
     steps:
-      - uses: actions/checkout@v3
-      - uses: julia-actions/setup-julia@v1
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: actions/cache@v3
-        env:
-          cache-name: cache-artifacts
-        with:
-          path: ~/.julia/artifacts
-          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-test-${{ env.cache-name }}-
-            ${{ runner.os }}-test-
-            ${{ runner.os }}-
+      - uses: julia-actions/cache@v2
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1

.github/workflows/documentation.yml

@@ -11,14 +11,14 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@latest
         with:
-          version: '1.6'
+          version: 'lts'
       - name: Install dependencies
         run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
       - name: Build and deploy
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
-        run: julia --project=docs/ docs/make.jl
+        run: julia --project=docs/ docs/make.jl

Project.toml

@@ -1,9 +1,10 @@
 name = "PALEOboxes"
 uuid = "804b410e-d900-4b2a-9ecd-f5a06d4c1fd4"
 authors = ["Stuart Daines <stuart.daines@gmail.com>"]
-version = "0.21.16"
+version = "0.22.4"
 
 [deps]
+Atomix = "a9b6321e-bd34-4604-b9c9-b65b8de01458"
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
@@ -16,12 +17,12 @@ Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 MAT = "23992714-dd62-5051-b70f-ba57cb901cac"
 NCDatasets = "85f8d34a-cbdd-5861-8df4-14fed0d494ab"
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
+PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
 Preferences = "21216c6a-2e73-6563-6e65-726566657250"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 SIMD = "fdea26ae-647d-5447-a871-4b548cad5224"
 SLEEF_jll = "63e82ce6-3d80-5af4-a84c-484b71ab98bb"
-PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 StructArrays = "09ab397b-f2b6-538f-b94a-2f83cf4a842a"
@@ -30,26 +31,27 @@ TimerOutputs = "a759f4b9-e2f1-59dc-863e-4aeb61b1ea8f"
 YAML = "ddb6d928-2868-570f-bddf-ab3f9cf99eb6"
 
 [compat]
+Atomix = "0.1, 1.0"
 BenchmarkTools = "1.0"
 DataFrames = "1.1"
 DocStringExtensions = "0.8, 0.9"
-Documenter = "0.27"
+Documenter = "1"
 Graphs = "1.4"
 Infiltrator = "1.0"
-Interpolations = "0.13, 0.14"
+Interpolations = "0.13, 0.14, 0.15"
 MAT = "0.10"
-NCDatasets = "0.12"
+NCDatasets = "0.12, 0.13, 0.14"
 OrderedCollections = "1.4"
+PrecompileTools = "1.0"
 Preferences = "1.2"
 Revise = "3.1"
 SIMD = "3.3"
 SLEEF_jll = "3.4"
-PrecompileTools = "1.0"
 StaticArrays = "1.4"
-StructArrays = "0.6"
+StructArrays = "0.6, 0.7"
 TestEnv = "1.0"
 TimerOutputs = "0.5"
-YAML = "0.4.7"
+YAML = "0.4.7 - 0.4.12"
 julia = "1.6"
 
 [extras]

docs/Project.toml

@@ -6,8 +6,8 @@ PALEOboxes = "804b410e-d900-4b2a-9ecd-f5a06d4c1fd4"
 Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 
 [compat]
-Documenter = "0.27"
-DocumenterCitations = "0.2"
+Documenter = "1"
+DocumenterCitations = "1"
 Revise = "3.1"
 julia = "1.6"
 

docs/make.jl

@@ -4,9 +4,13 @@ import PALEOboxes
 
 using DocumenterCitations
 
-bib = CitationBibliography(joinpath(@__DIR__, "src/paleo_references.bib"))
+bib = CitationBibliography(
+        joinpath(@__DIR__, "src/paleo_references.bib"),
+        style=:authoryear,
+    )
 
-makedocs(bib, sitename="PALEOboxes Documentation", 
+makedocs(;
+        sitename="PALEOboxes Documentation", 
         pages = [
             "Home" => "index.md",
             "Design" => [
@@ -25,11 +29,12 @@ makedocs(bib, sitename="PALEOboxes Documentation",
         format = Documenter.HTML(
             prettyurls = get(ENV, "CI", nothing) == "true"
         ),
+        plugins = [bib],
         # repo = "https://github.com/PALEOtoolkit/PALEOboxes.jl/blob/master/{path}#{line}"
     )
 
 @info "Local html documentation is available at $(joinpath(@__DIR__, "build/index.html"))"
 
 deploydocs(
     repo = "github.com/PALEOtoolkit/PALEOboxes.jl.git",
-)
+)

docs/src/CreateInitializeLoop.md

@@ -51,7 +51,7 @@ The custom Vector of [`CellRange`](@ref)s should then be supplied to
 
 ### Multithreaded models
 To use with a multithreaded solver eg for a spatially tiled model:
-- Set `threadsafe=true` when calling [`create_modeldata`](@ref). The subsequent call to [`allocate_variables!`](@ref) will then allocate Julia `Threads.Atomic` variables for PALEO Variables with attribute `atomic: = true` (usually scalar accumulator variables for totals etc).
+- Set the global parameter `threadsafe=true` in the YAML file before calling [`create_model_from_config`](@ref). This is used by Reactions that require special handling eg atomic operations to maintain thread safety (usually those with scalar accumulator variables for totals etc).
 - Supply a `method_barrier` implementing a thread barrier function to [`initialize_reactiondata!`](@ref). Reactions are sorted into groups, where each group has no dependencies and later groups depend on earlier ones. The `method_barrier` will be inserted between these groups of independent Reactions.
 
 ### Automatic differentiation

docs/src/DomainsVariablesFields.md

@@ -21,15 +21,38 @@ CurrentModule = PALEOboxes
 Domain
 ```
 
+### Dimensions and Coordinates
+
+PALEO approximately follows the [Common Data Model](https://docs.unidata.ucar.edu/netcdf-c/current/netcdf_data_model.html) used by NetCDF and other geoscience data formats.
+
+Domains provide named dimensions, to which coordinate variables may be attached (these are just normal PALEO variables).
+- Domain spatial dimensions are provided by the Domain grid (see `Grids`)
+- Additional Domain data dimensions (eg a wavelength grid) may be set by Reactions (see [`set_data_dimension!`](@ref)).
+
+```@meta
+CurrentModule = PALEOboxes
+```
+```@docs
+NamedDimension
+get_dimensions
+get_dimension
+get_coordinates
+set_coordinates!
+```
+
 ### Grids
 ```@meta
 CurrentModule = PALEOboxes
 ```
 ```@docs
 AbstractMesh
 
+Grids.available_spaces
+has_internal_cartesian
 internal_size
 cartesian_size
+Grids.cartesian_to_internal
+Grids.internal_to_cartesian
 ```
 ```@meta
 CurrentModule = PALEOboxes.Grids
@@ -61,23 +84,6 @@ subdomain_view
 subdomain_indices
 ```
 
-#### Regions, Dimensions and Coordinates
-```@meta
-CurrentModule = PALEOboxes.Grids
-```
-```@docs
-get_region
-```
-
-Grids may define name dimensions and attach coordinates for the convenience of output visualisation. Any coordinate information required by Reactions should be supplied as Variables.
-```@meta
-CurrentModule = PALEOboxes
-```
-```@docs
-NamedDimension
-FixedCoord
-```
-
 ## Variables
 
 ```@meta
@@ -148,7 +154,6 @@ Examples:
 ```@docs
 Field
 get_field
-wrap_field
 ```
 
 ## Spaces
@@ -177,8 +182,6 @@ allocate_values
 check_values
 zero_values!
 dof_values
-get_values_output
-
 
 init_values!
 copyfieldto!

docs/src/Reaction API.md

@@ -23,7 +23,6 @@ Parameter
 VecParameter
 VecVecParameter
 ParametersTuple
-add_par
 setvalue!
 ```
 
@@ -74,10 +73,10 @@ AbstractVarList
 VarList_single
 VarList_namedtuple
 VarList_tuple
+VarList_ttuple
 VarList_vector
 VarList_vvector
 VarList_nothing
-VarList_tuple_nothing
 ```
 
 ### Implementing method functions
@@ -151,6 +150,38 @@ In rare cases where it is necessary to operate on a Vector representing a quanti
         return nothing
     end
 
+#### Writing automatic-differentiation-compatible code
+
+Stiff systems of equations (with a wide range of timescales) will require a
+solver that uses Jacobian information (either calculated numerically or by automatic differentiation).
+
+To be numerically efficient, this means that the Jacobian needs to exist mathematically, so any reaction rates
+should change continuously. Any discontinuous steps (eg a rate that suddenly increases to a finite value at a threshold)
+should be smoothed out, eg using the [`smoothstepcubic`](@ref) function or ideally by reformulating the physical model
+in such a way that discontinuities are avoided.
+
+For large models, a sparse Jacobian may be required, where the sparsity pattern is generated by tracing the code with the
+model variables set eg to their initial values.  Conditional logic (if-then-else blocks or elseif) may then cause this tracing to fail
+(omit some terms from the Jacobian) if the conditional branch taken sets some rates to zero losing dependency information. 
+Workaround is to use [`zero_ad`](@ref) to generate a zero value that retains variable dependency information.  NB: the `max` and `min`
+Julia functions *are* safe to use with sparsity tracing.
+
+It is sometimes desirable to omit terms from the Jacobian, eg an insignificantly small term that would greatly reduce the
+Jacobian sparsity. This can be accomplished by using the [`value_ad`](@ref) function to drop automatic-differentiation information
+and retain only the value.
+```@docs
+smoothstepcubic
+zero_ad
+value_ad
+```
+
+#### Writing thread-safe code
+
+Reactions that accumulate per-cell quantities into a scalar variable (eg to calculate Domain totals) and are intended for use in
+large models that use a multithreaded solver with tiled Domains should use `atomic_add!`:
+```@docs
+atomic_add!
+```
 
 #### Optimising loops over cells using explicit SIMD instructions
 Reactions with simple loops over `cellindices` that implement time-consuming per-cell calculations 
@@ -184,6 +215,7 @@ add_method_do_totals_default!
 ```@docs
 RateStoich
 create_ratestoich_method
+add_rate_stoichiometry!
 ```
 
 ## Internal details of Variable arrays accessor generation

docs/src/Solver API.md

@@ -13,6 +13,7 @@ CurrentModule = PALEOboxes
 ```
 ```@docs
 create_model_from_config(config_file::AbstractString, configmodel::AbstractString)
+check_variable_links
 create_modeldata(model::Model, vectype::DataType=Array{Float64,1})
 ModelData
 add_arrays_data!
@@ -38,6 +39,11 @@ copyto!(dest::AbstractVector, src::VariableAggregator; dof::Int=1)
 VariableAggregatorNamed
 ```
 
+Aggregated collections of a subset of Parameters as a flattened Vector (eg for sensitivity studies) is provided by [`ParameterAggregator`](@ref):
+```@docs
+ParameterAggregator
+```
+
 ## Defining CellRanges
 ```@meta
 CurrentModule = PALEOboxes
@@ -109,5 +115,4 @@ CurrentModule = PALEOboxes
 ```@docs
 set_data!
 get_data
-get_data_output
 ```