Skip to content

Commit

Permalink
Merge pull request #118 from OMS-NetZero/v2.1.1
Browse files Browse the repository at this point in the history
Development branch for v2.1.1
  • Loading branch information
chrisroadmap authored Sep 26, 2023
2 parents 4528252 + 39ba167 commit 9e88f2f
Show file tree
Hide file tree
Showing 15 changed files with 206 additions and 120 deletions.
4 changes: 4 additions & 0 deletions CHANGELOG.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ Changelog
v2.1.1
------

(`#118 <https://github.com/OMS-NetZero/FAIR/pull/118>`_) Development branch merged in

(`#130 <https://github.com/OMS-NetZero/FAIR/issues/130>`_) Fixed breaking change in xarray 2023.9.0

(`#127 <https://github.com/OMS-NetZero/FAIR/pull/127>`_) Add a calibrated, constrained example to the documentation

(`#121 <https://github.com/OMS-NetZero/FAIR/pull/121>`_) Make `FAIR.ghg_forcing_offset` an attribute
Expand Down
6 changes: 3 additions & 3 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -40,16 +40,16 @@ format: ## re-format files

.PHONY: black
black: $(VENV_DIR) ## use black to autoformat code
$(VENV_DIR)/bin/black --target-version py37 $(FILES_TO_FORMAT_PYTHON)
$(VENV_DIR)/bin/black --target-version py311 $(FILES_TO_FORMAT_PYTHON)

isort: $(VENV_DIR) ## format the code
$(VENV_DIR)/bin/isort $(FILES_TO_FORMAT_PYTHON)

virtual-environment: $(VENV_DIR) ## update venv, create a new venv if it doesn't exist
$(VENV_DIR): setup.py
[ -d $(VENV_DIR) ] || python3 -m venv $(VENV_DIR)
[ -d $(VENV_DIR) ] || python3.11 -m venv $(VENV_DIR)

$(VENV_DIR)/bin/pip install --upgrade 'pip>=20.3'
$(VENV_DIR)/bin/pip install --upgrade pip
$(VENV_DIR)/bin/pip install wheel
$(VENV_DIR)/bin/pip install -e .[dev]

Expand Down
97 changes: 97 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
[![image](https://github.com/OMS-NetZero/FAIR/actions/workflows/checks.yml/badge.svg)](https://github.com/OMS-NetZero/FAIR/actions)
[![image](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/OMS-NetZero/FAIR/master?filepath=examples/basic_run_example.ipynb)
[![Documentation Status](https://readthedocs.org/projects/fair/badge/?version=latest)](http://fair.readthedocs.io/en/latest/?badge=latest)
[![image](https://zenodo.org/badge/DOI/10.5281/zenodo.1247898.svg)](https://doi.org/10.5281/zenodo.1247898)
[![image](https://codecov.io/gh/OMS-NetZero/FAIR/branch/master/graph/badge.svg)](https://codecov.io/gh/OMS-NetZero/FAIR)
[![image](https://img.shields.io/pypi/v/fair)](https://pypi.org/project/fair/) [![Anaconda-Server Badge](https://anaconda.org/chrisroadmap/fair/badges/version.svg)](https://anaconda.org/chrisroadmap/fair)

# FaIR

FaIR (the Finite-amplitude Impulse-Response) climate model is a simple
climate model, or *emulator*, useful for producing global mean
temperature projections from a wide range of emissions or prescribed
forcing scenarios.

## Requirements

- python 3.7+

## Installation

### From the Python Package Index

pip install fair

### From anaconda

conda install -c chrisroadmap fair

### From source

Refer to [the
documentation](https://fair.readthedocs.io/en/latest/install.html)

## Usage

FaIR can be driven by emissions of greenhouse gases (GHGs) and
short-lived forcers (SLCFs), concentrations of GHGs, or effective
radiative forcing (ERF), with different input methods for different
species possible in the same run. If run concentration-driven, emissions
are back-calculated. Custom GHGs and SLCFs can be defined, and all
components are optional allowing experiments such as pulse-response
analyses to single forcers or gathering up non-CO~2~ species as an
aggregate forcing.

## Examples

The examples directory contains Jupyter notebooks with some
simple examples showing how to run FaIR and the standalone energy
balance model.

If you want to try this out online, [go
here](https://mybinder.org/v2/gh/OMS-NetZero/FAIR/master?filepath=examples/basic_run_example.ipynb).

## Important: A note about calibrating and constraining

FaIR is naive. It will run whatever climate scenario and climate
configuration you give it. If you violate the laws of physics, FaIR
won\'t stop you. For simple climate models as for complex, garbage in
leads to garbage out. More subtle to spot are those analyses with simple
climate models where the present day warming (or historical) is wrong or
the climate is warming too slowly or too quickly. At least, plot a
historical temperature reconstruction over your results and see if it
looks right.

We have produced IPCC AR6 Working Group 1 consistent probabilistic
ensembles to run with. The calibration data can be obtained
[here](https://doi.org/10.5281/zenodo.7694879). These parameter sets are
calibrated to CMIP6 models, run in a large Monte Carlo ensemble, and
constrained based on observed and assessed climate metrics. For an
example of how to use this calibration data set with SSP emissions, see
[this
example](https://docs.fairmodel.net/en/latest/examples/calibrated_constrained_ensemble.html).
If you\'re writing a paper using FaIR, you should use these. There\'ll
be a paper on this at some point, for now please cite the Zenodo DOI.

## Citation

If you use FaIR in your work, please cite the following references
depending on the version:

- **v2.0+:** Leach, N. J., Jenkins, S., Nicholls, Z., Smith, C. J.,
Lynch, J., Cain, M., Walsh, T., Wu, B., Tsutsui, J., and Allen, M.
R.: FaIRv2.0.0: a generalized impulse response model for climate
uncertainty and future scenario exploration, Geosci. Model Dev., 14,
3007--3036, <https://doi.org/10.5194/gmd-14-3007-2021>, 2021
- **v1.1-v1.6**: Smith, C. J., Forster, P. M., Allen, M., Leach, N.,
Millar, R. J., Passerello, G. A., and Regayre, L. A.: FAIR v1.3: A
simple emissions-based impulse response and carbon cycle model,
Geosci. Model Dev.,
<https://doi.org/10.5194/gmd-11-2273-2018>, 2018.
- **v1.0** (or the concept of the state-dependent impulse-response
function for CO<sub>2</sub>): Millar, R. J., Nicholls, Z. R., Friedlingstein,
P., and Allen, M. R.: A modified impulse-response representation of
the global near-surface air temperature and atmospheric
concentration response to carbon dioxide emissions, Atmos. Chem.
Phys., 17, 7213-7228,
<https://doi.org/10.5194/acp-17-7213-2017>, 2017.
68 changes: 0 additions & 68 deletions README.rst

This file was deleted.

41 changes: 27 additions & 14 deletions docs/examples/basic_run_example.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,24 @@ contains all information about the scenario(s), the forcer(s) we want to
investigate, and any configurations specific to each species and the
response of the climate.

Note
----

The code in this introductory block is explanatory and if you try to
copy and paste it it you’ll get errors. The code in this file is
self-contained below the heading “1. Create FaIR instance” below.
Alternatively, check out the repository from GitHub and run this example
notebook in ``jupyter``. Details
`here <https://docs.fairmodel.net/en/latest/install.html>`__.

Some basics
-----------

A run is initialised as follows:

::

f = FAIR()
f = FAIR()

To this we need to add some information about the time horizon of our
model, forcers we want to run with, their configuration (and the
Expand All @@ -27,38 +40,38 @@ options:

::

f.define_time(2000, 2050, 1)
f.define_scenarios(['abrupt', 'ramp'])
f.define_configs(['high', 'central', 'low'])
f.define_species(species, properties)
f.ghg_method='Myhre1998'
f.define_time(2000, 2050, 1)
f.define_scenarios(['abrupt', 'ramp'])
f.define_configs(['high', 'central', 'low'])
f.define_species(species, properties)
f.ghg_method='Myhre1998'

We generate some variables: emissions, concentrations, forcing,
temperature etc.:

::

f.allocate()
f.allocate()

which creates ``xarray`` DataArrays that we can fill in:

::

fill(f.emissions, 40, scenario='abrupt', specie='CO2 FFI')
...
fill(f.emissions, 40, scenario='abrupt', specie='CO2 FFI')
...

Finally, the model is run with

::

f.run()
f.run()

Results are stored within the ``FAIR`` instance as ``xarray`` DataArrays
or Dataset, and can be obtained such as

::

print(fair.temperature)
print(fair.temperature)

Multiple ``scenarios`` and ``configs`` can be supplied in a ``FAIR``
instance, and due to internal parallelisation is the fastest way to run
Expand Down Expand Up @@ -242,7 +255,7 @@ the properties; but
- ``type`` defines the species type such as CO2, an aerosol precursor,
or volcanic forcing; there’s around 20 pre-defined types in FaIR.
Some can only be defined once in a run, some can have multiple
instances (e.g. ``f-gas``). See ``fair.structure.species`` for a
instances (e.g. ``f-gas``). See ``fair.structure.species`` for a
list.
- ``input_mode``: how the model should be driven with this ``specie``.
Valid values are ``emissions``, ``concentration``, ``forcing`` or
Expand Down Expand Up @@ -451,8 +464,8 @@ future.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This defines how the model responds to a forcing: the default behaviour
is the three-layer energy balance model as described in Cummins et
al. (2020). The number of layers can be changed in ``run_control``.
is the three-layer energy balance model as described in Cummins et al.
(2020). The number of layers can be changed in ``run_control``.

``climate_configs`` is an ``xarray`` Dataset.

Expand Down
7 changes: 7 additions & 0 deletions docs/examples/calibrated_constrained_ensemble.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,13 @@ reproduce both observed climate change since pre-industrial and assessed
climate metrics such as the equilibrium climate sensitivity from the
IPCC Sixth Assessement Report.

**Note**: if you are reading this tutorial online and want to reproduce
the results, you will need one additional file. Grab this from
https://github.com/OMS-NetZero/FAIR/blob/master/examples/data/species_configs_properties_calibration1.1.0.csv.
In Step 5 below, this is read in from the ``data/`` directory relative
to here. This does not apply if you are running this notebook from
Binder or have cloned it from GitHub - it should run out of the box.

The calibrations will be continually updated, as new data for surface
temperature, ocean heat content, external forcing and emissions become
available. For now, we have an IPCC AR6 WG1 version (where observational
Expand Down
2 changes: 1 addition & 1 deletion docs/examples/n-layer-ebm.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ This notebook shows examples of extending the 3-layer energy balance
model to general n.

For the two and three layer cases we’ll take the MLE estimates from
Cummins et al. (2020) for HadGEM2-ES, and we’ll use the GISS forcing.
Cummins et al. (2020) for HadGEM2-ES, and we’ll use the GISS forcing.
Where n > 3 the data is fake.

.. code:: ipython3
Expand Down
46 changes: 23 additions & 23 deletions docs/install.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ Installation
From the Python Package Index (PyPI)
------------------------------------

Probably the easiest way to get up and running::
Requires `python` 3.7+. Probably the easiest way to get up and running.
::

pip install fair


From anaconda
-------------

Expand All @@ -20,44 +20,44 @@ From anaconda
From GitHub
-----------

Download and install
~~~~~~~~~~~~~~~~~~~~
The latest release can be obtained from https://github.com/OMS-NetZero/FAIR/releases as zip or tarball files, or the most current unreleased version can be cloned from https://github.com/OMS-NetZero/FAIR.

To install::

The latest release can be obtained from https://github.com/OMS-NetZero/FAIR/releases as zip or tarball files, or the most current unreleased version can be cloned from https://github.com/OMS-NetZero/FAIR.
pip install -e .[dev]
This will also give access to the notebooks in the `examples` directory, so you can experiment with the model using these as a starting point. For this to work, you should launch notebooks from the same directory in which you install `FAIR` locally.

Developing
~~~~~~~~~~
Guide for developers
--------------------

1. Fork the repository, then clone it to your local disk. `cd` to the `FAIR` directory in your working copy.
1. Navigate to the GitHub repository, fork to your personal account, then clone it to your local disk. `cd` to the `FAIR` directory in your working copy.
2. Create a new branch for your changes::

git checkout -b <branch_name>

3. Optional, but we highly recommend developing FaIR in a virtual environment to keep your base installation of `python` nice and clean.
4. Install `fair` in development mode::
3. The development package includes a Makefile which will set up a virtual environment for you along with other tools, keeping your base installation clean. `python` 3.11 is used for developing FaIR. To set this up, run::

pip install -e .[dev]
make venv

5. Make your changes.
6. Write a test that tests your new feature (in the ``tests`` directory of the repository).
7. Format your code, and run tests locally::
4. Make your code changes.
5. Write a test that tests your new feature (in the ``tests`` directory of the repository).
6. Format your code, and run tests locally::

make format
make checks
make tests
make test
make test_notebooks

If you find errors at this point, they will need fixing before GitHub will allow merging to the `master` branch. Running the test suite ensures that your code change does not break or change existing functionality.
If you find errors at this point, they will need fixing before GitHub will allow merging to the `master` branch. Running the test suite ensures that your code change does not break or change existing functionality. The remote and local tests will also fail if you have not increased the code coverage (basically, if you haven't written a test for your change).

8. Commit and push your changes::
7. Commit and push your changes::

git add <file>
git commit -m "informative commit message"
git push origin <branch_name>

9. Create a pull request on the parent repository to merge in your changes. You will see there's a checklist of processes to go through...
10. One of which is adding a line to `CHANGELOG.rst` with a summary of the changes made.
11. The checks and tests will run using GitHub actions. If all pass, you should be able to submit the pull request for review.
12. If the codeowners are happy, the branch will be merged in.

TODO: Check out the (currently non-existent) contributing guide, but it's basically this.
8. Create a pull request on the parent repository to merge in your changes. You will see there's a checklist of processes to go through...
9. One of which is adding a line to `CHANGELOG.rst` with a summary of the changes made.
10. The checks and tests will run using GitHub actions. If all pass, you should be able to submit the pull request for review.
11. If the codeowners are happy, the branch will be merged in.
Loading

0 comments on commit 9e88f2f

Please sign in to comment.