pyhector¶

pyhector is a Python interface for the simple global climate carbon-cycle model Hector.

pyhector makes the simple climate model Hector easily installable and usable from Python and can for example be used in the analysis of mitigation scenarios, in integrated assessment models, complex climate model emulation, and uncertainty analyses.

Hector is written in C++ and developed at the Pacific Northwest National Laboratory. The model description is published in

Hartin, C. A., Patel, P., Schwarber, A., Link, R. P., and Bond-Lamberty, B. P.: A simple object-oriented and open-source model for scientific and policy analyses of the global climate system – Hector v1.0, Geosci. Model Dev., 8, 939-955, doi:10.5194/gmd-8-939-2015, 2015.

See the Hector repository and wiki for further information.

The Python interface pyhector is developed by Sven Willner and Robert Gieseke.

Pyhector uses pybind11 to wrap Hector’s API. The version of Hector used can be read using Pyhector’s __hector_version__ field.

Installation¶

Prerequisites¶

Hector requires Boost, so to install and use pyhector you need to have the filesystem and system modules of Boost version 1.52 or later installed (see also the Hector build instructions).

On Ubuntu/Debian these can be installed by invoking

sudo apt-get install libboost-filesystem-dev libboost-system-dev

On macOS Boost is available through the Homebrew package manager, it might be advisable to use a Homebrew installed Python for installing pyhector:

brew install boost

Windows is (as Hector) in principle supported but not yet tested for pyhector. Pull request with installation notes for Windows are welcome.

Install using pip¶

You can simply install pyhector from PyPI by invoking

pip install pyhector

Usage¶

This repository also contains a Jupyter Notebook you can run live and experiment with, courtesy of the Binder project. The notebook can be viewed as a static version using nbviewer.

Basic example¶

import pyhector

output = pyhector.run(pyhector.rcp26)

Advanced example¶

import pyhector
from pyhector import rcp26, rcp45, rcp60, rcp85

import matplotlib.pyplot as plt

for rcp in [rcp26, rcp45, rcp60, rcp85]:
    output = pyhector.run(rcp, {"core": {"endDate": 2100}})
    temp = output["temperature.Tgav"]
    # Adjust to 1850 - 1900 reference period
    temp = temp.loc[1850:] - temp.loc[1850:1900].mean()
    temp.plot(label=rcp.name.split("_")[0])
plt.title("Global mean temperature")
plt.ylabel("°C over pre-industrial (1850-1900 mean)")
plt.legend(loc="best")
plt.show()

Development¶

For local development you can clone the repository, update the dependencies and install in a virtual environment with pip.

git clone https://github.com/openclimatedata/pyhector.git --recursive
cd pyhector
python3 -m venv venv
./venv/bin/pip install --editable .

To update pyhector and all submodules you can run

git pull --recurse-submodules
git submodule update --init --recursive
./venv/bin/pip install --editable .

Tests can be run locally with

python setup.py test

Updating the Hector model version used¶

The Hector model source code is included in the pyhector repository as a submodule. To update its version do the following:

If you didn’t clone pyhector recursively:
git submodule update --init
Go into the hector folder and checkout the version to be used (replace VERSIONTAG according to the corresponding version tag):
cd hector git checkout VERSIONTAG
Commit the updated submodule to pyhector:
cd .. git add hector git commit -m
Please do not forget to run the tests with the new version.

How to contribute¶

We welcome contributions to and questions about pyhector. Please report issues or discuss feature requests on pyhector’s issue tracker.

You can also contact the pyhector authors via email (see their websites in the README).

Please also check the Hector repository, documentation and issue tracker as pyhector is only a thin interface around the Hector model:

https://github.com/JGCRI/hector

pyhector.constants¶

Dictionaries components and variables used for mapping categories internally. Auto-generated from Hector headers.

pyhector.default_config¶

A dictionary with Hector’s default configuration parameters. See also the original config file on GitHub. In pyhector this INI-file is represented as a dictionary.

pyhector.emissions¶

A dictionary with mapping from Hector components to emissions used in the respective component.

component	emissions
`C2F6_halocarbon`	`C2F6_emissions`
`C4F10_halocarbon`	`C4F10_emissions`
`CCl4_halocarbon`	`CCl4_emissions`
`CF4_halocarbon`	`CF4_emissions`
`CFC113_halocarbon`	`CFC113_emissions`
`CFC114_halocarbon`	`CFC114_emissions`
`CFC115_halocarbon`	`CFC115_emissions`
`CFC11_halocarbon`	`CFC11_emissions`
`CFC12_halocarbon`	`CFC12_emissions`
`CH3Br_halocarbon`	`CH3Br_emissions`
`CH3CCl3_halocarbon`	`CH3CCl3_emissions`
`CH3Cl_halocarbon`	`CH3Cl_emissions`
`CH4`	`CH4_emissions`
`HCF141b_halocarbon`	`HCF141b_emissions`
`HCF142b_halocarbon`	`HCF142b_emissions`
`HCF143_halocarbon`	`HCF143_emissions`
`HCF22_halocarbon`	`HCF22_emissions`
`HFC125_halocarbon`	`HFC125_emissions`
`HFC134a_halocarbon`	`HFC134a_emissions`
`HFC143a_halocarbon`	`HFC143a_emissions`
`HFC152a_halocarbon`	`HFC152a_emissions`
`HFC227ea_halocarbon`	`HFC227ea_emissions`
`HFC236fa_halocarbon`	`HFC236fa_emissions`
`HFC23_halocarbon`	`HFC23_emissions`
`HFC245fa_halocarbon`	`HFC245fa_emissions`
`HFC32_halocarbon`	`HFC32_emissions`
`HFC4310_halocarbon`	`HFC4310_emissions`
`N2O`	`N2O_emissions`
`OH`	`NOX_emissions`, `CO_emissions`, `NMVOC_emissions`
`SF6_halocarbon`	`SF6_emissions`
`bc`	`BC_emissions`
`halon1211_halocarbon`	`halon1211_emissions`
`halon1301_halocarbon`	`halon1301_emissions`
`halon2402_halocarbon`	`halon2402_emissions`
`oc`	`OC_emissions`
`ozone`	`NOX_emissions`, `CO_emissions`, `NMVOC_emissions`
`simpleNbox`	`ffi_emissions`, `luc_emissions`
`so2`	`SO2_emissions`

pyhector.output¶

A dictionary with Hector’s available output variables:

output = {
    'C2F6_halocarbon.hc_concentration': {
        'component': 'C2F6_halocarbon',
        'description': 'C2F6 concentration',
        'unit': 'pptv',
        'variable': 'hc_concentration'
    },
    [...]

component	variable	description	unit
`C2F6_halocarbon`	`hc_concentration`	C2F6 concentration	`pptv`
`CCl4_halocarbon`	`hc_concentration`	CCl4 concentration	`pptv`
`CF4_halocarbon`	`hc_concentration`	CF4 concentration	`pptv`
`CFC113_halocarbon`	`hc_concentration`	CFC113 concentration	`pptv`
`CFC114_halocarbon`	`hc_concentration`	CFC114 concentration	`pptv`
`CFC115_halocarbon`	`hc_concentration`	CFC115 concentration	`pptv`
`CFC11_halocarbon`	`hc_concentration`	CFC11 concentration	`pptv`
`CFC12_halocarbon`	`hc_concentration`	CFC12 concentration	`pptv`
`CH3Br_halocarbon`	`hc_concentration`	CH3Br concentration	`pptv`
`CH3CCl3_halocarbon`	`hc_concentration`	CH3CCl3 concentration	`pptv`
`CH3Cl_halocarbon`	`hc_concentration`	CH3Cl concentration	`pptv`
`CH4`	`CH4`	CH4 concentration	`ppbv CH4`
`HCF141b_halocarbon`	`hc_concentration`	HFC141b concentration	`pptv`
`HCF142b_halocarbon`	`hc_concentration`	HFC142b concentration	`pptv`
`HCF22_halocarbon`	`hc_concentration`	HFC22 concentration	`pptv`
`HFC125_halocarbon`	`hc_concentration`	HFC125 concentration	`pptv`
`HFC134a_halocarbon`	`hc_concentration`	HFC134a concentration	`pptv`
`HFC143a_halocarbon`	`hc_concentration`	HFC143a concentration	`pptv`
`HFC227ea_halocarbon`	`hc_concentration`	HFC227ea concentration	`pptv`
`HFC23_halocarbon`	`hc_concentration`	HFC23 concentration	`pptv`
`HFC245fa_halocarbon`	`hc_concentration`	HFC245fa concentration	`pptv`
`HFC32_halocarbon`	`hc_concentration`	HFC32 concentration	`pptv`
`HFC4310_halocarbon`	`hc_concentration`	HFC4310 concentration	`pptv`
`N2O`	`N2O`	N2O concentration	`ppbv N2O`
`OH`	`TAU_OH`	OH lifetime	`Years`
`SF6_halocarbon`	`hc_concentration`	SF6 concentration	`pptv`
`forcing`	`FBC`	radiative forcing from BC	`W/m2`
`forcing`	`FC2F6`	radiative forcing from C2F6	`W/m2`
`forcing`	`FCCl4`	radiative forcing from CCl4	`W/m2`
`forcing`	`FCF4`	radiative forcing from CF4	`W/m2`
`forcing`	`FCFC11`	radiative forcing from CFC11	`W/m2`
`forcing`	`FCFC113`	radiative forcing from CFC113	`W/m2`
`forcing`	`FCFC114`	radiative forcing from CFC114	`W/m2`
`forcing`	`FCFC115`	radiative forcing from CFC115	`W/m2`
`forcing`	`FCFC12`	radiative forcing from CFC12	`W/m2`
`forcing`	`FCH3Br`	radiative forcing from CH3Br	`W/m2`
`forcing`	`FCH3CCl3`	radiative forcing from CH3CCl3	`W/m2`
`forcing`	`FCH3Cl`	radiative forcing from CH3Cl	`W/m2`
`forcing`	`FCH4`	radiative forcing from CH4	`W/m2`
`forcing`	`FCO2`	radiative forcing from CO2	`W/m2`
`forcing`	`FH2O`	radiative forcing from H2O	`W/m2`
`forcing`	`FHCF141b`	radiative forcing from HCF141b	`W/m2`
`forcing`	`FHCF142b`	radiative forcing from HCF142b	`W/m2`
`forcing`	`FHCF22`	radiative forcing from HCF22	`W/m2`
`forcing`	`FHFC125`	radiative forcing from HFC125	`W/m2`
`forcing`	`FHFC134a`	radiative forcing from HFC134a	`W/m2`
`forcing`	`FHFC143a`	radiative forcing from HFC143a	`W/m2`
`forcing`	`FHFC227ea`	radiative forcing from HFC227ea	`W/m2`
`forcing`	`FHFC23`	radiative forcing from HFC23	`W/m2`
`forcing`	`FHFC245fa`	radiative forcing from HFC245fa	`W/m2`
`forcing`	`FHFC32`	radiative forcing from HFC32	`W/m2`
`forcing`	`FHFC4310`	radiative forcing from HFC4310	`W/m2`
`forcing`	`FN2O`	radiative forcing from N2O	`W/m2`
`forcing`	`FO3`	radiative forcing from O3	`W/m2`
`forcing`	`FOC`	radiative forcing from OC	`W/m2`
`forcing`	`FSF6`	radiative forcing from SF6	`W/m2`
`forcing`	`FSO2`	radiative forcing from SO2	`W/m2`
`forcing`	`FSO2d`	radiative forcing from SO2d	`W/m2`
`forcing`	`FSO2i`	radiative forcing from SO2i	`W/m2`
`forcing`	`Fhalon1211`	radiative forcing from halon1211	`W/m2`
`forcing`	`Fhalon1301`	radiative forcing from halon1301	`W/m2`
`forcing`	`Fhalon2402`	radiative forcing from halon2402	`W/m2`
`forcing`	`Ftalbedo`	radiative forcing from terrestrial albedo forcing	`W/m2`
`forcing`	`Ftot`	total global radiative forcing	`W/m2`
`forcing`	`Fvol`	volcanic radiative forcing	`W/m2`
`halon1211_halocarbon`	`hc_concentration`	halon1211 concentration	`pptv`
`halon1301_halocarbon`	`hc_concentration`	halon1301 concentration	`pptv`
`halon2402_halocarbon`	`hc_concentration`	halono2402 concentration	`pptv`
`ocean`	`CO3_HL`	carbonate ion - high latitude	`umol/kg`
`ocean`	`CO3_LL`	carbonate ion - low latitude	`umol/kg`
`ocean`	`DIC_HL`	dissolved inorganic carbon - high latitude	`umol/kg`
`ocean`	`DIC_LL`	dissolved inorganic carbon - low latitude	`umol/kg`
`ocean`	`HL_DO_Cflux`	flux of carbon from the high latitude to the deep ocean	`Pg C/yr`
`ocean`	`OmegaAr_HL`	aragnoite saturation - high latitude	`(unitless)`
`ocean`	`OmegaAr_LL`	aragnoite saturation - low latitude	`(unitless)`
`ocean`	`OmegaCa_HL`	calcite saturation - high latitude	`(unitless)`
`ocean`	`OmegaCa_LL`	calcite saturation - low latitude	`(unitless)`
`ocean`	`PCO2_HL`	partial pressure CO2 - high latitude	`uatm`
`ocean`	`PCO2_LL`	partial pressure CO2 - low latitude	`uatm`
`ocean`	`Revelle_HL`	Revelle factor - high latitude	`(unitless)`
`ocean`	`Revelle_LL`	Revelle factor - low latitude	`(unitless)`
`ocean`	`Temp_HL`	ocean surface temperature - high latitude	`degC`
`ocean`	`Temp_LL`	ocean surface temperature - low latitude	`degC`
`ocean`	`atm_ocean_flux`	total atmosphere ocean flux	`Pg C/yr`
`ocean`	`atm_ocean_flux_HL`	flux of carbon between the atmosphere and high latitude surface box	`Pg C/yr`
`ocean`	`atm_ocean_flux_LL`	flux of carbon between the atmosphere and low latitude surface box	`Pg C/yr`
`ocean`	`carbon_DO`	carbon pool - deep ocean	`Pg C`
`ocean`	`carbon_HL`	carbon pool - high latitude surface ocean	`Pg C`
`ocean`	`carbon_IO`	carbon pool - intermediate ocean	`Pg C`
`ocean`	`carbon_LL`	carbon pool - low latitude surface ocean	`Pg C`
`ocean`	`ocean_c`	total ocean carbon pool	`Pg C`
`ocean`	`ocean_timesteps`	time step the ocean operates on	`(unitless)`
`ocean`	`pH_HL`	pH - high latitude	`pH`
`ocean`	`pH_LL`	pH - low latitude	`pH`
`ozone`	`O3`	tropospheric ozone concentration	`DU O3`
`simpleNbox`	`Ca`	atmospheric CO2 concentration	`ppmv CO2`
`simpleNbox`	`atm_land_flux`	flux of carbon between the atmosphere and the ocean	`Pg C/yr`
`simpleNbox`	`atmos_c`	total atmospheric carbon pool	`Pg C`
`simpleNbox`	`atmos_c_residual`	the difference between calculated CO2 and and prescribed CO2 when running with prescribed CO2 concentrations	`Pg C`
`simpleNbox`	`detritus_c`	total detritus carbon pool	`Pg C`
`simpleNbox`	`earth_c`	total carbon pool - used a mass balance check	`Pg C`
`simpleNbox`	`npp`	net primary production (land)	`Pg C/yr`
`simpleNbox`	`rh`	heterotrophic respiration (land)	`Pg C/yr`
`simpleNbox`	`soil_c`	total soil carbon pool	`Pg C`
`simpleNbox`	`veg_c`	total vegetation carbon pool	`Pg C`
`temperature`	`Tgav`	global atmospheric temperature anomaly	`degC`
`temperature`	`Tgaveq`	temperature change without accounting for ocean heat uptake	`degC`

pyhector.units¶

A dictionary with emissions categories and their associated units.

emissions	unit
`BC_emissions`	`Mt/yr`
`C2F6_emissions`	`kt/yr`
`CCl4_emissions`	`kt/yr`
`CF4_emissions`	`kt/yr`
`CFC113_emissions`	`kt/yr`
`CFC114_emissions`	`kt/yr`
`CFC115_emissions`	`kt/yr`
`CFC11_emissions`	`kt/yr`
`CFC12_emissions`	`kt/yr`
`CH3Br_emissions`	`kt/yr`
`CH3CCl3_emissions`	`kt/yr`
`CH3Cl_emissions`	`kt/yr`
`CH4_emissions`	`MtCH4/yr`
`CO_emissions`	`MtCO/yr`
`HCF141b_emissions`	`kt/yr`
`HCF142b_emissions`	`kt/yr`
`HCF22_emissions`	`kt/yr`
`HFC125_emissions`	`kt/yr`
`HFC134a_emissions`	`kt/yr`
`HFC143a_emissions`	`kt/yr`
`HFC227ea_emissions`	`kt/yr`
`HFC23_emissions`	`kt/yr`
`HFC245fa_emissions`	`kt/yr`
`HFC32_emissions`	`kt/yr`
`HFC4310_emissions`	`kt/yr`
`N2O_emissions`	`MtN2O-N/yr`
`NMVOC_emissions`	`Mt/yr`
`NOX_emissions`	`MtN/yr`
`OC_emissions`	`Mt/yr`
`SF6_emissions`	`kt/yr`
`SO2_emissions`	`Gg/yr`
`ffi_emissions`	`GtC/yr`
`halon1211_emissions`	`kt/yr`
`halon1301_emissions`	`kt/yr`
`halon2402_emissions`	`kt/yr`
`luc_emissions`	`GtC/yr`

Changelog¶

2.5.0.2¶

update to Hector 2.5.0 (https://github.com/JGCRI/hector/releases/tag/rcmip-tier1)
fix install errors with newer setuptools

2.4.0.1¶

fix for pybind issue on ARM

2.4.0.0¶

update to Hector 2.4.0 (revamped multi-biome system)

2.3.1.0¶

update to Hector 2.3.1

2.3.0.0¶

fix __hector_version__ field
update to Hector 2.3.0 (https://github.com/JGCRI/hector/releases/tag/v2.3.0)

2.2.2.0¶

update to Hector 2.2.2 (https://github.com/JGCRI/hector/releases/tag/v2.2.2)
includes new output variables from Hector 2.2.1

2.2.0.1¶

fix installation

2.2.0.0¶

update to Hector 2.2.0 (https://github.com/JGCRI/hector/releases/tag/v2.2.0)
add a new parameter “VOLCANIC_SCALE”

2.1.0.0¶

switch to new versioning scheme: Hector version + ascending number denoting changes in Pyhector

2.1.0a¶

update to Hector 2.1.0 (https://github.com/JGCRI/hector/releases/tag/v2.1.0)
switch to new versioning scheme: Hector version + ascending letters denoting changes in Pyhector

2.1.3¶

C++ bindings are using pybind11 now (making the hector-wrapper obsolete)
drop offical support for 2.7 and 3.4 (not tested anymore)
new in Pyhector: shutdown, run(until=None), __hector_version__, clear_observables, reset

2.0.1¶

updated to Hector 2.0.1 (license clarification)

2.0.0¶

updated to Hector 2.0.0
directly works with Hector, no fork needed anymore
see the Hector changelog for details (https://github.com/JGCRI/hector/releases)

0.9.0¶

include more forcings as output variables

0.8.1¶

updated underlying Hector version to include the fix for halo carbon double counting (https://github.com/JGCRI/hector/pull/201)

0.7.0¶

overhauled docs to include tables for configuration dicts
fixed start_date bug when not setting observables

0.6.0¶

explicitly state C++11 in setup.py
enable spinup output to be readable

0.5.2¶

config dictionary can also take a Pandas series instead of list of tuples for time series
add function to export scenarios as CSV files (in Hector format)
add API docs using Sphinx and Readthedocs

0.4.0¶

return parameters only when requested in run function
allow different configuration objects to be used

0.3.0¶

default config object uses Python numbers or booleans instead of strings, units can be included as tuples like (35.0, 'pptv') and time series as lists of tuples like 'N2ON_emissions': [(1765, 11), (2000, 8), (2300, 8)]

0.2.4¶

first PyPI beta release