Merge pull request #7 from PALEOtoolkit/add_examples

Add 3 box, MITgcm examples

Project.toml

@@ -1,33 +1,52 @@
 name = "PALEOocean"
 uuid = "41de04b1-2efd-44ae-92ae-39d71a4fd99b"
 authors = ["sd336 "]
-version = "0.3.0"
+version = "0.4.0"
 
 [deps]
 Interpolations = "a98d9a8b-a2ab-59e6-89dd-64a1c18fca59"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
+MAT = "23992714-dd62-5051-b70f-ba57cb901cac"
+PALEOaqchem = "673cec3b-17d1-411f-9fcd-71c01c593120"
 PALEOboxes = "804b410e-d900-4b2a-9ecd-f5a06d4c1fd4"
+Preferences = "21216c6a-2e73-6563-6e65-726566657250"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 SIMD = "fdea26ae-647d-5447-a871-4b548cad5224"
 SnoopPrecompile = "66db9d55-30c0-4569-8b51-7e840670fc0c"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 TestEnv = "1e6cf692-eddd-4d53-88a5-2d735e33781b"
 
 [compat]
+DataFrames = "1.0"
+DiffEqBase = "6.0"
 Documenter = "0.27"
 Interpolations = "0.13, 0.14"
+MAT = "0.10.4"
+PALEOaqchem = "0.3.1"
 PALEOboxes = "0.20.4, 0.21"
+PALEOcopse = "0.4.5"
 PALEOmodel = "0.15.8"
+Plots = "1.38"
+Preferences = "1.3"
 SIMD = "3.4"
 SnoopPrecompile = "1.0"
+SpecialFunctions = "1.0, 2.0"
+Sundials = "4.0"
 TestEnv = "1.0"
 julia = "1.6"
 
 [extras]
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
+PALEOcopse = "4a6ed817-0e58-48c6-8452-9e9afc8cb508"
 PALEOmodel = "bf7b4fbe-ccb1-42c5-83c2-e6e9378b660c"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+Sundials = "c3572dad-4567-51f8-b174-8c6c989267f4"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Documenter", "Logging", "PALEOmodel", "Test"]
+test = ["DataFrames", "DiffEqBase", "Documenter", "Logging", "PALEOcopse", "PALEOmodel", "Plots", "Sundials", "Test"]

README.md

@@ -6,7 +6,7 @@
 Ocean components for the PALEO biogeochemical model. 
 
 
-**NB: work-in-progress - this repo contains an initial minimal example only to test infrastructure.**
+**NB: work-in-progress - this repo contains initial minimal examples only to test infrastructure.**
 
 ## Installation and running a minimal example
 

docs/src/PALEOocean Reactions.md

@@ -1,24 +1,58 @@
 # PALEOocean Reactions
 
-## Ocean geometry and transport
+## Ocean geometry and circulation transport
 ```@meta
 CurrentModule = PALEOocean.Ocean
 ```
 
 ```@docs
 OceanNoTransport.ReactionOceanNoTransport
+OceanTransport3box.ReactionOceanTransport3box
+OceanTransport6box.ReactionOceanTransport6box
+OceanTransportTMM.ReactionOceanTransportTMM
 ```
 
-## Ocean surface
+## Vertical Transport
+```@docs
+VerticalTransport.ReactionLightColumn
+VerticalTransport.ReactionExportDirect
+VerticalTransport.ReactionExportDirectColumn
+VerticalTransport.ReactionSinkFloat
+```
+
+## Biological Production
+```@docs
+BioProd.ReactionBioProdPrest
+BioProd.ReactionBioProdMMPop
+```
+
+## Ocean surface air-sea flux
 ```@meta
 CurrentModule = PALEOocean.Oceansurface
 ```
 
-### Air-sea flux
 ```@docs
 AirSeaExchange.ReactionAirSea
 AirSeaExchange.ReactionAirSeaO2
 AirSeaExchange.ReactionAirSeaCO2
 AirSeaExchange.ReactionAirSeaCH4
 AirSeaExchange.ReactionAirSeaFixedSolubility
 ```
+
+## Ocean floor burial
+
+```@meta
+CurrentModule = PALEOocean.Oceanfloor
+```
+
+
+###  Carbonate burial
+```@docs
+Burial.ReactionShelfCarb
+Burial.ReactionBurialEffCarb
+```
+
+### Organic carbon and phosphorus burial
+```@docs
+Burial.ReactionBurialEffCorgP
+```

docs/src/collated_examples/PTBClarkson2014/README.md

@@ -0,0 +1,9 @@
+# PTB land-atmosphere-ocean model (Clarkson 2015)
+
+3-box [Sarmiento1984](@cite), [Toggweiler1985](@cite) ocean model, coupled to the COPSE land surface and sediment/crust.
+
+Combination of forcings are as used in [Clarkson2015](@cite).  See paper SI for model description.
+
+**NB: this is an untested PALEO configuration intended to reproduce the Matlab code from the original paper.**
+
+    julia> include("PALEO_examples_PTB3box.jl")

docs/src/collated_examples/mitgcm/README.md

@@ -0,0 +1,39 @@
+# MITgcm transport matrix ocean-only examples
+
+GCM ocean transport test cases using transport matrices in format defined by [Khatiwala2007](@cite)
+
+Examples require a download of Samar Khatiwala's TMM files (for MITgcm, UVic models) as described in https://github.com/samarkhatiwala/tmm where TM files are from http://kelvin.earth.ox.ac.uk/spk/Research/TMM/TransportMatrixConfigs/. The TMMDir key in `examples\LocalPreferences.toml` should then be set to the folder location on the local machine.
+
+Default configurations are set to run for ~10 model yr, single core, single fixed timestep. See comments in .jl files to change run time and enable threading and split-timestep solver (with fast timestep for biogeochemistry and vertical transport).  
+
+Approximate model CPU times below are for a single laptop core (a CPU i5-6300U from ~2015).
+
+## 2.8 degree O2 only abiotic
+
+Minimal test case for ocean transport and air-sea exchange.
+
+Tracers: atmosphere O2, ocean O2
+
+    julia> include("MITgcm_2deg8_abiotic.jl")
+
+Wallclock time: 10.3 s core-1 (model yr)-1  with default timestep = 86400 s (1 day)
+
+## 2.8 degree P, O2 
+
+Minimal test case for biotic ocean.
+
+Tracers: atmosphere O2, ocean O2, P, DOP
+
+    julia> include("MITgcm_2deg8_PO4MMbase.jl")
+
+Wallclock time: 10.0 s core-1 (model yr)-1  with default timestep = 86400 s (1 day)
+
+## 2.8 degree P, O2, S, DIC/TAlk
+
+Minimal test case for a biotic ocean with carbonate chemistry, SO4/H2S and CH4.
+
+Tracers: atmosphere O2, CO2(x2), ocean O2, P, DOC(x2), H2S(x2), SO4(x2), CH4(x2), DIC(x2), TAlk (13 ocean tracers)
+
+    julia> include("MITgcm_2deg8_PO4MMcarbSCH4.jl")
+
+Wallclock time: 27.2 s core-1 (model yr)-1  with default timestep = 86400 s (1 day)

docs/src/collated_examples/ocean3box/README.md

@@ -0,0 +1,31 @@
+# 3 Box Ocean Examples
+
+These examples demonstrate the 3-box [Sarmiento1984](@cite), [Toggweiler1985](@cite) ocean model,
+standalone and coupled to the COPSE land surface and sediment/crust (as used in [Clarkson2015](@cite)).
+
+## Abiotic CO2/DIC only atmosphere-ocean 
+
+    julia> include("PALEO_examples_oaonly_abiotic.jl")
+
+Abiotic atmosphere-ocean with atmosphere CO2, ocean DIC, TAlk. Test case cf Sarmiento & Toggweiler (2007) book, Fig 10.4, p436-7
+
+Commented-out options in file to set k_piston to show effect of default/fast/slow air-sea exchange rates
+
+## Biotic atmosphere-ocean (no weathering or burial)
+
+    julia> include("PALEO_examples_oaonly.jl")
+
+Biotic atmosphere-ocean with atmosphere O2, CO2, ocean P, O2, SO4/H2S, CH4, DIC, TAlk (no weathering or burial).
+
+Use in conjunction with expt='killbio' (disables production at t=0 yr) to
+demonstrate effect of biological pump.
+
+## Open atmosphere-ocean with silicate/carbonate weathering and burial
+
+    julia> include("PALEO_examples_oaopencarb.jl")
+
+Biotic atmosphere-ocean with atmosphere O2, CO2, ocean P, O2, SO4/H2S, CH4, DIC, TAlk
+
+Open atm-ocean carbonate system, with carbonate/silicate weathering input, degassing input, and carbonate burial output
+
+Closed ocean organic carbon, sulphur systems (no burial)

docs/src/index.md

@@ -1,6 +1,6 @@
 # PALEOocean.jl documentation
 
-## Installation and running the model
+## Installation and running the examples
 
 ### Installation
 

docs/src/paleo_references.bib

@@ -1,28 +1,114 @@
-@article{Bergman2004,
-author = {Bergman, N. M. and Lenton, Timothy M and Watson, Andrew J},
-doi = {10.2475/ajs.304.5.397},
-issn = {0002-9599},
-journal = {American Journal of Science},
-month = {may},
-number = {5},
-pages = {397--437},
-title = {{COPSE: A new model of biogeochemical cycling over Phanerozoic time}},
-url = {http://www.ajsonline.org/cgi/doi/10.2475/ajs.304.5.397},
-volume = {304},
-year = {2004}
-}
-
-
-@article{Lenton2018,
-author = {Lenton, Timothy M. and Daines, Stuart J and Mills, Benjamin J.W.},
-doi = {10.1016/j.earscirev.2017.12.004},
-journal = {Earth-Science Reviews},
+@article{Caldeira1993,
+author = {Caldeira, Ken and Rampino, Michael R},
+doi = {10.1029/93PA01163},
+issn = {08838305},
+journal = {Paleoceanography},
+month = {aug},
+number = {4},
+pages = {515--525},
+title = {{Aftermath of the end-Cretaceous mass extinction: Possible biogeochemical stabilization of the carbon cycle and climate}},
+url = {http://doi.wiley.com/10.1029/93PA01163},
+volume = {8},
+year = {1993}
+}
+
+@article{Canfield2006,
+author = {Canfield, Donald E},
+doi = {10.1016/j.gca.2006.07.023},
+journal = {Geochimica et Cosmochimica Acta},
+month = {dec},
+number = {23},
+pages = {5753--5765},
+title = {{Models of oxic respiration, denitrification and sulfate reduction in zones of coastal upwelling}},
+url = {http://linkinghub.elsevier.com/retrieve/pii/S0016703706019120},
+volume = {70},
+year = {2006}
+}
+
+@article{Clarkson2015,
+author = {Clarkson, M. O. and Kasemann, S. A. and Wood, R. A. and Lenton, T. M. and Daines, Stuart J and Richoz, S. and Ohnemueller, F. and Meixner, A. and Poulton, Simon W and Tipper, E. T.},
+doi = {10.1126/science.aaa0193},
+journal = {Science},
+month = {apr},
+number = {6231},
+pages = {229--232},
+title = {{Ocean acidification and the Permo-Triassic mass extinction}},
+url = {https://www.sciencemag.org/lookup/doi/10.1126/science.aaa0193},
+volume = {348},
+year = {2015}
+}
+
+@article{Daines2016,
+author = {Daines, Stuart J and Lenton, Timothy M},
+doi = {10.1016/j.epsl.2015.11.021},
+journal = {Earth and Planetary Science Letters},
+month = {jan},
+pages = {42--51},
+title = {{The effect of widespread early aerobic marine ecosystems on methane cycling and the Great Oxidation}},
+url = {http://linkinghub.elsevier.com/retrieve/pii/S0012821X15007256},
+volume = {434},
+year = {2016}
+}
+
+@article{Hotinski2000,
+author = {Hotinski, Roberta M and Kump, Lee R and Najjar, Raymond G},
+doi = {10.1029/1999PA000408},
+journal = {Paleoceanography},
+number = {3},
+pages = {267},
+title = {{Opening Pandora's Box: The impact of open system modeling on interpretations of anoxia}},
+url = {http://www.agu.org/pubs/crossref/2000/1999PA000408.shtml},
+volume = {15},
+year = {2000}
+}
+
+@article{Khatiwala2007,
+author = {Khatiwala, Samar},
+doi = {10.1029/2007GB002923},
+journal = {Global Biogeochemical Cycles},
+month = {jul},
+number = {3},
+pages = {1--14},
+title = {{A computational framework for simulation of biogeochemical tracers in the ocean}},
+url = {http://www.agu.org/pubs/crossref/2007/2007GB002923.shtml},
+volume = {21},
+year = {2007}
+}
+
+@article{Sarmiento1984,
+author = {Sarmiento, Jorge L and Toggweiler, J. R.},
+doi = {10.1038/308621a0},
+journal = {Nature},
+month = {apr},
+number = {5960},
+pages = {621--624},
+title = {{A new model for the role of the oceans in determining atmospheric P CO2}},
+url = {http://www.nature.com/articles/308621a0},
+volume = {308},
+year = {1984}
+}
+
+
+@incollection{Toggweiler1985,
+author = {Toggweiler, J. R. and Sarmiento, Jorge L},
+booktitle = {The Carbon cycle and atmospheric CO2: Natural variations Archean to present.},
+doi = {10.1029/GM032p0163},
 month = {mar},
-pages = {1--28},
-publisher = {Elsevier B.V},
-title = {{COPSE reloaded: An improved model of biogeochemical cycling over Phanerozoic time}},
-url = {http://linkinghub.elsevier.com/retrieve/pii/S0012825217304117 https://linkinghub.elsevier.com/retrieve/pii/S0012825217304117},
-volume = {178},
-year = {2018}
+pages = {163--184},
+publisher = {Wiley},
+title = {{Glacial to Interglacial Changes in Atmospheric Carbon Dioxide: The Critical Role of Ocean Surface Water in High Latitudes}},
+url = {http://doi.wiley.com/10.1029/GM032p0163},
+volume = {1},
+year = {1985}
 }
 
+
+@inproceedings{Watson1995,
+author = {Watson, Andrew J},
+booktitle = {Upwelling in the ocean: Modern processes and ancient records},
+editor = {Summerhayes, CP},
+pages = {321--336},
+publisher = {Wiley},
+title = {{Are upwelling zones sources or sinks of CO2?}},
+year = {1995}
+}