All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

The changes listed in this file are categorised as follows:

  • Added: new features

  • Changed: changes in existing functionality

  • Deprecated: soon-to-be removed features

  • Removed: now removed features

  • Fixed: any bug fixes

  • Security: in case of vulnerabilities.

v2.1.3 - 2021-09-07


  • (#332) Fix check for whether MAGICC logged a warning/error

  • (#331) Hotfix CI to handle new pandas version

v2.1.2 - 2021-07-17


  • (#328) Adds additional spelling options for YEARS header in .SCEN files

v2.1.1 - 2021-07-02


  • (#327) Reran notebook to include updated documentation from scmdata

v2.1.0 - 2021-07-01


  • (#317) Support for ozone (effective) radiative forcing output


  • (#317) convert_magicc7_to_openscm_variables() such that inverse mapping for e.g. “Emissions|CO2” is now “CO2T_EMIS” rather than “CO2_EMIS” (similarly for CH4 and N2O). This change ensures that the correct MAGICC output file is requested if “Emissions|CO2” are requested as output.

v2.0.0 - 2021-01-20


  • (#317) Add support for more MAGICC7 output variables

  • (#315) Include links to AR6 region abbreviations if they are written in .MAG files

  • (#314) Add AR6 regions to the list of known regions

  • (#313) Add tests for global-only binary files written with out_binary_format=2

  • (#305) Added functionality to read new MAGICC binary format which includes units

  • (#238) Add documentation for handling of World region in .SCEN7 files


  • (#277) Add MAGICC7 compact output file readers

  • (#288) Add, which allows fast reading of metadata from a .MAG file

  • (#282) Expose MAGICCBase.get_tcr_ecs_from_diagnosis_results method

  • (#274) Add better readers and writers for .DAT files

  • (#272) Add support for new THISFILE_TIMESERIESTYPE in .MAG files

  • (#259) Added strict option for downgrading configuration exceptions to warnings

  • (#256) Capture stderr output from MAGICC7 and above (not available in MAGICC6)

  • (#253) Add support for out_dynamic_vars parameter

  • (#250) Add support for .MAG files

  • (#229) Add more robust tests of io, in particular that column order and spacing in files is preserved

  • (#226) Add SURFACE_TEMP.IN writer, closing #211

  • (#224) Add INVERSEEMIS.OUT reader

  • (#208) Add set_zero_config(). Also adds scenarios module, tidies up the notebooks and adds a notebook showing how to run in different modes.

  • (#208) Add pymagicc.scenarios module

  • (#208) Tidy up the notebooks and add a notebook showing how to run in different modes.

  • (#187) Added which simplifies joining/merging scenarios to create custom scenarios

  • (#185) Added ability to read RCP files from as requested in #176

  • (#183) Added ability to read MHALO files (see #182)

  • (#180) Added reference which explains MAGICC’s variables to docs

  • (#170) Added pyam as a dependency and gave an example of how to integrate with it

  • (#168) Added MAGICC7 compatibility

  • (#162) Added basic tests of integration with MAGICC binaries

  • (#139) Added the ability to read all MAGICC output files/throw an explanatory error with

  • (#79) Confirmed that keeping track of config state works and added example to TCR/ECS diagnosis notebook

  • (#102) Added ability to read and write SCEN7 files

  • (#108) Added ability to read all files in MAGICC6 run folder (pymagicc/MAGICC6/run) to a common format

    • Note that this change means that only files which follow the MAGICC6 or MAGICC7 naming convention are supported. These are very similar to MAGICC5 except that emissions files must be named in the form *.SCEN, *.SCEN7 or *EMISX.IN where X is I if the file contains fossil and industrial emissions and B if the file contains agriculture, land-use and land-use change emissions. The suffixes FOSSIL&IND and LANDUSE are no longer supported.

    • The renamed files are

      • pymagicc/MAGICC6/run/EDGAR_NOX_EMIS_LANDUSE.IN => pymagicc/MAGICC6/run/EDGAR_NOXB_EMIS.IN

      • pymagicc/MAGICC6/run/EDGAR_NOX_EMIS_FOSSIL&IND.IN => pymagicc/MAGICC6/run/EDGAR_NOXI_EMIS.IN


      • pymagicc/MAGICC6/run/MARLAND_CO2_EMIS_FOSSIL&IND.IN => pymagicc/MAGICC6/run/MARLAND_CO2I_EMIS.IN

    • Deleted pymagicc/MAGICC6/run/HIST_SEALEVEL_CHURCHWHITE2006_RF.IN as it’s empty

    • Added scripts/ so we can quickly check which files in a MAGICC run directory can be read by pymagicc

    • Added new section to docs, docs/file_conventions.rst which will document all of the relevant information related to MAGICC’s file conventions


  • (#323) Writers raise an AssertionError if the user tries to write a MAGICC input file which has timesteps where some values are nan whilst others are not. Such input files would have nans in them hence would cause MAGICC’s run to fail.

  • (#322) Re-write CHANGELOG to follow Keep a Changelog style

  • (#322) Change to 3-Clause BSD License

  • (#321) Raise ValueError if we attempt to run MAGICC with conflicting config keys (which can occur because FORTRAN is not case sensitive)

  • (#311) Fix naming of ocean heat content and ocean heat uptake output variables to match RCMIP conventions

  • (#307) Use scmdata.ScmRun as a base class for MAGICCData instead of the deprecated scmdata.ScmDataFrame (closes #295)

  • (#306) Copy run folder recursively when creating temporary copy

  • (#303) Refactor into multiple files

  • (#299) Make conversion of FORTRAN safe units apply to .MAG files too and be more consistent

  • (#293) Update CI to use GitHub actions

  • (#294) Convert the direct aerosols variable names from MAGICC in a consistent way.

  • (#294) Renamed definitions/magicc_emisssions_units.csv to definitions/magicc_emissions_units.csv

  • (#291) Switch to using the _ERF suffix for IPCC definition of Effective Radiative Forcing variables. This replaces _EFFRF which is a MAGICC internal variable and was incorrectly labelled as Effective Radiative Forcing.

  • (#290) Update minimum scmdata version to v0.4.3

  • (#285) Return pint.quantity.Quantity from all ECS, TCR and TCRE diagnostic methods

  • (#284) Update ECS, TCR and TCRE diagnosis to use 1pctCO2 and abrupt-2xCO2 experiments

  • (#283) Diagnose TCRE alongisde ECS and TCR, changes diagnose_tcr_ecs to diagnose_tcr_ecs_tcre and get_tcr_ecs_from_diagnosis_results method to get_tcr_ecs__tcre_from_diagnosis_results

  • (#280) Also include source distribution in pypi release

  • (#271) Update requirements of pyam.

  • (#271) Make error messages include stderr

  • (#271) Remove overwrite of file_emisscen when creating MAGICC7 copies if not self.strict

  • (#268) Update region mapping to match SSP database

  • (#266) Use a whitelist of OUT_ parameters which are converted to 1/0’s

  • (#264) Allowed an empty dataframe to be returned from if no output is produced

  • (#261) Improve mapping of MAGICC7 to OpenSCM variables

  • (#252) Improve header writing

  • (#252) Upgrade MAGICC time conversions

  • (#249) Update MAGICC7 support

  • (#247) Upgrade pyam dependency to use nominated release

  • (#236) Made all subannual files raise an InvalidTemporalResError exception as ScmDataFrame can’t handle merging annual and subannual timeseries together yet

  • (#239) Explicitly overwrite tuning model and emission scenario parameters for MAGICC7 when a temporary copy is created

  • (#234) Raise ValueError if only doesn’t match an output variable in (solves #231)

  • (#227) Fixed up permafrost naming to avoid confusing inclusion when summing up “Emissions|CO2”

  • (#220) If binary and ascii output files exist for a given variable only read the binary file

  • (#214) Refactor to use the timeseries capabilities of ScmDataFrameBase

  • (#210) Updated to match new openscm naming

  • (#199) Switched to OpenSCMDataFrameBase for the backend, also includes:

    • dropping Python3.5 support as OpenSCM typing is not Python3.5 compatible

    • ensuring that metadata is properly stripped when reading

    • altering MAGICCData.append so that MAGICCData instances can be appended to MAGICCData instances

    • allowing the user to specify, model, scenario and climate_model when initialising a MAGICCData instance

    • automatically filling model, scenario and climate_model when running

  • (#204) Addressed potential bug identified in (#203) and updated robustness of output file read in

  • (#198) Move all install requirements into

  • (#190) Speed up diagnosis of TCR and ECS by removing writing of scenario file

  • (#191) Fixed bugs which meant config passed to MAGICC wasn’t handled correctly

  • (#191) Renamed tests/ to tests/

  • (#173) Renamed pymagicc.api to pymagicc.core

  • (#165) Moved to one unified backend for all run functionality. This one got a bit out of hand so also includes:

    • Breaking the API, hence requiring significantly re-writing the tests to match the new API, bumping the major version number and updating the examples.

    • Locking up Pymagicc so that it will only run if MAGICC’s .CFG files are configured in the simplest way possible (see MAGICC flags). This required re-writing the pymagicc/MAGICC6/run/MAGCFG_USER.CFG file that ships with Pymagicc (although the result is the same, as confirmed by the fact that the outputs of the four RCPs are unchanged in tests/

    • Adding a function to pull a single configuration file from a MAGICC PARAMETERS.OUT file to aid the transition to the change referred to above (i.e. one could run MAGICC with whatever config elsewhere and then get a single config file which can be used with Pymagicc from the resulting PARAMETERS.OUT file).

    • Tidying up the docs to make linking a bit simpler and more reusable.

    • Only passing filepath (i.e. the combination of path and name) to reading/writing functions to remove ambiguity in previous language which used file, filepath, path, name and filename, sometimes in a self-contradictory way.

  • (#167) Updated release instructions

  • (#164) Improved missing MAGICC binary message in tests as discussed in #124

  • (#154) Change to using OpenSCM variables for all user facing data as well as preparing to move to using OpenSCM dataframes

    • Note that this change breaks direct access but that we will gain a lot of features once we start using the capabilities of pyam as part of an OpenSCM dataframe

  • (#160) Made notebooks CI more opinionated (#158)

  • (#135) Moved emissions definitions to a single csv and packaged all of the definitions files using the data package standard

  • (#146) Removed path alteration from docs buiding

  • (#143) Only read PARAMETERS.OUT file if it exists. MAGICCBase.config now defaults to None until a valid PARAMETERS.OUT file is read.

  • (#133) Put definitions of MAGICC6’s expected emissions into a standalone module



  • (#244) Use openscm from pip, hence drop Python3.6 support, and drop pyam dependency (moved into notebooks dependencies)

  • (#184) Remove redundant mapping of region names for SCEN to SCEN7 conversions


  • (#323) Writers now automatically drop all nan timesteps before writing MAGICC input files

  • (#323) pymagicc.scenarios.rcps now contains all the rcps rather than just rcp26

  • (#310) Rename to as PRN is a reserved filename on Windows

  • (#300) Fix name in docs (closes #205)

  • (#298) Make SCEN7 writing work with single variables

  • (#297) Make Binary reader able to handle global-only binary output

  • (#281) Hotfix readers and writers for .DAT files (thisfile_datacolumns was wrong)

  • (#269) Break circular dependency on OpenSCM by switching to using scmdata

  • (#267) Hotfix appveyor failures

  • (#252) Fix wine not installed error handling

  • (#233) Fix inplace append hard coding as identified in #232

  • (#225) Fix reading of DAT_CO2PF_EMIS.OUT

  • (#223) Ensure closes the input file

  • (#222) Remove trailing / in MANIFEST.IN recursive includes as this is invalid syntax on windows.

  • (#177) Fixed SCEN reading bug, can now read SCEN files with “YEAR” in first column rather than “YEARS”

  • (#163) Confirmed HFC-245fa misnaming in MAGICC6 (i.e. HFC-245fa was mistakenly labelled as HFC-245ca). Accordingly, we:

    • fixed this naming in the SRES scenarios (changing HFC-245ca to HFC-245fa)

    • removed pymagicc/MAGICC6/run/HISTRCP_HFC245ca_CONC.IN to avoid repeating this confusion

    • ensured that anyone who finds a file with “HFC-245ca” in it in future will get a warning, see tests/

For versions before 2.0 we did not follow the Keep a Changelog style. The notes made whilst developing versions <2.0 are included below for posterity.


  • add short-term solution for reading Carbon Cycle output

  • add clear error if a valid executable is not configured/found

  • remove _magiccbinary variable

  • partial steps towards updated input/output, still not fully tested

  • add examples of file input/writing in notebook

  • add expectexception so that we can show errors in notebooks with sensible CI


  • add TCR diagnosis function

  • improve testing of notebooks

  • add documentation using MkDocs

  • use Black for automatic code formatting

  • add Python 3.7 testing


  • drop support for Python 2

  • rename RCP3PD to RCP26 and RCP6 to RCP60 for consistency and MAGICC7 compatibility

  • introduce new API functions for setting up and running MAGICC

  • introduce config module

  • remove output_dir from run function, this can be achieved using the new API

  • change directory structure of the MAGICC version shipped with Pymagicc to be more similar to MAGICC7’s structure

  • add --skip-slow option to tests


  • add reading of MAGICC_EXECUTABLE environment variable to simplify setting path of MAGICC package for testing and CI (thanks @lewisjared)


  • interactive demo Notebook using Jupyter Notebook’s appmode extension

  • documentation improvements


  • Un-pin f90nml dependency, 0.23 is working with Pymagicc again


  • API Stable release



  • add Windows testing and fix running on Windows

  • simplify configuration by only having optional config parameters


  • pin f90nml version because later release breaks with MAGICC output


  • switch to Dictionaries as results object and scenarios data structure since Pandas panel is being deprecated.


  • returning used parameters in MAGICC run function is optional

  • fix versioning for PyPI installs


Initial release.