From 382b4dda563e85c810b9c1ca91149c24eb5d6cac Mon Sep 17 00:00:00 2001 From: Benoit Pasquier <4486578+briochemc@users.noreply.github.com> Date: Fri, 10 Dec 2021 16:50:53 +1100 Subject: [PATCH] JOSS paper (#87) * JOSS paper * Fix tests (updated WOA API) * Fix SciML API (no Val{:jac}) * Fix #88 --- Project.toml | 6 +- docs/lit/howtos/1_parameters.jl | 5 + docs/lit/howtos/2_plot.jl | 4 + docs/lit/howtos/3_cruiseplot.jl | 4 + docs/lit/howtos/4_fluxes.jl | 5 + docs/lit/tutorials/1_ideal_age.jl | 5 +- docs/lit/tutorials/2_radiocarbon.jl | 5 + docs/lit/tutorials/3_Pmodel.jl | 5 + docs/lit/tutorials/4_dustmodel.jl | 5 + docs/lit/tutorials/5_river_discharge.jl | 5 + docs/lit/tutorials/6_groundwater_discharge.jl | 5 + docs/paper.bib | 113 +++++++++++++----- docs/paper.md | 69 +++++------ src/AIBECS.jl | 2 + src/Parameters.jl | 4 +- src/overload_solve.jl | 19 ++- test/bgc_functions.jl | 6 +- test/cost_functions.jl | 3 +- test/derivatives.jl | 8 +- test/runtests.jl | 2 +- test/solvers.jl | 2 +- 21 files changed, 190 insertions(+), 92 deletions(-) diff --git a/Project.toml b/Project.toml index 07fa3f08..0ca70e33 100644 --- a/Project.toml +++ b/Project.toml @@ -1,7 +1,7 @@ name = "AIBECS" uuid = "ace601d6-714c-11e9-04e5-89b7fad23838" authors = ["Benoit Pasquier "] -version = "0.11.0" +version = "0.11.1" [deps] Bijectors = "76274a88-744f-5084-9051-94815aaf08c4" @@ -9,7 +9,6 @@ CodecZlib = "944b1d66-785c-5afd-91f1-9de20f533193" DataDeps = "124859b0-ceae-595e-8997-d05f6a7a8dfe" DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0" Dates = "ade2ca70-3891-5945-98fb-dc099432e06a" -DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e" Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7" Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f" Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6" @@ -27,6 +26,7 @@ OceanGrids = "cfe838f4-859f-11e9-2ea1-df7d4e7c3537" Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7" RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01" Reexport = "189a3867-3050-52da-a836-e630ba90ab69" +SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462" Shapefile = "8e980c4a-a4fe-5da2-b3a7-4b4b0353a2f4" SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf" StringDistances = "88034a9c-02f8-509d-84a9-84ec65e18404" @@ -40,7 +40,6 @@ Bijectors = "0.8, 0.9" CodecZlib = "0.7" DataDeps = "0.7" DataFrames = "0.20, 0.21, 0.22, 1.0" -DiffEqBase = "6" Distances = "0.9, 0.10" Distributions = "0.23, 0.24, 0.25" FieldMetadata = "0.3" @@ -55,6 +54,7 @@ NearestNeighbors = "0.4" OceanGrids = "0.4" RecipesBase = "1" Reexport = "0.2, 1.0" +SciMLBase = "1" Shapefile = "0.6, 0.7" StringDistances = "0.10, 0.11" UnPack = "1" diff --git a/docs/lit/howtos/1_parameters.jl b/docs/lit/howtos/1_parameters.jl index f310a531..02a019d0 100644 --- a/docs/lit/howtos/1_parameters.jl +++ b/docs/lit/howtos/1_parameters.jl @@ -5,6 +5,11 @@ #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/notebooks/1_parameters.ipynb) #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/notebooks/1_parameters.ipynb) +#md # !!! note +#md # All the AIBECS tutorials and how-to guides are available as Jupyter notebooks. +#md # You can view them with [nbviewer](https://nbviewer.jupyter.org/)or execute them online with [binder](https://mybinder.org/) by clicking on the badges above! +#md # (Note that binder can be slow to launch and its memory caps can be a problem when running.) + # Here we will describe the AIBECS interface. # This guide will take you through some examples of setting up model parameters. diff --git a/docs/lit/howtos/2_plot.jl b/docs/lit/howtos/2_plot.jl index afc9b09c..151cd020 100644 --- a/docs/lit/howtos/2_plot.jl +++ b/docs/lit/howtos/2_plot.jl @@ -6,6 +6,10 @@ #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/notebooks/2_plot.ipynb) #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/notebooks/2_plot.ipynb) +#md # !!! note +#md # All the AIBECS tutorials and how-to guides are available as Jupyter notebooks. +#md # You can view them with [nbviewer](https://nbviewer.jupyter.org/)or execute them online with [binder](https://mybinder.org/) by clicking on the badges above! +#md # (Note that binder can be slow to launch and its memory caps can be a problem when running.) # This guide is organized as follows # - [Horizontal maps](@ref horizontal-plots) diff --git a/docs/lit/howtos/3_cruiseplot.jl b/docs/lit/howtos/3_cruiseplot.jl index 54b6e1ae..3b8230a8 100644 --- a/docs/lit/howtos/3_cruiseplot.jl +++ b/docs/lit/howtos/3_cruiseplot.jl @@ -5,6 +5,10 @@ #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/notebooks/3_cruiseplot.ipynb) #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/notebooks/3_cruiseplot.ipynb) +#md # !!! note +#md # All the AIBECS tutorials and how-to guides are available as Jupyter notebooks. +#md # You can view them with [nbviewer](https://nbviewer.jupyter.org/)or execute them online with [binder](https://mybinder.org/) by clicking on the badges above! +#md # (Note that binder can be slow to launch and its memory caps can be a problem when running.) # This guide follows the [basic plotting guide](@ref plots) and its goal is to plot data related to oceanographic observations from cruise expeditions. # In this walkthrough, we will diff --git a/docs/lit/howtos/4_fluxes.jl b/docs/lit/howtos/4_fluxes.jl index fe991fc2..42b449a0 100644 --- a/docs/lit/howtos/4_fluxes.jl +++ b/docs/lit/howtos/4_fluxes.jl @@ -5,6 +5,11 @@ #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/notebooks/4_fluxes.ipynb) #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/notebooks/4_fluxes.ipynb) +#md # !!! note +#md # All the AIBECS tutorials and how-to guides are available as Jupyter notebooks. +#md # You can view them with [nbviewer](https://nbviewer.jupyter.org/)or execute them online with [binder](https://mybinder.org/) by clicking on the badges above! +#md # (Note that binder can be slow to launch and its memory caps can be a problem when running.) + # This will take you through the process of extracting flux information from a given transport operator. # It is split into 3 parts # 1. [Figure out the stencil of the operator](@ref operatorstencil) diff --git a/docs/lit/tutorials/1_ideal_age.jl b/docs/lit/tutorials/1_ideal_age.jl index 5bd1a825..7cba4fe1 100644 --- a/docs/lit/tutorials/1_ideal_age.jl +++ b/docs/lit/tutorials/1_ideal_age.jl @@ -8,7 +8,8 @@ #md # !!! note #md # All the AIBECS tutorials and how-to guides are available as Jupyter notebooks. -#md # You can execute them online with [binder](https://mybinder.org/) or just view them with [nbviewer](https://nbviewer.jupyter.org/) by clicking on the badges above! +#md # You can view them with [nbviewer](https://nbviewer.jupyter.org/)or execute them online with [binder](https://mybinder.org/) by clicking on the badges above! +#md # (Note that binder can be slow to launch and its memory caps can be a problem when running.) # The tracer equation for the ideal age is # @@ -86,7 +87,7 @@ F = AIBECSFunction(TOCIM2, G) # Now that `F` and `p` are defined, we are going to solve for the steady-state. # But first, we must create a `SteadyStateProblem` object that contains `F`, `p`, and an initial guess `x_init` for the age. -# (`SteadyStateProblem` comes from [DiffEqBase](https://github.com/JuliaDiffEq/DiffEqBase.jl).) +# (`SteadyStateProblem` comes from [SciMLBase](https://github.com/JuliaDiffEq/SciMLBase.jl).) # Let's make a vector of 0's for our initial guess. diff --git a/docs/lit/tutorials/2_radiocarbon.jl b/docs/lit/tutorials/2_radiocarbon.jl index 2aa4ff3d..b639db9e 100644 --- a/docs/lit/tutorials/2_radiocarbon.jl +++ b/docs/lit/tutorials/2_radiocarbon.jl @@ -6,6 +6,11 @@ #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/notebooks/2_radiocarbon.ipynb) #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/notebooks/2_radiocarbon.ipynb) +#md # !!! note +#md # All the AIBECS tutorials and how-to guides are available as Jupyter notebooks. +#md # You can view them with [nbviewer](https://nbviewer.jupyter.org/)or execute them online with [binder](https://mybinder.org/) by clicking on the badges above! +#md # (Note that binder can be slow to launch and its memory caps can be a problem when running.) + # In this tutorial, we will simulate the radiocarbon age using the AIBECS by # 1. defining the transport `T(p)` and the sources and sinks `G(x,p)`, # 1. defining the parameters `p`, diff --git a/docs/lit/tutorials/3_Pmodel.jl b/docs/lit/tutorials/3_Pmodel.jl index e04388a9..651f931c 100644 --- a/docs/lit/tutorials/3_Pmodel.jl +++ b/docs/lit/tutorials/3_Pmodel.jl @@ -6,6 +6,11 @@ #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/notebooks/3_Pmodel.ipynb) #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/notebooks/3_Pmodel.ipynb) +#md # !!! note +#md # All the AIBECS tutorials and how-to guides are available as Jupyter notebooks. +#md # You can view them with [nbviewer](https://nbviewer.jupyter.org/)or execute them online with [binder](https://mybinder.org/) by clicking on the badges above! +#md # (Note that binder can be slow to launch and its memory caps can be a problem when running.) + # In this tutorial we will explicitly simulate 2 tracers whose distributions control and feed back on each other. # We consider a simple model for the cycling of phosphorus with 2 state variables consisting of phosphate (PO₄) AKA dissolved inorganic phosphorus (DIP) and particulate organic phosphorus (POP). diff --git a/docs/lit/tutorials/4_dustmodel.jl b/docs/lit/tutorials/4_dustmodel.jl index 05a346db..15603420 100644 --- a/docs/lit/tutorials/4_dustmodel.jl +++ b/docs/lit/tutorials/4_dustmodel.jl @@ -6,6 +6,11 @@ #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/notebooks/4_dustmodel.ipynb) #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/notebooks/4_dustmodel.ipynb) +#md # !!! note +#md # All the AIBECS tutorials and how-to guides are available as Jupyter notebooks. +#md # You can view them with [nbviewer](https://nbviewer.jupyter.org/)or execute them online with [binder](https://mybinder.org/) by clicking on the badges above! +#md # (Note that binder can be slow to launch and its memory caps can be a problem when running.) + # In this tutorial we will simulate particles of dust that graviationally settle. # 2D maps of dust deposition are available from within the AIBECS. # To use these, we will convert them into sources in the top layer of the model grid. diff --git a/docs/lit/tutorials/5_river_discharge.jl b/docs/lit/tutorials/5_river_discharge.jl index 315cdd2e..a0df4b48 100644 --- a/docs/lit/tutorials/5_river_discharge.jl +++ b/docs/lit/tutorials/5_river_discharge.jl @@ -6,6 +6,11 @@ #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/notebooks/5_river_discharge.ipynb) #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/notebooks/5_river_discharge.ipynb) +#md # !!! note +#md # All the AIBECS tutorials and how-to guides are available as Jupyter notebooks. +#md # You can view them with [nbviewer](https://nbviewer.jupyter.org/)or execute them online with [binder](https://mybinder.org/) by clicking on the badges above! +#md # (Note that binder can be slow to launch and its memory caps can be a problem when running.) + # In this tutorial we will simulate a fictitious radioactive tracer that is injected into the ocean by the 200 largest rivers (by estimated discharge). # The 200 major rivers dataset from [*Dai and Trenberth* (2002)](https://rda.ucar.edu/datasets/ds551.0/) is available from within the AIBECS. # Once "born", our ficitious tracer decays with a parameter timescale $\tau$ as it flows through ocean basins. diff --git a/docs/lit/tutorials/6_groundwater_discharge.jl b/docs/lit/tutorials/6_groundwater_discharge.jl index 3172bc52..3da45dbd 100644 --- a/docs/lit/tutorials/6_groundwater_discharge.jl +++ b/docs/lit/tutorials/6_groundwater_discharge.jl @@ -6,6 +6,11 @@ #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/notebooks/6_groundwater_discharge.ipynb) #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/notebooks/6_groundwater_discharge.ipynb) +#md # !!! note +#md # All the AIBECS tutorials and how-to guides are available as Jupyter notebooks. +#md # You can view them with [nbviewer](https://nbviewer.jupyter.org/)or execute them online with [binder](https://mybinder.org/) by clicking on the badges above! +#md # (Note that binder can be slow to launch and its memory caps can be a problem when running.) + #md # !!! note #md # This tutorial is very similar to the [river discharge notebook](@id river-discharge) diff --git a/docs/paper.bib b/docs/paper.bib index 5af340fe..11038634 100644 --- a/docs/paper.bib +++ b/docs/paper.bib @@ -8,7 +8,7 @@ @article{Amante_Eakins_2009 } -@article{Archer_etal:2000, +@article{Archer_etal_GBC_2000, author = {Archer, David E. and Eshel, Gidon and Winguth, Arne and Broecker, Wallace and Pierrehumbert, Ray and Tobis, Michael and Jacob, Robert}, title = {Atmospheric p{CO}\textsubscript{2} sensitivity to the biological pump in the ocean}, journal = {Global Biogeochemical Cycles}, @@ -79,6 +79,45 @@ @incollection{Box_1979 author = {G.E.P. Box} } +@software{Campin_etal_2021, + author = {Jean-Michel Campin and + Patrick Heimbach and + Martin Losch and + Gael Forget and + edhill3 and + Alistair Adcroft and + amolod and + Dimitris Menemenlis and + dfer22 and + Chris Hill and + Oliver Jahn and + Jeff Scott and + stephdut and + Matt Mazloff and + Baylor Fox-Kemper and + antnguyen13 and + Ed Doddridge and + Ian Fenty and + Michael Bates and + AndrewEichmann-NOAA and + Timothy Smith and + Torge Martin and + Jonathan Lauderdale and + Ryan Abernathey and + samarkhatiwala and + hongandyan and + Bruno Deremble and + dngoldberg and + Pascal Bourgault and + raphael dussin}, + title = {MITgcm/MITgcm: checkpoint67z}, + year = 2021, + publisher = {Zenodo}, + version = {checkpoint67z}, + doi = {10.5281/zenodo.1409237}, + url = {https://doi.org/10.5281/zenodo.1409237} +} + @article{Chamberlain_etal_OM_2019, title = {Transport matrices from standard ocean-model output and quantifying circulation response to climate change}, journal = {Ocean Modelling}, @@ -154,7 +193,7 @@ @article{DataDeps:2018 bibsource = {dblp computer science bibliography, https://dblp.org} } -@article{DeVries_Deutsch_NatGeo_2014, +@article{DeVries_Deutsch_NatGeosci_2014, doi = {10.1038/ngeo2300}, year = {2014}, month = nov, @@ -167,7 +206,7 @@ @article{DeVries_Deutsch_NatGeo_2014 journal = {Nature Geoscience} } -@article{DeVries_etal_GBC_2013, +@article{DeVries_etal_Biogeosciences_2013, author = {DeVries, Tim and Deutsch, C. and Rafter, P. A. and Primeau, F.}, title = {Marine denitrification rates determined from a global {3-D} inverse model}, journal = {Biogeosciences}, @@ -192,7 +231,7 @@ @article{DeVries_etal_Nature_2017 journal = {Nature} } -@article{DeVries_Holzer:2019, +@article{DeVries_Holzer_JGRO_2019, author = {DeVries, Tim and Holzer, Mark}, title = {Radiocarbon and Helium Isotope Constraints on Deep Ocean Ventilation and Mantle-\textsuperscript{3}{He} Sources}, journal = {Journal of Geophysical Research: Oceans}, @@ -203,7 +242,7 @@ @article{DeVries_Holzer:2019 year = {2019} } -@article{DeVries_Primeau:2011, +@article{DeVries_Primeau_JPO_2011, title = {Dynamically and Observationally Constrained Estimates of Water-Mass Distributions and Ages in the Global Ocean}, author = {DeVries, Tim and Primeau, François}, journal = {Journal of Physical Oceanography}, @@ -225,7 +264,21 @@ @article{DeVries_Weber_GBC_2017 year = {2017} } -@article{DeVries:2014, +@article{DeVries_etal_GRL_2012, + author = {DeVries, Tim and Primeau, Francois and Deutsch, Curtis}, + title = {The sequestration efficiency of the biological pump}, + journal = {Geophysical Research Letters}, + volume = {39}, + number = {13}, + pages = {}, + keywords = {biological pump, carbon cycle, nutrients}, + doi = {10.1029/2012GL051963}, + year = {2012} +} + + + +@article{DeVries_GBC_2014, author = {DeVries, Tim}, title = {The oceanic anthropogenic {CO}\textsubscript{2} sink: Storage, air-sea fluxes, and transports over the industrial era}, journal = {Global Biogeochemical Cycles}, @@ -280,7 +333,7 @@ @article{Forget:2010 doi = {10.1175/2009JPO4043.1} } -@article{Frants_etal_2016, +@article{Frants_etal_JGRB_2016, doi = {10.1002/2015jg003111}, year = {2016}, month = {jan}, @@ -293,7 +346,7 @@ @article{Frants_etal_2016 journal = {Journal of Geophysical Research: Biogeosciences} } -@article{Fu_etal_2018, +@article{Fu_etal_DSR1_2018, title = {Tracing ventilation source of tropical pacific oxygen minimum zones with an adjoint global ocean transport model}, journal = {Deep Sea Research Part I: Oceanographic Research Papers}, volume = {139}, @@ -305,7 +358,7 @@ @article{Fu_etal_2018 keywords = {Adjoint transport model, Ventilation, Oxygen minimum zone, Eastern Tropical Pacific, Transit time} } -@article{Gardner_etal_2018a, +@article{Gardner_etal_EPSL_2018, title = {Global assessment of benthic nepheloid layers and linkage with upper ocean dynamics}, journal = {Earth and Planetary Science Letters}, volume = {482}, @@ -317,7 +370,7 @@ @article{Gardner_etal_2018a author = {Wilford D. Gardner and Jo Richardson and Alexey V. Mishonov} } -@article{Gardner_etal_2018b, +@article{Gardner_etal_ProgOcn_2018, title = {Global comparison of benthic nepheloid layers based on 52 years of nephelometer and transmissometer measurements}, journal = {Progress in Oceanography}, volume = {168}, @@ -359,10 +412,10 @@ @article{Holzer_Brzezinski_GBC_2015 -@article{Holzer_etal_2016, +@article{Holzer_etal_GBC_2016, author = {Holzer, Mark and Frants, Marina and Pasquier, Benoît}, title = {The age of iron and iron source attribution in the ocean}, - journal = GBC, + journal = {Global Biogeochemical Cycles}, issn = {1944-9224}, doi = {10.1002/2016GB005418}, keywords = {marine iron cycle, mean iron age, iron age spectrum, iron source attribution, Green function methods, GEOTRACES}, @@ -453,7 +506,7 @@ @article{Holzer_Primeau_JGRO_2013 year = {2013} } -@article{Huang_etal_2021, +@article{Huang_etal_OM_2021, title = {CYCLOCIM: A 4-D variational assimilation system for the climatological mean seasonal cycle of the ocean circulation}, journal = {Ocean Modelling}, volume = {159}, @@ -465,7 +518,7 @@ @article{Huang_etal_2021 keywords = {CFC, Radiocarbon, Residual mean circulation, Data Assimilation, Tracer-transport matrix} } -@article{John_etal_2020, +@article{John_etal_ChemGeo_2020, author = {Seth G. John and Hengdi Liang and Thomas Weber and Tim DeVries and François Primeau and Keith Moore and Mark Holzer and Natalie Mahowald and Wilford Gardner and Alexey Mishonov and Jo Richardson and Yannice Faugere and Guillaume Taburet}, title = {AWESOME OCIM: A simple, flexible, and powerful tool for modeling elemental cycling in the oceans}, journal = {Chemical Geology}, @@ -560,7 +613,7 @@ @article{Kvale_etal_GMD_2017 doi = {10.5194/gmd-10-2425-2017} } -@article{Kwon_Primeau_2006, +@article{Kwon_Primeau_GBC_2006, author = {Kwon, Eun Young and Primeau, François}, title = {Optimization and sensitivity study of a biogeochemistry ocean model using an implicit solver and in situ phosphate data}, journal = {Global Biogeochemical Cycles}, @@ -572,7 +625,7 @@ @article{Kwon_Primeau_2006 year = {2006} } -@article{Kwon_Primeau_2008, +@article{Kwon_Primeau_JGRO_2008, author = {Kwon, Eun Young and Primeau, François}, title = {Optimization and sensitivity of a global biogeochemistry ocean model using combined in situ {DIC}, alkalinity, and phosphate data}, journal = {Journal of Geophysical Research: Oceans}, @@ -662,7 +715,7 @@ @article{Optim.jl-2018 doi = {10.21105/joss.00615} } -@article{Pasquier_Holzer_2016, +@article{Pasquier_Holzer_JGRO_2016, author = {Pasquier, Benoît and Holzer, Mark}, title = {The plumbing of the global biological pump: Efficiency control through leaks, pathways, and time scales}, journal = {Journal of Geophysical Research: Oceans}, @@ -674,7 +727,7 @@ @article{Pasquier_Holzer_2016 year = {2016} } -@article{Pasquier_Holzer_2017, +@article{Pasquier_Holzer_Biogeosciences_2017, author = {Pasquier, Benoît and Holzer, Mark}, title = {Inverse-model estimates of the ocean's coupled phosphorus, silicon, and iron cycles}, journal = {Biogeosciences}, @@ -686,7 +739,7 @@ @article{Pasquier_Holzer_2017 } -@article{Pasquier_Holzer_BG_2018, +@article{Pasquier_Holzer_Biogeosciences_2018, author = {Pasquier, Benoît and Holzer, M.}, title = {The number of past and future regenerations of iron in the ocean and its intrinsic fertilization efficiency}, journal = {Biogeosciences}, @@ -717,10 +770,10 @@ @software{Plots.jl doi = {10.5281/zenodo.4725317} } -@article{Primeau_etal:2013, +@article{Primeau_etal_JGRO_2013, author = {Primeau, François and Holzer, Mark and DeVries, Tim}, title = {{S}outhern {O}cean nutrient trapping and the efficiency of the biological pump}, - journal = {Journal of Geophysical Research}, + journal = {Journal of Geophysical Research: Oceans}, volume = {118}, doi = {10.1002/jgrc.20181}, pages = {2547-2564}, @@ -791,7 +844,7 @@ @book{Sarmiento_Gruber:2006 } -@article{Schlitzer2018, +@article{Schlitzer_etal_ChemGeo_2018, author = {Schlitzer, Reiner and Anderson, Robert F. and Dodas, Elena Masferrer and Lohan, Maeve and Geibert, Walter and Tagliabue, Alessandro and Bowie, Andrew and Jeandel, Catherine and Maldonado, Maria T and Landing, William M and Cockwell, Donna and Abadie, Cyril and Abouchami, Wafa and Achterberg, Eric P and Agather, Alison and Aguliar-Islas, Ana and van Aken, Hendrik M and Andersen, Morten and Archer, Corey and Auro, Maureen and de Baar, Hein J and Baars, Oliver and Baker, Alex R and Bakker, Karel and Basak, Chandranath and Baskaran, Mark and Bates, Nicholas R and Bauch, Dorothea and van Beek, Pieter and Behrens, Melanie K and Black, Erin and Bluhm, Katrin and Bopp, Laurent and Bouman, Heather and Bowman, Katlin and Bown, Johann and Boyd, Philip and Boye, Marie and Boyle, Edward A. and Branellec, Pierre and Bridgestock, Luke and Brissebrat, Guillaume and Browning, Thomas and Bruland, Kenneth W and Brumsack, Hans-J{\"u}rgen and Brzezinski, Mark and Buck, Clifton S and Buck, Kristen N and Buesseler, Ken and Bull, Abby and Butler, Edward and Cai, Pinghe and Mor, Patricia C{\'a}mara and Cardinal, Damien and Carlson, Craig and Carrasco, Gonzalo and Casacuberta, N{\'u}ria and Casciotti, Karen L and Castrillejo, Maxi and Chamizo, Elena and Chance, Rosie and Charette, Matthew A and Chaves, Joaquin E and Cheng, Hai and Chever, Fanny and Christl, Marcus and Church, Thomas M and Closset, Ivia and Colman, Albert and Conway, Tim M and Cossa, Daniel and Croot, Peter and Cullen, Jay T and Cutter, Gregory A and Daniels, Chris and Dehairs, Frank and Deng, Feifei and Dieu, Huong Thi and Duggan, Brian and Dulaquais, Gabriel and Dumousseaud, Cynthia and Echegoyen-Sanz, Yolanda and Edwards, R Lawrence and Ellwood, Michael and Fahrbach, Eberhard and Fitzsimmons, Jessica N and Flegal, A Russell and Fleisher, Martin Q and van de Flierdt, Tina and Frank, Martin and Friedrich, Jana and Fripiat, François and Fr{\"o}llje, Henning and Galer, Stephen J G and Gamo, Toshitaka and Ganeshram, Raja S and Garcia-Orellana, Jordi and Garcia-Solsona, Ester and Gault-Ringold, Melanie and George, Ejin and Gerringa, Loes J A and Gilbert, Melissa and Godoy, Jose M and Goldstein, Steven L. and Gonzalez, Santiago R and Grissom, Karen and Hammerschmidt, Chad and Hartman, Alison and Hassler, Christel S and Hathorne, Ed C and Hatta, Mariko and Hawco, Nicholas and Hayes, Christopher T and Heimb{\"u}rger, Lars-Eric and Helgoe, Josh and Heller, Maija and Henderson, Gideon M and Henderson, Paul B and van Heuven, Steven and Ho, Peng and Horner, Tristan J and Hsieh, Yu-Te and Huang, Kuo-Fang and Humphreys, Matthew P and Isshiki, Kenji and Jacquot, Jeremy E and Janssen, David J and Jenkins, William J and John, Seth and Jones, Elizabeth M and Jones, Janice L and Kadko, David C and Kayser, Rick and Kenna, Timothy C and Khondoker, Roulin and Kim, Taejin and Kipp, Lauren and Klar, Jessica K and Klunder, Maarten and Kretschmer, Sven and Kumamoto, Yuichiro and Laan, Patrick and Labatut, Marie and Lacan, François and Lam, Phoebe J and Lambelet, Myriam and Lamborg, Carl H and Le Moigne, Fr{\'e}d{\'e}ric A C and Le Roy, Emilie and Lechtenfeld, Oliver J and Lee, Jong-Mi and Lherminier, Pascale and Little, Susan and L{\'o}pez-Lora, Mercedes and Lu, Yanbin and Masque, Pere and Mawji, Edward and Mcclain, Charles R and Measures, Christopher and Mehic, Sanjin and Barraqueta, Jan-Lukas Menzel and van der Merwe, Pier and Middag, Rob and Mieruch, Sebastian and Milne, Angela and Minami, Tomoharu and Moffett, James W and Moncoiffe, Gwenaelle and Moore, Willard S and Morris, Paul J and Morton, Peter L and Nakaguchi, Yuzuru and Nakayama, Noriko and Niedermiller, John and Nishioka, Jun and Nishiuchi, Akira and Noble, Abigail and Obata, Hajime and Ober, Sven and Ohnemus, Daniel C and van Ooijen, Jan and O'Sullivan, Jeanette and Owens, Stephanie and Pahnke, Katharina and Paul, Maxence and Pavia, Frank and Pena, Leopoldo D and Peters, Brian and Planchon, Frederic and Planquette, Helene and Pradoux, Catherine and Puigcorb{\'e}, Viena and Quay, Paul and Queroue, Fabien and Radic, Amandine and Rauschenberg, S and Rehk{\"a}mper, Mark and Rember, Robert and Remenyi, Tomas and Resing, Joseph A and Rickli, Joerg and Rigaud, Sylvain and Rijkenberg, Micha J A and Rintoul, Stephen and Robinson, Laura F. and Roca-Mart{\'\i}, Montserrat and Rodellas, Valenti and Roeske, Tobias and Rolison, John M and Rosenberg, Mark and Roshan, Saeed and van der Loeff, Michiel M Rutgers and Ryabenko, Evgenia and Saito, Mak A and Salt, Lesley A and Sanial, Virginie and Sarthou, Geraldine and Schallenberg, Christina and Schauer, Ursula and Scher, Howie and Schlosser, Christian and Schnetger, Bernhard and Scott, Peter and Sedwick, Peter N and Semiletov, Igor and Shelley, Rachel...}, title = {{The GEOTRACES Intermediate Data Product 2017}}, journal = {Chemical Geology}, @@ -801,7 +854,7 @@ @article{Schlitzer2018 month = aug } -@article{Schlitzer1993, +@article{Schlitzer_JPO_1993, author = {Reiner Schlitzer}, title = {Determining the Mean, Large-Scale Circulation of the Atlantic with the Adjoint Method}, journal = {Journal of Physical Oceanography}, @@ -814,7 +867,7 @@ @article{Schlitzer1993 pages = {1935 - 1952} } -@article{Schlitzer2000, +@article{Schlitzer_GeoMonoAGU_2000, title = {Applying the adjoint method for biogeochemical modeling: export of particulate organic matter in the world ocean}, author = {Schlitzer, Reiner}, journal = {GEOPHYSICAL MONOGRAPH-AMERICAN GEOPHYSICAL UNION}, @@ -825,7 +878,7 @@ @article{Schlitzer2000 } -@article{Schlitzer2002, +@article{Schlitzer_DSR2_2002, title = {Carbon export fluxes in the Southern Ocean: results from inverse modeling and comparison with satellite-based estimates}, journal = {Deep Sea Research Part II: Topical Studies in Oceanography}, volume = {49}, @@ -838,7 +891,7 @@ @article{Schlitzer2002 author = {Reiner Schlitzer} } -@article{Schlitzer2004, +@article{Schlitzer_JO_2004, doi = {10.1023/b:joce.0000038318.38916.e6}, year = {2004}, publisher = {Springer Science and Business Media {LLC}}, @@ -850,7 +903,7 @@ @article{Schlitzer2004 journal = {Journal of Oceanography} } -@article{Schlitzer2007, +@article{Schlitzer_JPO_2007, doi = {10.1175/jpo3011.1}, url = {https://doi.org/10.1175/jpo3011.1}, year = {2007}, @@ -864,7 +917,7 @@ @article{Schlitzer2007 journal = {Journal of Physical Oceanography} } -@article{Taburet_etal_2019, +@article{Taburet_etal_OcnSci_2019, author = {Taburet, G. and Sanchez-Roman, A. and Ballarotta, M. and Pujol, M.-I. and Legeais, J.-F. and Fournier, F. and Faugere, Y. and Dibarboure, G.}, title = {DUACS~DT2018: 25~years of reprocessed sea level altimetry products}, journal = {Ocean Science}, @@ -875,7 +928,7 @@ @article{Taburet_etal_2019 doi = {10.5194/os-15-1207-2019} } -@article{Teng_etal_NatGeo_2014, +@article{Teng_etal_NatGeosci_2014, doi = {10.1038/ngeo2303}, year = {2014}, month = nov, @@ -890,7 +943,7 @@ @article{Teng_etal_NatGeo_2014 -@article{Thacker_1989, +@article{Thacker_JGRO_1989, author = {Thacker, William Carlisle}, title = {The role of the Hessian matrix in fitting models to measurements}, journal = {Journal of Geophysical Research: Oceans}, diff --git a/docs/paper.md b/docs/paper.md index 04a10e81..6bf1e5ae 100644 --- a/docs/paper.md +++ b/docs/paper.md @@ -1,5 +1,5 @@ --- -title: 'AIBECS.jl: The ideal tool for exploring global marine biogeochemical cycles.' +title: 'AIBECS.jl: A tool for exploring global marine biogeochemical cycles.' tags: - Julia - Oceanography @@ -8,19 +8,21 @@ tags: authors: - name: Benoît Pasquier^[corresponding author] orcid: 0000-0002-3838-5976 - affiliation: "1" # (Multiple affiliations must be quoted) - - name: Seth G. John - orcid: 0000-0002-8257-626X - affiliation: "1" # (Multiple affiliations must be quoted) + affiliation: "1,3" # (Multiple affiliations must be quoted) - name: François W. Primeau orcid: 0000-0001-7452-9415 affiliation: "2" + - name: Seth G. John + orcid: 0000-0002-8257-626X + affiliation: "1" # (Multiple affiliations must be quoted) affiliations: - name: Department of Earth Sciences, University of Southern California index: 1 - name: Department of Earth System Science, University of California, Irvine index: 2 -date: 19 Aug 2021 + - name: (now at) School of Mathematics and Statistics, University of New South Wales, Sydney + index: 3 +date: 7 Dec 2021 bibliography: paper.bib --- @@ -33,9 +35,9 @@ bibliography: paper.bib The ocean transports, mixes, and transforms chemical constituents on a multitude of time and length scales. Observations and models are both essential for making sense of this complex system. However, the days of just publishing data without any quantitative modelling are over, increasing pressure on sea-going oceanographers that are expected to be proficient in the use of biogeochemical models. -And while the simplest of these models consist of only a few boxes, with solutions that are easily obtained by hand or on a simple desktop computer, the most advanced models have high-resolution three-dimensional meshes that require high-performance computing (HPC) clusters and a considerable amount of computational-science expertise. +And while the simplest of these models consist of only a few boxes [e.g., the two-box model of @Archer_etal_GBC_2000], with solutions that are easily obtained by hand or on a simple desktop computer, the most advanced models have high-resolution three-dimensional meshes that require high-performance computing (HPC) clusters and a considerable amount of computational-science expertise [e.g., the MITgcm, @Campin_etal_2021]. A high barrier to entry for modelling in oceanography hinders advances in the field. -[AIBECS.jl](https://github.com/JuliaOcean/AIBECS.jl) [@Pasquier:2021] is a [JuliaOcean](https://github.com/JuliaOcean/)-affiliated package written in [Julia](https://julialang.org/) [@Bezanson_etal:2017], which aims to lower this barrier by providing an easy-to-use, open-source, and modular framework for simulating global marine tracers and biogeochemical parameter fitting. +[AIBECS.jl](https://github.com/JuliaOcean/AIBECS.jl) [@Pasquier:2021] is a [JuliaOcean](https://github.com/JuliaOcean/)-affiliated package written in [Julia](https://julialang.org/) [@Bezanson_etal:2017], which aims to lower this barrier by providing an easy-to-use, open-source, and modular framework for simulating global marine tracers in steady-state and biogeochemical parameter fitting. @@ -45,21 +47,20 @@ A high barrier to entry for modelling in oceanography hinders advances in the fi A conceptual model of the cycle of any marine tracer essentially requires two components. (i) A model of how the tracer is transported (be it the ocean currents and eddies, gravitational settling, or a combination of those), and (ii) a model of the local sources and sinks at any location. AIBECS.jl is built on this concept and allows users to build numerical models of marine tracers by selecting a circulation and/or vertical transport of the tracer with particles and local sources and sinks. -Tools for generating the equations, solving them, and then diagnosing and plotting the simulated tracers are also provided, either directly by AIBECS.jl, by its dependencies, or by satellite packages in the AIBECS and Julia ecosystem. - +Tools for generating the steady-state equations, solving them, and then diagnosing and plotting the simulated tracers are also provided, either directly by AIBECS.jl, by its dependencies, or by satellite packages in the AIBECS and Julia ecosystem. -By definition, all models are wrong because they make simplifying assumptions [@Box_1979]. -These assumptions give rise to model parameters that can capture fundamental characteristics of the system. -Once the model of the cycle of a marine tracer is implemented, it is thus natural to try to estimate biogeochemical parameters by minimizing model–observation mismatches, which also improves the skill of the model. -Parameter optimization is generally more efficiently performed when first and second derivatives are available, and these derivatives can also be used to estimate parameter sensitivity [@Thacker_1989]. +@Box_1979 has remarked that, by definition, all models are wrong because they make simplifying assumptions. +These assumptions can give rise to model parameters that can capture fundamental characteristics of the system. +Once the model of the cycle of a marine tracer is implemented, it is thus natural to try to estimate biogeochemical parameters by minimizing model–observation mismatches, which may improves the skill of the model. +Parameter optimization is generally more efficiently performed when first and second derivatives are available, and these derivatives can also be used to estimate parameter sensitivity [@Thacker_JGRO_1989]. AIBECS.jl was designed with parameter fitting in mind and provides, along with satellite packages, tools for generating first- and second-order derivatives automatically and efficiently. -The AIBECS.jl package builds on the vision of the [AWESOME OCIM](https://github.com/MTEL-USC/AWESOME-OCIM) [A Working Environment for Simulating Ocean Movement and Elemental cycling within the Ocean Circulation Inverse Model, or AO, @John_etal_2020], which was designed to make three-dimensional element-cycling models more broadly accessible. -Offering a truly open-source solution, the AIBECS.jl framework improves on the AO on a number of fronts to target education and research. +The AIBECS.jl package builds on the vision of the [AWESOME OCIM](https://github.com/MTEL-USC/AWESOME-OCIM) [A Working Environment for Simulating Ocean Movement and Elemental cycling within the Ocean Circulation Inverse Model, or AO, @John_etal_ChemGeo_2020], which was designed to make three-dimensional element-cycling models more broadly accessible. +Written in [Julia](https://julialang.org/) — chosen for of its combined expressive power and efficiency and offering a truly open-source solution — the AIBECS.jl framework improves on the AO on a number of fronts to target education and research. Simple AIBECS.jl simulations can be produced in minutes in interactive notebooks while resource-hungry projects, e.g., for optimizing models with multiple tracers interacting nonlinearly within a high-resolution mesh, can be easily version-controlled, hosted, and run on HPC clusters. @@ -67,11 +68,11 @@ Simple AIBECS.jl simulations can be produced in minutes in interactive notebooks Through a simple user interface, AIBECS.jl provides access to a variety of steady-state ocean circulation models. These currently include -the Ocean Circulation Inverse Model (OCIM) v0.1 [@Primeau_etal:2013], -v1.0 [@DeVries_Primeau:2011; @DeVries:2014], -and v2.0 [@DeVries_Holzer:2019], +the Ocean Circulation Inverse Model (OCIM) v0.1 [@Primeau_etal_JGRO_2013], +v1.0 [@DeVries_Primeau_JPO_2011; @DeVries_GBC_2014], +and v2.0 [@DeVries_Holzer_JGRO_2019], and the MITgcm-built Ocean Comprehensible Atlas (OCCA) ocean-state estimate model [@Forget:2010], of which the downloads are handled by the [DataDeps.jl](https://github.com/oxinabox/DataDeps.jl) package [@DataDeps:2018; @White_etal:2019]. -AIBECS.jl also offers classic two-box and three-box models [@Sarmiento_Gruber:2006; @Archer_etal:2000]. +AIBECS.jl also offers classic two-box and three-box models [@Sarmiento_Gruber:2006; @Archer_etal_GBC_2000]. The [OceanGrids.jl](https://github.com/briochemc/OceanGrids.jl) package, on which AIBECS depends, provides the underlying grid configuration types as well as regridding and interpolating routines. Swapping the underlying circulation model and grid requires a single-line-of-code change, facilitating intercomparison projects. As new circulation models that are represented in matrix form are made publicly available, they will be added to the collection. @@ -87,10 +88,10 @@ In addition, AIBECS provides access to a number of predefined fields that can be Fine-resolution (1-arc-minute) topography from the ETOPO1 dataset [@Amante_Eakins_2009] can be used for a refined interception of particulate fluxes by subgrid topographic features not captured by coarser circulation models. For aeolian deposition, AIBECS.jl includes aerosol-type- and region-of-origin-partitioned dust deposition fields [@Chien_etal_2016; @Kok_etal_2021b]. Datasets for global river discharge [@Dai_2017; @Dai_Trenberth_2002] and surface groundwater discharge [@Luijendijk_etal_2019; @Luijendijk_etal_2020] are included. -For hydrothermal-sourced tracers, the helium fluxes from the Earth's mantle computed with the OCIM v1.0 and v2.0 are available when loading the corresponding circulation models [@DeVries:2014; @DeVries_Holzer:2019]. -AIBECS.jl also provides access to the data included with the AWESOME OCIM framework [@John_etal_2020], namely data from the Global Ocean Data Analysis Project [GLODAP, @Lauvset_etal_2016; @Olsen_etal_2016], P-cycling modelled fields from @Weber_etal_Science_2018, nepheloid layers [@Gardner_etal_2018a; @Gardner_etal_2018b; Taburet_etal_2019], as well as other data already present within AIBECS or satellite packages. +For hydrothermal-sourced tracers, the helium fluxes from the Earth's mantle computed with the OCIM v1.0 and v2.0 are available when loading the corresponding circulation models [@DeVries_GBC_2014; @DeVries_Holzer_JGRO_2019]. +AIBECS.jl also provides access to the data included with the AWESOME OCIM framework [@John_etal_ChemGeo_2020], namely data from the Global Ocean Data Analysis Project [GLODAP, @Lauvset_etal_2016; @Olsen_etal_2016], P-cycling modelled fields from @Weber_etal_Science_2018, nepheloid layers [@Gardner_etal_EPSL_2018; @Gardner_etal_ProgOcn_2018; @Taburet_etal_OcnSci_2019], as well as other data already present within AIBECS or satellite packages. Also useful to global biogeochemistry modelling are data from the World Ocean Atlas [@WOA_2018_nut] that can be downloaded, assisted by external package [WorldOceanAtlasTools.jl](https://github.com/briochemc/WorldOceanAtlasTools.jl) [@WorldOceanAtlasTools.jl-2019]. -Similarly, GEOTRACES data [@Schlitzer2018] can be handled by the [GEOTRACES.jl](https://github.com/briochemc/GEOTRACES.jl) package (although GEOTRACES requires manual download of the data). +Similarly, GEOTRACES data [@Schlitzer_etal_ChemGeo_2018] can be handled by the [GEOTRACES.jl](https://github.com/briochemc/GEOTRACES.jl) package (although GEOTRACES requires manual download of the data). More advanced usage such as optimization is facilitated by the [F1Method.jl](https://github.com/briochemc/F1Method.jl) package [@F1Method], which provides efficient gradient and Hessian computations of objective functions defined through AIBECS.jl, which can then be directly fed to optimization routines from, e.g., the [Optim.jl](https://github.com/JuliaNLSolvers/Optim.jl) package [@Optim.jl-2018]. Finally, plotting recipes for the [Plots.jl](https://github.com/JuliaPlots/Plots.jl) package [@Plots.jl], are available. @@ -123,23 +124,22 @@ Continuous integration through GitHub actions also includes a fairly complete su +Pioneered by @Schlitzer_JPO_1993 to study the ocean circulation using ventilation tracers such as radiocarbon [see also @Schlitzer_GeoMonoAGU_2000], the low computational costs of steady-state circulation models allow for efficient optimization and inference/estimation of biogeochemical parameters. +Today, despite reduced resolution and steady-state assumption, data-constrained matrix-transport models such as the OCIM are at the forefront of oceanographic research. +This is evidenced for example by the growing number of high-profile studies that use such models for parameter estimation published in recent years [e.g., @DeVries_etal_Nature_2017; @DeVries_etal_Biogeosciences_2013; @DeVries_etal_GRL_2012; @Weber_Deutsch_Nature_2010; @DeVries_GBC_2014; @DeVries_Weber_GBC_2017; @Teng_etal_NatGeosci_2014; @DeVries_Deutsch_NatGeosci_2014; @Weber_etal_PNAS_2016; @Roshan_DeVries_NatCom_2017; @Wang_etal_Nature_2019]. +However, although the steady-state assumption and matrix representation simplify the simulation of tracers compared to traditional Ocean General Circulation Models (OGCMs), most studies that employ a steady-state matrix representation of marine cycling remain difficult to reproduce without significant computer-science and modelling expertise because they are built on private implementations. +Comparisons between different circulation models are moreover complicated by the lack of standardization across models. -In spite of reduced resolution and steady-state assumption, data-constrained coarse-resolution matrix transport models such as the OCIM are at the forefront of oceanographic research, as evidenced by their increasing use in recent literature. -Pioneered by @Schlitzer1993 to study the ocean circulation using ventilation tracers such as radiocarbon [see also @Schlitzer2000], -the low computational costs of steady-state circulation models allow for efficient optimization and inference/estimation of biogeochemical parameters, e.g., for the carbon cycle [@Schlitzer2000; @Schlitzer2002; @Schlitzer2004; @DeVries:2014; @Weber_etal_PNAS_2016; @Roshan_DeVries_NatCom_2017; @DeVries_etal_Nature_2017], for other macronutrient cycles (e.g. phosphorus, nitrogen, silicon) [@Kwon_Primeau_2006; @Kwon_Primeau_2008; @DeVries_etal_GBC_2013; @Holzer_etal_JGRO_2014; @Holzer_Brzezinski_GBC_2015; @DeVries_Weber_GBC_2017; @Wang_etal_Nature_2019], for stoichiometric ratios [@DeVries_Deutsch_NatGeo_2014; @Teng_etal_NatGeo_2014; @Weber_Deutsch_Nature_2010], and for micronutrients and trace metals such as dissolved iron [@Frants_etal_2016; @Pasquier_Holzer_2017], zinc [@Roshan_etal_GBC_2018], and argon [@Holzer_etal_GRL_2019], and hydrothermal gases such as helium [@Holzer_etal_EPSL_2017]. -Efficient computation also allows for a wide range of experiments [@Primeau_etal:2013; @DeVries:2014; @Holzer_etal_GBC_2019]. -Further, these models are amenable to the development of new metrics, thanks to their matrix representation, which enables the use of powerful linear-algebra techniques to efficiently compute exact partitions, pathways, timescales, eigen modes, moments, and other novel diagnostics [@Primeau_JPO_2005; @Holzer_Primeau_JGRO_2013; @Pasquier_Holzer_2016; @Holzer_etal_2016; @Fu_etal_2018; @Pasquier_Holzer_BG_2018; @Holzer_etal_JGRO_2020; @Holzer_etal_GBC_2021]. -Finally, steady-state (and cyclo-stationary) circulation models are useful to bypass the need for long and costly spinups of large ocean general circulation models [@Khatiwala_etal_OM_2005; @Khatiwala_GBC_2007; @Khatiwala_OM_2008; @Khatiwala_Nature_2009; @Li_Primeau_OM_2008; @Bardin_etal_OM_2014; @Bardin_etal_OM_2016; @Huang_etal_2021]. -Although the steady-state assumption and matrix representation of the advective–diffusive tracer flux divergence simplifies the simulation of tracers compared to traditional Ocean General Circulation Models (OGCMs), most of the above mentioned studies required significant expertise and were built using private implementations that remain difficult to reproduce. -Comparisons between different circulation models are moreover complicated by the lack of standardization across models. -There is a need to facilitate the use of steady-state ocean-circulation models by providing +Hence, there is a need to facilitate the use of steady-state ocean-circulation models by providing: (i) an integrated framework for handling a number of different ocean-circulation models with tools for swapping circulations (including interpolating from one model grid to another), -(ii) a user-friendly interface for translating mathematical models of biogeochemical cycles into the corresponding code (e.g., for sources, sinks, and vertical transport of tracers), and +(ii) a user-friendly interface for translating mathematical models of biogeochemical cycles into the corresponding code (e.g., for sources, sinks, and vertical transport of tracers), and (iii) solvers for efficient simulations, optimization, diagnosis, and statistical analysis. + + AIBECS.jl provides a free, open-source, unified framework for biogeochemical-tracer-modelling studies that use steady-state circulation models. Among other advantages over existing solutions (i.e., the AO), AIBECS.jl offers better computational efficiency, enhanced versatility, composability with other Julia packages, and ease of reproducibility (granted by version control and Julia's package manager) and improved syntax, which are pillars of modern scientific dissemination. Thus, AIBECS users may include sea-going oceanographers and educators who will benefit from its simplicity, as well as more experienced modellers who can leverage its computational advantages. @@ -154,7 +154,7 @@ Of particular interest to the broader community to facilitate the simulation of -Further devepment could include Newton–Krylov solvers for cyclo-stationary states [e.g., CYCLOCIM: @Huang_etal_2021] or time-dependent solvers for transient biogeochemical simualtions provided, e.g., by the SciML ecosystem [@Rackauckas_Nie_JORS_2017]. +Further devepment could include exposing advanced Grren-function-based diagnostic tools [e.g., @Holzer_etal_GBC_2021; @Pasquier_Holzer_Biogeosciences_2018], coupling tracers on different grids, Newton–Krylov solvers for cyclo-stationary states [e.g., CYCLOCIM: @Huang_etal_OM_2021], or time-dependent solvers for transient biogeochemical simualtions provided, e.g., by the SciML ecosystem [@Rackauckas_Nie_JORS_2017]. Bridging packages could be implemented for improved composability with statistical packages [e.g., [Turing.jl](https://github.com/TuringLang/Turing.jl): @ge2018t], optimization tools, and plotting software [e.g., [Makie.jl](https://github.com/JuliaPlots/Makie.jl): @Makie.jl; @Danisch_Krumbiegel_2021]. @@ -163,5 +163,6 @@ Bridging packages could be implemented for improved composability with statistic FWP and BP acknowledge funding from the Department of Energy (grant DE-SC0016539) and the National Science Foundation (grant 1658380). BP and SGJ acknowledge funding provided by the Simons Foundation (Award #426570SP to SGJ) and the National Science Foundation (grant 1736896). +The authors thank Dr. Zhen Wu and Prof. Dan Kelley for their insightful reviews that have helped improve the software and this manuscript. # References \ No newline at end of file diff --git a/src/AIBECS.jl b/src/AIBECS.jl index f79ae8ec..00b78af1 100644 --- a/src/AIBECS.jl +++ b/src/AIBECS.jl @@ -27,6 +27,8 @@ using NearestNeighbors using Shapefile using Bijectors using ImageFiltering +using SciMLBase + diff --git a/src/Parameters.jl b/src/Parameters.jl index 220be66a..623de9f5 100644 --- a/src/Parameters.jl +++ b/src/Parameters.jl @@ -222,7 +222,7 @@ Base.vec(p::T) where {T <: APar} = [UnPack.unpack(p, Val(s)) for s in flattenabl """ length(p::AbstractParameter) -Returns the length of the **flattened/optimzable** vector of `p`. +Returns the length of the **flattened/optimizable** vector of `p`. May be different from the number of parameters. Can also be used directly on the type of `p`. @@ -233,7 +233,7 @@ Base.length(::Type{T}) where {T <: APar} = sum(flattenable(T)) """ size(p::AbstractParameter) -Returns the size of the **flattened/optimzable** vector of `p`. +Returns the size of the **flattened/optimizable** vector of `p`. May be different from the number of parameters. Can also be used directly on the type of `p`. diff --git a/src/overload_solve.jl b/src/overload_solve.jl index d013b6cf..510ce0d7 100644 --- a/src/overload_solve.jl +++ b/src/overload_solve.jl @@ -1,9 +1,8 @@ -using DiffEqBase -struct CTKAlg <: DiffEqBase.AbstractSteadyStateAlgorithm end +struct CTKAlg <: SciMLBase.AbstractSteadyStateAlgorithm end """ - solve(prob::DiffEqBase.AbstractSteadyStateProblem, + solve(prob::SciMLBase.AbstractSteadyStateProblem, alg::CTKAlg; nrm=norm, τstop=1e12*365*24*60*60, @@ -12,30 +11,30 @@ struct CTKAlg <: DiffEqBase.AbstractSteadyStateAlgorithm end Solves `prob` using the modified C.T.Kelley Shamanskii algorithm. """ -function DiffEqBase.solve(prob::DiffEqBase.AbstractSteadyStateProblem, +function SciMLBase.solve(prob::SciMLBase.AbstractSteadyStateProblem, alg::CTKAlg; nrm=norm, τstop=ustrip(u"s", 1e6u"Myr"), preprint="", maxItNewton=50) - # Define the functions according to DiffEqBase.SteadyStateProblem type + # Define the functions according to SciMLBase.SteadyStateProblem type p = prob.p x0 = copy(prob.u0) dx = copy(x0) function F(x) - if DiffEqBase.isinplace(prob) + if SciMLBase.isinplace(prob) prob.f(dx, x, p) dx else prob.f(x, p) end end - ∇ₓF(x) = prob.f(Val{:jac}, x, p) - # Compute `u_steady` and `resid` as per DiffEqBase using my algorithm + ∇ₓF(x) = prob.f.jac(x, p) + # Compute `u_steady` and `resid` as per SciMLBase using my algorithm x_steady = NewtonChordShamanskii(F, ∇ₓF, nrm, x0, τstop; preprint=preprint, maxItNewton=maxItNewton) resid = F(x_steady) - # Return the common DiffEqBase solution type - DiffEqBase.build_solution(prob, alg, x_steady, resid; retcode=:Success) + # Return the common SciMLBase solution type + SciMLBase.build_solution(prob, alg, x_steady, resid; retcode=:Success) end export solve, SteadyStateProblem, CTKAlg diff --git a/test/bgc_functions.jl b/test/bgc_functions.jl index 81b3b6e5..212fcdbb 100644 --- a/test/bgc_functions.jl +++ b/test/bgc_functions.jl @@ -120,7 +120,7 @@ Tests @test norm(v_all .* x) / norm(v_all' * F₀) > ustrip(upreferred(1u"Myr")) end @testset "Jacobian of the state function" begin - ∇ₓF₀ = fun(Val{:jac}, x, p) + ∇ₓF₀ = fun.jac(x, p) @test ∇ₓF₀ isa SparseMatrixCSC @test size(∇ₓF₀) == (n, n) end @@ -135,7 +135,7 @@ end dx = similar(x) @testset "in-place F ≈ out-of-place F" begin @test fun(x, p) ≈ fun!(dx, x, p) rtol = 1e-10 - @test fun(Val{:jac}, x, p) ≈ fun!(Val{:jac}, x, p) rtol = 1e-10 + @test fun.jac(x, p) ≈ fun!.jac(x, p) rtol = 1e-10 end end @@ -151,7 +151,7 @@ end @test F2(x, p) ≈ L(x, p) + NL(x, p) - T(p) * x rtol = 1e-10 end @testset "split ∇ₓF ≈ ∇ₓF" begin - @test fun(Val{:jac}, x, p) ≈ ∇ₓF2(x, p) rtol = 1e-10 + @test fun.jac(x, p) ≈ ∇ₓF2(x, p) rtol = 1e-10 end @testset "split ∇ₓF ≈ T + ∇ₓNL" begin @test ∇ₓF2(x, p) ≈ ∇ₓL(p) + ∇ₓNL(x, p) - T(p) rtol = 1e-10 diff --git a/test/cost_functions.jl b/test/cost_functions.jl index 42ac4e6d..2a776915 100644 --- a/test/cost_functions.jl +++ b/test/cost_functions.jl @@ -2,8 +2,7 @@ ωs = [1.0, 0.0, 0.0] ωp = 1e-7 # PO₄ mean and variance of observations fom WOA18 -WOA = WorldOceanAtlasTools -μDIPobs3D, σ²DIPobs3D = WOA.fit_to_grid(grd, 2018, "phosphate", "annual", "1°", "an") +μDIPobs3D, σ²DIPobs3D = WorldOceanAtlasTools.fit_to_grid(grd, "PO₄") μDIPobs, σ²DIPobs = μDIPobs3D[iwet], σ²DIPobs3D[iwet] μx = (μDIPobs, missing, missing) σ²x = (σ²DIPobs, missing, missing) diff --git a/test/derivatives.jl b/test/derivatives.jl index d5b85233..4fbe405f 100644 --- a/test/derivatives.jl +++ b/test/derivatives.jl @@ -12,10 +12,10 @@ x = xgeo * ones(n) testp = AIBECS.reconstruct(TestParameters, 2vec(p)) # other value for testing p @testset "∇ₓF" begin - @test ForwardDiff.jacobian(x -> fun(x, p), x) ≈ fun(Val{:jac}, x, p) rtol = 1e-14 - @test ForwardDiff.jacobian(x -> fun(x, p), 2x) ≈ fun(Val{:jac}, 2x, p) rtol = 1e-14 - @test ForwardDiff.jacobian(x -> fun(x, p), -x) ≈ fun(Val{:jac}, -x, p) rtol = 1e-14 - @test ForwardDiff.jacobian(x -> fun(x, testp), x) ≈ fun(Val{:jac}, x, testp) rtol = 1e-14 + @test ForwardDiff.jacobian(x -> fun(x, p), x) ≈ fun.jac(x, p) rtol = 1e-14 + @test ForwardDiff.jacobian(x -> fun(x, p), 2x) ≈ fun.jac(2x, p) rtol = 1e-14 + @test ForwardDiff.jacobian(x -> fun(x, p), -x) ≈ fun.jac(-x, p) rtol = 1e-14 + @test ForwardDiff.jacobian(x -> fun(x, testp), x) ≈ fun.jac(x, testp) rtol = 1e-14 end @testset "∇ₓf" begin @test ForwardDiff.jacobian(x -> [f(x, p)], x) ≈ ∇ₓf(x, p) rtol = 1e-14 diff --git a/test/runtests.jl b/test/runtests.jl index a428d44c..40f989a8 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -5,7 +5,7 @@ using SparseArrays, LinearAlgebra using Unitful using Unitful: °, m, km using WorldOceanAtlasTools -using DiffEqBase +using SciMLBase using ForwardDiff, DualNumbers using DataFrames using Distributions diff --git a/test/solvers.jl b/test/solvers.jl index e53b4d05..b8d05424 100644 --- a/test/solvers.jl +++ b/test/solvers.jl @@ -8,7 +8,7 @@ algs = [CTKAlg] @unpack xgeo = p x = xgeo * ones(n) @testset "$(string(alg))" for alg in algs - @test alg <: DiffEqBase.AbstractSteadyStateAlgorithm + @test alg <: SciMLBase.AbstractSteadyStateAlgorithm @testset "$(nx)x, $(np)p" for nx in 1:2, np in 1:2 testp = AIBECS.reconstruct(TestParameters, np * vec(p)) oopprob = SteadyStateProblem(fun, nx * x, testp)