Update documentation (#67)

* Fixed emissions plot by masked mitigation when it vanishes.

* Increased default geoengineering cost.

* Updated default Tgoal to 1.5ºC

* Added forcing plot and make default plots "wedges"

* Updated adaptation parameterization

Adaptation now acts to remove a fraction of the *baseline* temperature.

Adaptation costs have been quadrupled to reflect the fact that baseline temps are typically higher than controlled temps.

Updated default optimization "obj_option" to adaptive temperature and reduced default temp_goal to 1.1

Slightly changed adaptation cost

* Increment version

* Added repo link to project.toml

* transfered ownership from hdrake to ClimateMARGO.jl (shouldn't be breaking)

* Updated schematic w/ new adaptation

* rename and fix future mask

* fixed overshoot (for adaptived temp)

Had a typo where the temp_goal was still being used as temp_overshoot for the "adaptive_temp" option.

* Fixed a bug in the 1D and 2D optimization examples.

* Updating documentation a bit

Project.toml

@@ -1,6 +1,6 @@
 name = "ClimateMARGO"
 uuid = "d3f62095-a717-45bf-aadc-ac9dfc258fa6"
-version = "0.2.0"
+version = "0.2.1"
 repo = "https://github.com/ClimateMARGO/ClimateMARGO.jl"
 
 [deps]

configurations/default_params.json

@@ -1 +1 @@
-{"name":"default","domain":{"dt":5.0,"present_year":2020.0,"initial_year":2020.0,"final_year":2200.0},"economics":{"E0":100.0,"γ":0.02,"β":0.0022222222222222222,"ρ":0.02,"Finf":8.5,"mitigate_cost":0.034,"remove_cost":13.0,"geoeng_cost":0.126,"adapt_cost":0.16,"mitigate_init":0.0,"remove_init":0.0,"geoeng_init":0.0,"adapt_init":null,"baseline_emissions":[7.5,8.4375,9.375,10.3125,11.25,12.1875,13.125,14.0625,15.0,15.9375,16.875,17.8125,18.75,19.6875,20.625,21.5625,22.5,20.25,18.0,15.75,13.5,11.25,9.0,6.75,4.5,2.25,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0],"epsilon_cost":0.0,"extra_CO₂":[0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0]},"physics":{"c0":460.0,"T0":1.1,"a":4.977297891066924,"B":1.13,"Cd":106.0,"κ":0.73,"r":0.5}}
+{"name":"default","domain":{"dt":5.0,"present_year":2020.0,"initial_year":2020.0,"final_year":2200.0},"economics":{"E0":100.0,"γ":0.02,"β":0.0022222222222222222,"ρ":0.02,"Finf":8.5,"mitigate_cost":0.034,"remove_cost":13.0,"geoeng_cost":0.126,"adapt_cost":0.18,"mitigate_init":0.0,"remove_init":0.0,"geoeng_init":0.0,"adapt_init":null,"baseline_emissions":[7.5,8.4375,9.375,10.3125,11.25,12.1875,13.125,14.0625,15.0,15.9375,16.875,17.8125,18.75,19.6875,20.625,21.5625,22.5,20.25,18.0,15.75,13.5,11.25,9.0,6.75,4.5,2.25,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0],"epsilon_cost":0.0,"extra_CO₂":[0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0]},"physics":{"c0":460.0,"T0":1.1,"a":4.977297891066924,"B":1.13,"Cd":106.0,"κ":0.73,"r":0.5}}

docs/make.jl

@@ -3,7 +3,7 @@ push!(LOAD_PATH,"../src/")
 using ClimateMARGO
 using Documenter, Literate
 
-const EXAMPLES_DIR = joinpath(@__DIR__, "src/examples_literate")
+const EXAMPLES_DIR = joinpath(@__DIR__, "..", "examples")
 const OUTPUT_DIR   = joinpath(@__DIR__, "src/generated")
 
 print(@__DIR__)
@@ -29,12 +29,12 @@ pages = [
     "Installation instructions" => "installation_instructions.md",
     "Theory" => "theory.md",
     "Examples" => example_pages,
-    "Submodules" => [
-        "Domain" => "Submodules/Domain.md",
-        "Physics" => "Submodules/Physics.md",
-        "Economics" => "Submodules/Economics.md",
-        "Controls" => "Submodules/Controls.md",
-    ],
+    # "Submodules" => [
+    #     "Domain" => "Submodules/Domain.md",
+    #     "Physics" => "Submodules/Physics.md",
+    #     "Economics" => "Submodules/Economics.md",
+    #     "Controls" => "Submodules/Controls.md",
+    # ],
     "Diagnostics" => "diagnostics.md",
     "Optimization" => "optimization.md",
     "Function index" => "function_index.md"
@@ -46,8 +46,9 @@ makedocs(
     authors = "Henri F. Drake",
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", nothing) == "true",
+        collapselevel = 1
     ),
     pages = pages
 )
 
-deploydocs(repo = "github.com/hdrake/ClimateMARGO.jl.git",)
+deploydocs(repo = "github.com/ClimateMARGO/ClimateMARGO.jl.git",)

docs/src/index.md

@@ -2,24 +2,24 @@
 
 A Julia implementation of **MARGO**, an idealized framework for the **O**ptimization of four climate change control strategies: **M**itigation, **A**daptation, **R**emoval of carbon dioxide, and **G**eoengineering by solar radiation management.
 
-ClimateMARGO.jl couples together a very simple model of Earth's physical climate with a very simple economic model of climate damages (and the costs of controls that reduce those damages). Our design philosophy is for the MARGO model to be *as simple as possible* while still producing quasi-realistic climate trajectories over the next few hundred years.
+ClimateMARGO.jl couples together a very simple model of Earth's physical climate with a very simple economic model of climate damages (and the costs of "controls" that reduce those damages). Our design philosophy is that the MARGO model should be *as simple as possible* while still producing quasi-realistic climate trajectories over the next few hundred years.
 
 Compared to more conventional *Integrated Assessment Models (IAMs)*, MARGO is:
-* **Faster**: The algorithm solves convex optimization problems in less than 10 milliseconds (most use cases), meaning the model can be run interactively in real-time and that both large-ensemble, high-dimensional, and stochastic optimizations are all computationally feasible.
+* **Faster**: The algorithm solves convex optimization problems in less than 100 milliseconds (most use cases), meaning the model can be run interactively in real-time and that both large-ensemble, high-dimensional, and stochastic optimizations are all computationally feasible.
 * **More accessible**: The ClimateMARGO.jl package is free to use and is accessible in several different forms depending on the user's programming experience and use case:
   * *An interactive web-app (Coming Soon)* – For code-free interactive exploration of climate storylines (and their sensitivity to model parameters)
-  * *A browser-based binder tutorial* – For users with some programming experience who want to see (and run!) the *ClimateMARGO.jl* source code
+  * *A browser-based binder tutorial* – For users with some programming experience who want to run *ClimateMARGO.jl* themselves.
   * *Importing ClimateMARGO.jl* – For users proficient in Julia who want to use the MARGO model for education or scientific research
-  * *Forking ClimateMARGO.jl* – For users wanting to extend or fundamentally modify the MARGO model for scientific research
+  * *Forking ClimateMARGO.jl* – For users wanting to extend or fundamentally modify the MARGO model source code, e.g. for their own scientific or policy research
 * **More interpretable**: The entire model algorithm is simple enough to be expressed in a single closed-form math equation and is determined by only a handful of intuitive free parameters (see also the MARGO flowchart below).
-* **More transparent**: The MARGO model is developed as an entirely open-source Julia package, *ClimateMARGO.jl*, complete with documentation, in-depth tutorials, and publication-quality example simulations.
+* **More transparent**: The MARGO model is developed as an entirely open-source Julia package, *ClimateMARGO.jl*, complete with documentation, in-depth tutorials, and example applications.
 * **More general**: By including all four of the primary climate controls in the default configuration, more common configurations like "Mitigation-only" experiments are straight-forward to implement by simply turning unwanted features off.
 * **More explicitly value-dependent**: Rather than burying important value-dependent choices in various obscure economic and social parameters, we abstract away many of the complexities to yield a small number of intuitive parameters, which can be easily modified by users.
 * **More extendable**: The modular and interpretable nature of the Julia source implementation means that existing features can be easily modified and new features are easily added.
 
 !!! warning "Don't take MARGO's results too seriously"
-    The extreme simplicity of the MARGO model also means its *quantitative* results should be taken with a large pinch of salt. MARGO should instead be used to explore underlying *patterns* and *relative* climate outcomes.
+    The extreme simplicity of the MARGO model also means its *quantitative* results should be taken with a handful of salt. MARGO should instead be used to explore underlying *patterns* and *relative* climate outcomes.
 
 ## Getting help
 
-If you are interested in using ClimateMARGO.jl or are trying to figure out how to use it, please feel free to ask us questions and get in touch! Please feel free to [open an issue](https://github.com/hdrake/ClimateMARGO.jl/issues/new) if you have any questions, comments, suggestions, etc!
+If you are interested in using ClimateMARGO.jl or are trying to figure out how to use it, please feel free to ask us questions and get in touch! Please feel free to [open an issue](https://github.com/ClimateMARGO/ClimateMARGO.jl/issues/new) if you have any questions, comments, suggestions, etc!

docs/src/installation_instructions.md

@@ -5,23 +5,21 @@ Julia command prompt) to add the package and instantiate/build all dependencies
 
 ```julia
 julia>]
-(v1.3) pkg> add ClimateMARGO
-(v1.3) pkg> instantiate
+(v1.5) pkg> add ClimateMARGO
+(v1.5) pkg> instantiate
 ```
 
-We recommend installing ClimateMARGO with the built-in Julia package manager, because this installs a stable, tagged
-release. ClimateMARGO.jl can be updated to the latest tagged release from the package manager by typing
-
+We recommend installing ClimateMARGO with the built-in Julia package manager, because this installs a stable, tagged release. ClimateMARGO.jl can be updated to the latest tagged release from the package manager by typing
 ```julia
-(v1.3) pkg> update ClimateMARGO
+(v1.5) pkg> update ClimateMARGO
 ```
 
 In some cases, it may be useful to install versions of ClimateMARGO from a development branch named [Branch name], which can be done by typing
 ```julia
-(v1.3) pkg> add https://github.com/hdrake/ClimateMARGO.jl#[Branch name]
+(v1.5) pkg> add https://github.com/ClimateMARGO/ClimateMARGO.jl#[Branch name]
 ```
 
-At this time, updating should be done with care, as ClimateMARGO is under rapid development and breaking changes to the user API occur often. But if anything does happen, please open an issue!
+At this time (and until ClimateMARGO v1.0.0), updating should be done with care, as ClimateMARGO is under rapid development and breaking changes to the user API occur often. But if anything does happen, please open an issue!
 
-!!! warn "Use Julia 1.3 or newer"
-    ClimateMARGO requires at least Julia v1.3 to run.
+!!! warn "Use Julia 1.5 or newer"
+    ClimateMARGO requires at least Julia v1.5 to run.

docs/src/theory.md

@@ -1,8 +1,10 @@
 # Theory
 
+The theory below formulates the simple default configuration of the MARGO model. We invite users to modify these equations or add additional ones, as required by their use cases.
+
 ## The causal chain of climate suffering
 
-It is helpful to conceptualize climate change as a four step process that connects the human-caused emissions of greenhouse gases (GHGs) to the eventual climate suffering (or damages) that they cause. This four-step framing reflects the four major human controls (or controls) which can sever these links to reduce climate suffering: **M**itigation of GHG emissions (e.g. switching away from fossil fuels), **R**emoval of carbon dioxide from the atmosphere (e.g. by planting trees or storing biofuel emissions underground), **G**eoengineering by solar radiation management (e.g. injecting sulfate aerosols into the stratosphere to reduce incoming sunlight), or **A**dapting to the changed climate (e.g. relocating coastal communities displaced by rising seas or expanding indoor air condititiong to fight off intensifying heat waves).
+It is helpful to conceptualize climate change as a four step process that connects the human-caused emissions of greenhouse gases (GHGs) to the eventual climate suffering (or damages) that they cause. This four-step framing reflects the four major human actions (or controls) which can sever these links to reduce climate suffering: **M**itigation of GHG emissions (e.g. switching away from fossil fuels), **R**emoval of carbon dioxide from the atmosphere (e.g. by planting trees or storing biofuel emissions underground), **G**eoengineering by solar radiation management (e.g. injecting sulfate aerosols into the stratosphere to reduce incoming sunlight), or **A**dapting to the changed climate (e.g. relocating coastal communities displaced by rising seas or expanding indoor air condititiong to fight off intensifying heat waves).
 
 ```math
 \text{Emissions}\,
@@ -16,26 +18,26 @@ It is helpful to conceptualize climate change as a four step process that connec
 \text{Suffering}.
 ```
 
-Letting climate change run rampant would clearly cause a lot of suffering; however, climate controls that keep climate change under control are not free either. MARGO empowers users to explore the trade-offs between climate controls and climate suffering by employing an optimization framework commonly used in the climate-economics community. In this section, we develop a simple theory– a set of mathematical equations– which capture the key aspects of the entire causal chain of climate damages.
+Letting climate change run rampant would clearly cause a lot of suffering; however, climate controls that slow or stop climate change are not free either. MARGO empowers users to explore the trade-offs between climate controls and climate suffering by employing an optimization framework commonly used in the climate-economics community. In this section, we develop a simple theory– a set of mathematical equations– which capture the key aspects of the entire causal chain of climate damages.
 
 ![MARGO schematic](MARGO_schematic.png)
 
 !!! ukw "Tuning MARGO's free parameters"
-    We have attempted to make reasonable choices for the default values of MARGO's parameters in the equations below. Some of these, such as the climate physics variables, are well justified based on the best climate science research; others, such as the socio-economic parameters, are chosen based on our values (or those represented in the academic climate change literature). We encourage users to question these choices and plug their own values into ClimateMARGO. If you feel strongly that we should change some of the default values included in the model code, please reach out to us by [opening an issue](https://github.com/hdrake/ClimateMARGO.jl/labels/criticism) on Github.
+    We have attempted to make reasonable choices for the default values of MARGO's parameters in the equations below. Some of these, such as the climate physics variables, are well justified based on the best climate science research; others, such as the socio-economic parameters, are chosen based on our values (or those represented in the academic climate change literature). We encourage users to question these choices and plug their own values into ClimateMARGO. If you feel strongly that we should change some of the default values included in the model code, please reach out to us by [opening an issue](https://github.com/ClimateMARGO/ClimateMARGO.jl/labels/criticism) on Github.
 
 ## Greenhouse gas emissions
 
-While greenhouse gases include more than just the dominant carbon dioxide (CO``_{2}``), it simplifies things greatly to just bundle these into an equivalent concentration CO``_{2e}``. In MARGO, CO``_{2e}`` is emitted at a rate ``q(t)``, with only a fraction ``r = 50\%`` remaining in the atmosphere after a few years, net of uptake by the ocean and terrestrial biosphere.
+Since carbon dioxide (CO``_{2}``) is the dominant anthropogenic greenhouse gas, it dramatically simplifies the model to bundle all of the other gases into an equivalent concentration CO``_{2e}``, which produces an equivalent greenhouse effect. In MARGO, CO``_{2e}`` is emitted at a rate ``q(t)``, with only a fraction ``r`` remaining in the atmosphere after a few years, net of uptake by the ocean and terrestrial biosphere.
 
 !!! note "Climate control: Emissions mitigation"
     GHG emissions are reduced by a **M**itigation factor ``(1-M(t))``, becoming ``q(t)(1-M(t))``, where ``M(t)`` varies between 0% (high-emissions baseline) and 100% (full decarbonization).
 
 ## Greenhouse gas concentrations
 
-CO``_{2e}`` continues to accumulate in the atmosphere and its concentrations ``c(t)= c_{0} + \int_{t_{0}}^{t} rq(t)\text{ d}t\,`` will increase as long as the emissions ``q(t)`` are greater than zero.
+CO``_{2e}`` continues to accumulate in the atmosphere and its concentrations ``c(t)= c_{0} + \int_{t_{0}}^{t} rq(t')\text{ d}t' \,`` will increase as long as the emissions ``q(t)`` are greater than zero.
 
 !!! note "Climate control: Carbon dioxide removal"
-    **R**emoval of CO``_{2e}``, in contrast to mitigation, is de-coupled from instantaneous emissions and is expressed as the percentage of 2020 baseline emissions that are removed from the atmosphere in a given year, ``q_{0}R(t)``. A maximal value of ``R=100\%`` corresponds to removing ``30`` GtCO``_{2e}`` per year, which is roughly equal to a recent upper-bound estimate of the global potential for negative emission technologies.
+    **R**emoval of CO``_{2e}``, in contrast to mitigation, is de-coupled from instantaneous emissions and is expressed as the percentage of 2020 baseline emissions that are removed from the atmosphere in a given year, ``q_{0}R(t)``. A value of ``R=100\%`` corresponds to removing ``60`` GtCO``_{2e}`` per year, which is roughly equal to a recent upper-bound estimate of the global potential for negative emission technologies.
 
     A useful diagnostic quantity is the effective emissions
     ```math
@@ -72,13 +74,13 @@ where ``T_{0} = 1.1``°C is the present warming relative to preindustrial and ``
 Anthropogenic warming causes a myriad of climate impacts, which result suffering (expressed in an economic model as a loss in welfare or monetary damages) that increase non-linearly with temperature, ``D = \beta T^{2}``, where the damage parameter ``\beta`` is tuned such that a warming of ``3``°C results in damages of the ``2\%`` of Gross World Product (GWP), consistent with DICE in the limit of non-catastrophic warming.
 
 !!! note "Climate control: Adaptation"
-    **A**daptation to climate impacts acts to reduce damages by a fraction ``A(t)``. Since some climate impacts are likely impossible to adapt to, we assume that adaptation can at most reduce climate damages by ``A < 40\%``. The controlled damages are thus given by
+    **A**daptation to climate impacts acts to reduce damages by a fraction ``A`` of the baseline damages. Since some climate impacts are likely impossible to adapt to, we assume by default that adaptation can at most reduce climate damages by ``A \ll 100\%``. The controlled damages are thus given by
     ```math
-        D_{M,R,G,A} = \beta (T_{M,R,G})^{2} (1-A(t)).
+        D_{M,R,G,A} = \beta (T_{M,R,G} - A(t) T)^{2}.
     ```
-    Although adaptation does not affect the planetary temperature directly, it is useful to consider an "adapted temperature" ``T_{M,R,G,A}`` which yields controlled damages equivalent to the fully-controlled damages ``\beta (T_{M,R,G,A})^{2} = \beta (T_{M,R,G})^{2} (1-A)`` and is defined
+    Although adaptation does not affect the planetary temperature directly, it is useful to consider an "adapted temperature" ``T_{M,R,G,A}`` which yields controlled damages equivalent to the fully-controlled damages ``\beta (T_{M,R,G,A})^{2} = \beta (T_{M,R,G} - AT)^{2}`` and is defined
     ```math
-        T_{M,R,G,A} \equiv T_{M,R,G} \sqrt{(1-A)}.
+        T_{M,R,G,A} \equiv T_{M,R,G} - A T.
     ```
 
 ## The costs and benefits of climate control

docs/src/examples_literate/default_optimization.jl → examples/default_optimization.jl

@@ -9,6 +9,7 @@ using ClimateMARGO.Optimization
 
 # Load the pre-defined default MARGO parameters, which are described by the ClimateModelParameters struct
 params = deepcopy(ClimateMARGO.IO.included_configurations["default"])
+
 # Create a MARGO instance based on these parameters
 m = ClimateModel(params);
 
@@ -23,7 +24,7 @@ m.controls
 # The optimization can be slow the first time since it has to compile.
 # Let's re-initialize the model and see how fast it runs now that the the optimization routine has been precompiled.
 m = ClimateModel(params);
-@time optimize_controls!(m, obj_option = "net_benefit");
+@time optimize_controls!(m);
 
 # ## Visualizing the results