pymagicc.core¶

class pymagicc.core.MAGICC6(root_dir=None, strict=True)[source]¶

Bases: pymagicc.core.MAGICCBase

property binary_name¶

Name of the MAGICC binary file

Returns: Name of the binary file
Return type: str

check_config()¶

Check that our MAGICC .CFG files are set to safely work with PYMAGICC

For further detail about why this is required, please see MAGICC flags.

Raises: ValueError – If we are not certain that the config written by PYMAGICC will overwrite all other config i.e. that there will be no unexpected behaviour. A ValueError will also be raised if the user tries to use more than one scenario file.

create_copy()¶

Initialises a temporary directory structure and copy of MAGICC configuration files and binary.

The root folder and bin folders are copied (not recursively). The run folder is copied recursively.

property default_config¶: Default configuration to use in a run

diagnose_ecs(**kwargs)¶

Diagnose ECS

The equilibrium climate sensitivity (ECS), is the equilibrium global-mean temperature response to an instantaneous doubling of atmospheric CO₂ concentrations (abrupt-2xCO2 experiment).

Please note that sometimes the run length won’t be long enough to allow MAGICC’s oceans to fully equilibrate and hence the ECS value might not be what you expect (it should match the value of core_climatesensitivity).

Parameters: **kwargs – parameter values to use in the diagnosis e.g. core_climatesensitivity=4
Returns: Dictionary with keys: “ecs” - the diagnosed ECS; “timeseries” - the relevant model input and output timeseries used in the experiment i.e. atmospheric CO₂ concentrations, inverse CO₂ emissions, total radiative forcing and global-mean surface temperature
Return type: dict

diagnose_tcr_ecs_tcre(**kwargs)¶

Diagnose TCR, ECS and TCRE

The transient climate response (TCR), is the global-mean temperature response per unit cumulative CO₂ emissions at the time at which atmospheric CO₂ concentrations double in an experiment where atmospheric CO₂ concentrations are increased at 1% per year from pre-industrial levels (1pctCO2 experiment).

The equilibrium climate sensitivity (ECS), is the equilibrium global-mean temperature response to an instantaneous doubling of atmospheric CO₂ concentrations (abrupt-2xCO2 experiment).

The transient climate response to emissions (TCRE), is the global-mean temperature response per unit cumulative CO₂ emissions at the time at which atmospheric CO₂ concentrations double in the 1pctCO2 experiment.

Please note that sometimes the run length won’t be long enough to allow MAGICC’s oceans to fully equilibrate and hence the ECS value might not be what you expect (it should match the value of core_climatesensitivity).

Parameters: **kwargs – parameter values to use in the diagnosis e.g. core_climatesensitivity=4
Returns: Dictionary with keys: “ecs” - the diagnosed ECS; “tcr” - the diagnosed TCR; “tcre” - the diagnosed TCRE; “timeseries” - the relevant model input and output timeseries used in the experiment i.e. atmospheric CO₂ concentrations, inverse CO₂ emissions, total radiative forcing and global-mean surface temperature
Return type: dict

diagnose_tcr_tcre(**kwargs)¶

Diagnose TCR and TCRE

The transient climate response (TCR), is the global-mean temperature response per unit cumulative CO₂ emissions at the time at which atmospheric CO₂ concentrations double in an experiment where atmospheric CO₂ concentrations are increased at 1% per year from pre-industrial levels (1pctCO2 experiment).

The transient climate response to emissions (TCRE), is the global-mean temperature response per unit cumulative CO₂ emissions at the time at which atmospheric CO₂ concentrations double in the 1pctCO2 experiment.

Parameters: **kwargs – parameter values to use in the diagnosis e.g. core_climatesensitivity=4
Returns: Dictionary with keys: “tcr” - the diagnosed TCR; “tcre” - the diagnosed TCRE; “timeseries” - the relevant model input and output timeseries used in the experiment i.e. atmospheric CO₂ concentrations, inverse CO₂ emissions, total radiative forcing and global-mean surface temperature
Return type: dict

get_ecs_from_diagnosis_results(results_ecs_run)¶

Diagnose ECS from the results of the abrupt-2xCO2 experiment

Parameters: results_ecs_run (ScmRun) – Results of the abrupt-2xCO2 experiment, must contain atmospheric CO₂ concentrations, total radiative forcing and surface temperature.
Returns: ecs – ECS diagnosed from results_ecs_run
Return type: pint.quantity.Quantity

get_executable()¶

Get path to MAGICC executable being used

Returns: Path to MAGICC executable being used
Return type: str

get_tcr_tcre_from_diagnosis_results(results_tcr_tcre_run)¶

Diagnose TCR and TCRE from the results of the 1pctCO2 experiment

Parameters: results_tcr_tcre_run (ScmRun) – Results of the 1pctCO2 experiment, must contain atmospheric CO₂ concentrations, inverse CO₂ emissions, total radiative forcing and surface temperature.
Returns: tcr, tcre – TCR and TCRE diagnosed from results_tcr_tcre_run
Return type: pint.quantity.Quantity, pint.quantity.Quantity

property original_dir¶

Directory of the MAGICC package.

This is the directory which contains the run and out folders.

Returns: Path of the MAGICC package
Return type: str

property out_dir¶

Output directory of the MAGICC package.

This path always ends in out.

Returns: Path of the output directory
Return type: str

read_parameters()¶

Read a parameters.out file

Returns: A dictionary containing all the configuration used by MAGICC
Return type: dict

remove_temp_copy()¶: Removes a temporary copy of the MAGICC version shipped with Pymagicc.

run(scenario=None, only=None, debug=False, **kwargs)¶

Run MAGICC and parse the output.

As a reminder, putting out_parameters=1 will cause MAGICC to write out its parameters into out/PARAMETERS.OUT and they will then be read into output.metadata["parameters"] where output is the returned object.

Any logged output from running magicc will be in``output.metadata[“stderr”]``. For MAGICC7 and above, The level of logging can be controlled with the debug argument.

Any subannual files output by MAGICC will be ignored by this function. These files can be read in manually using pymagicc.io.MAGICCData directly.

Parameters

scenario (pymagicc.io.MAGICCData) – Scenario to run. If None MAGICC will simply run with whatever config has already been set.
only (list of str) – If not None, only extract variables in this list.
debug ({True, False, "verbose"}) – If true, MAGICC will run in debug mode with the maximum amount of logging. If “verbose”, MAGICC will be run in verbose mode.
kwargs – Other config values to pass to MAGICC for the run

Returns

MAGICCData object containing that data in its df attribute and metadata and parameters (depending on the value of include_parameters) in its metadata attribute.

Return type

pymagicc.io.MAGICCData

Raises

ValueError – If no output is found which matches the list specified in only.
subprocess.CalledProcessError – If MAGICC fails to run. Check the ‘stderr’ key of the result’s metadata attribute to inspect the results output from MAGICC.
ValueError – The user attempts to use debug with MAGICC6

property run_dir¶

Run directory of the MAGICC package.

This path always ends in run.

Returns: Path of the run directory
Return type: str

set_config(filename='MAGTUNE_PYMAGICC.CFG', top_level_key='nml_allcfgs', conflict='warn', **kwargs)¶

Create a configuration file for MAGICC.

Writes a fortran namelist in run_dir.

Parameters

filename (str) – Name of configuration file to write
top_level_key (str) – Name of namelist to be written in the configuration file
conflict ({'warn', 'ignore'}) – If ‘warn’, when a flag needs to be replaced by a different name (because, for example, the flag name changed between MAGICC versions), a warning is raised. If ‘ignore’, no warning is raised when a replacement is required.
kwargs – Other parameters to pass to the configuration file. No validation on the parameters is performed.

Returns

The contents of the namelist which was written to file

Return type

dict

Warning

If a key is renamed, a warning is raised

Raises: ValueError – An invalid value for conflict is supplied

set_emission_scenario_setup(scenario, config_dict)¶

Set the emissions flags correctly.

Parameters

scenario (pymagicc.io.MAGICCData) – Scenario to run.
config_dict (dict) – Dictionary with current input configurations which is to be validated and updated where necessary.

Returns

Updated configuration

Return type

dict

set_output_variables(write_ascii=True, write_binary=False, **kwargs)¶

Set the output configuration, minimising output as much as possible

There are a number of configuration parameters which control which variables are written to file and in which format. Limiting the variables that are written to file can greatly speed up the running of MAGICC. By default, calling this function without specifying any variables will disable all output by setting all of MAGICC’s out_xx flags to 0.

This convenience function should not be confused with set_config or update_config which allow the user to set/update the configuration flags directly, without the more convenient syntax and default behaviour provided by this function.

Parameters

write_ascii (bool) – If true, MAGICC is configured to write output files as human readable ascii files.
write_binary (bool) – If true, MAGICC is configured to write binary output files. These files are much faster to process and write, but are not human readable.
**kwargs –
List of variables to write out. A list of possible options are as follows. This may not be a complete list.

’emissions’, ‘gwpemissions’, ‘sum_gwpemissions’, ‘concentrations’, ‘carboncycle’, ‘forcing’, ‘surfaceforcing’, ‘permafrost’, ‘temperature’, ‘sealevel’, ‘parameters’, ‘misc’, ‘lifetimes’, ‘timeseriesmix’, ‘rcpdata’, ‘summaryidx’, ‘inverseemis’, ‘tempoceanlayers’, ‘oceanarea’, ‘heatuptake’, ‘warnings’, ‘precipinput’, ‘aogcmtuning’, ‘ccycletuning’, ‘observationaltuning’, ‘keydata_1’, ‘keydata_2’

set_years(startyear=1765, endyear=2100)¶

Set the start and end dates of the simulations.

Parameters

startyear (int) – Start year of the simulation
endyear (int) – End year of the simulation

Returns

The contents of the namelist

Return type

dict

set_zero_config()¶

Set config such that radiative forcing and temperature output will be zero

This method is intended as a convenience only, it does not handle everything in an obvious way. Adjusting the parameter settings still requires great care and may behave unepexctedly.

update_config(filename='MAGTUNE_PYMAGICC.CFG', top_level_key='nml_allcfgs', conflict='warn', **kwargs)¶

Updates a configuration file for MAGICC

Updates the contents of a fortran namelist in the run directory, creating a new namelist if none exists.

Parameters

filename (str) – Name of configuration file to write
top_level_key (str) – Name of namelist to be written in the configuration file
conflict ({'warn', 'ignore'}) – If ‘warn’, when a flag needs to be replaced by a different name (because, for example, the flag name changed between MAGICC versions), a warning is raised. If ‘ignore’, no warning is raised when a replacement is required.
kwargs – Other parameters to pass to the configuration file. No validation on the parameters is performed.

Returns

The contents of the namelist which was written to file

Return type

dict

Warning

If a key is renamed, a warning is raised

Raises: ValueError – An invalid value for conflict is supplied

version = 6¶

write(mdata, name)¶

Write an input file to disk

Parameters

mdata (pymagicc.io.MAGICCData) – A MAGICCData instance with the data to write
name (str) – The name of the file to write. The file will be written to the MAGICC instance’s run directory i.e. self.run_dir

class pymagicc.core.MAGICC7(root_dir=None, strict=True)[source]¶

Bases: pymagicc.core.MAGICCBase

property binary_name¶

Name of the MAGICC binary file

Returns: Name of the binary file
Return type: str

check_config()¶

Check that our MAGICC .CFG files are set to safely work with PYMAGICC

For further detail about why this is required, please see MAGICC flags.

Raises: ValueError – If we are not certain that the config written by PYMAGICC will overwrite all other config i.e. that there will be no unexpected behaviour. A ValueError will also be raised if the user tries to use more than one scenario file.

create_copy()[source]¶

Initialises a temporary directory structure and copy of MAGICC configuration files and binary.

This will also overwrite the value of all file_tuningmodel_x flags to ensure that Pymagicc’s configurations will be read. If self.strict, this will also overwrite the value of all file_emisscen_x flags to ensure that only Pymagicc’s scenario input is used. This overwrite behaviour can be removed once the MAGICC7 binary is publicly released as we can then create a Pymagicc specific MAGCFG_USER.CFG rather than relying on whatever is in the user’s current copy.

property default_config¶

Default configuration for a run

Returns: Namelist object containing the default configuration
Return type: f90nml.Namelist

diagnose_ecs(**kwargs)¶

Diagnose ECS

The equilibrium climate sensitivity (ECS), is the equilibrium global-mean temperature response to an instantaneous doubling of atmospheric CO₂ concentrations (abrupt-2xCO2 experiment).

Please note that sometimes the run length won’t be long enough to allow MAGICC’s oceans to fully equilibrate and hence the ECS value might not be what you expect (it should match the value of core_climatesensitivity).

Parameters: **kwargs – parameter values to use in the diagnosis e.g. core_climatesensitivity=4
Returns: Dictionary with keys: “ecs” - the diagnosed ECS; “timeseries” - the relevant model input and output timeseries used in the experiment i.e. atmospheric CO₂ concentrations, inverse CO₂ emissions, total radiative forcing and global-mean surface temperature
Return type: dict

diagnose_tcr_ecs_tcre(**kwargs)¶

Diagnose TCR, ECS and TCRE

The transient climate response (TCR), is the global-mean temperature response per unit cumulative CO₂ emissions at the time at which atmospheric CO₂ concentrations double in an experiment where atmospheric CO₂ concentrations are increased at 1% per year from pre-industrial levels (1pctCO2 experiment).

The equilibrium climate sensitivity (ECS), is the equilibrium global-mean temperature response to an instantaneous doubling of atmospheric CO₂ concentrations (abrupt-2xCO2 experiment).

The transient climate response to emissions (TCRE), is the global-mean temperature response per unit cumulative CO₂ emissions at the time at which atmospheric CO₂ concentrations double in the 1pctCO2 experiment.

Please note that sometimes the run length won’t be long enough to allow MAGICC’s oceans to fully equilibrate and hence the ECS value might not be what you expect (it should match the value of core_climatesensitivity).

Parameters: **kwargs – parameter values to use in the diagnosis e.g. core_climatesensitivity=4
Returns: Dictionary with keys: “ecs” - the diagnosed ECS; “tcr” - the diagnosed TCR; “tcre” - the diagnosed TCRE; “timeseries” - the relevant model input and output timeseries used in the experiment i.e. atmospheric CO₂ concentrations, inverse CO₂ emissions, total radiative forcing and global-mean surface temperature
Return type: dict

diagnose_tcr_tcre(**kwargs)¶

Diagnose TCR and TCRE

The transient climate response (TCR), is the global-mean temperature response per unit cumulative CO₂ emissions at the time at which atmospheric CO₂ concentrations double in an experiment where atmospheric CO₂ concentrations are increased at 1% per year from pre-industrial levels (1pctCO2 experiment).

The transient climate response to emissions (TCRE), is the global-mean temperature response per unit cumulative CO₂ emissions at the time at which atmospheric CO₂ concentrations double in the 1pctCO2 experiment.

Parameters: **kwargs – parameter values to use in the diagnosis e.g. core_climatesensitivity=4
Returns: Dictionary with keys: “tcr” - the diagnosed TCR; “tcre” - the diagnosed TCRE; “timeseries” - the relevant model input and output timeseries used in the experiment i.e. atmospheric CO₂ concentrations, inverse CO₂ emissions, total radiative forcing and global-mean surface temperature
Return type: dict

get_ecs_from_diagnosis_results(results_ecs_run)¶

Diagnose ECS from the results of the abrupt-2xCO2 experiment

Parameters: results_ecs_run (ScmRun) – Results of the abrupt-2xCO2 experiment, must contain atmospheric CO₂ concentrations, total radiative forcing and surface temperature.
Returns: ecs – ECS diagnosed from results_ecs_run
Return type: pint.quantity.Quantity

get_executable()¶

Get path to MAGICC executable being used

Returns: Path to MAGICC executable being used
Return type: str

get_tcr_tcre_from_diagnosis_results(results_tcr_tcre_run)¶

Diagnose TCR and TCRE from the results of the 1pctCO2 experiment

Parameters: results_tcr_tcre_run (ScmRun) – Results of the 1pctCO2 experiment, must contain atmospheric CO₂ concentrations, inverse CO₂ emissions, total radiative forcing and surface temperature.
Returns: tcr, tcre – TCR and TCRE diagnosed from results_tcr_tcre_run
Return type: pint.quantity.Quantity, pint.quantity.Quantity

property original_dir¶

Directory of the MAGICC package.

This is the directory which contains the run and out folders.

Returns: Path of the MAGICC package
Return type: str

property out_dir¶

Output directory of the MAGICC package.

This path always ends in out.

Returns: Path of the output directory
Return type: str

read_parameters()¶

Read a parameters.out file

Returns: A dictionary containing all the configuration used by MAGICC
Return type: dict

remove_temp_copy()¶: Removes a temporary copy of the MAGICC version shipped with Pymagicc.

run(scenario=None, only=None, debug=False, **kwargs)¶

Run MAGICC and parse the output.

As a reminder, putting out_parameters=1 will cause MAGICC to write out its parameters into out/PARAMETERS.OUT and they will then be read into output.metadata["parameters"] where output is the returned object.

Any logged output from running magicc will be in``output.metadata[“stderr”]``. For MAGICC7 and above, The level of logging can be controlled with the debug argument.

Any subannual files output by MAGICC will be ignored by this function. These files can be read in manually using pymagicc.io.MAGICCData directly.

Parameters

scenario (pymagicc.io.MAGICCData) – Scenario to run. If None MAGICC will simply run with whatever config has already been set.
only (list of str) – If not None, only extract variables in this list.
debug ({True, False, "verbose"}) – If true, MAGICC will run in debug mode with the maximum amount of logging. If “verbose”, MAGICC will be run in verbose mode.
kwargs – Other config values to pass to MAGICC for the run

Returns

MAGICCData object containing that data in its df attribute and metadata and parameters (depending on the value of include_parameters) in its metadata attribute.

Return type

pymagicc.io.MAGICCData

Raises

ValueError – If no output is found which matches the list specified in only.
subprocess.CalledProcessError – If MAGICC fails to run. Check the ‘stderr’ key of the result’s metadata attribute to inspect the results output from MAGICC.
ValueError – The user attempts to use debug with MAGICC6

property run_dir¶

Run directory of the MAGICC package.

This path always ends in run.

Returns: Path of the run directory
Return type: str

set_config(filename='MAGTUNE_PYMAGICC.CFG', top_level_key='nml_allcfgs', conflict='warn', **kwargs)¶

Create a configuration file for MAGICC.

Writes a fortran namelist in run_dir.

Parameters

filename (str) – Name of configuration file to write
top_level_key (str) – Name of namelist to be written in the configuration file
conflict ({'warn', 'ignore'}) – If ‘warn’, when a flag needs to be replaced by a different name (because, for example, the flag name changed between MAGICC versions), a warning is raised. If ‘ignore’, no warning is raised when a replacement is required.
kwargs – Other parameters to pass to the configuration file. No validation on the parameters is performed.

Returns

The contents of the namelist which was written to file

Return type

dict

Warning

If a key is renamed, a warning is raised

Raises: ValueError – An invalid value for conflict is supplied

set_emission_scenario_setup(scenario, config_dict)¶

Set the emissions flags correctly.

Parameters

scenario (pymagicc.io.MAGICCData) – Scenario to run.
config_dict (dict) – Dictionary with current input configurations which is to be validated and updated where necessary.

Returns

Updated configuration

Return type

dict

set_output_variables(write_ascii=True, write_binary=False, **kwargs)¶

Set the output configuration, minimising output as much as possible

There are a number of configuration parameters which control which variables are written to file and in which format. Limiting the variables that are written to file can greatly speed up the running of MAGICC. By default, calling this function without specifying any variables will disable all output by setting all of MAGICC’s out_xx flags to 0.

This convenience function should not be confused with set_config or update_config which allow the user to set/update the configuration flags directly, without the more convenient syntax and default behaviour provided by this function.

Parameters

write_ascii (bool) – If true, MAGICC is configured to write output files as human readable ascii files.
write_binary (bool) – If true, MAGICC is configured to write binary output files. These files are much faster to process and write, but are not human readable.
**kwargs –
List of variables to write out. A list of possible options are as follows. This may not be a complete list.

’emissions’, ‘gwpemissions’, ‘sum_gwpemissions’, ‘concentrations’, ‘carboncycle’, ‘forcing’, ‘surfaceforcing’, ‘permafrost’, ‘temperature’, ‘sealevel’, ‘parameters’, ‘misc’, ‘lifetimes’, ‘timeseriesmix’, ‘rcpdata’, ‘summaryidx’, ‘inverseemis’, ‘tempoceanlayers’, ‘oceanarea’, ‘heatuptake’, ‘warnings’, ‘precipinput’, ‘aogcmtuning’, ‘ccycletuning’, ‘observationaltuning’, ‘keydata_1’, ‘keydata_2’

set_years(startyear=1765, endyear=2100)¶

Set the start and end dates of the simulations.

Parameters

startyear (int) – Start year of the simulation
endyear (int) – End year of the simulation

Returns

The contents of the namelist

Return type

dict

set_zero_config()¶

Set config such that radiative forcing and temperature output will be zero

This method is intended as a convenience only, it does not handle everything in an obvious way. Adjusting the parameter settings still requires great care and may behave unepexctedly.

update_config(filename='MAGTUNE_PYMAGICC.CFG', top_level_key='nml_allcfgs', conflict='warn', **kwargs)¶

Updates a configuration file for MAGICC

Updates the contents of a fortran namelist in the run directory, creating a new namelist if none exists.

Parameters

filename (str) – Name of configuration file to write
top_level_key (str) – Name of namelist to be written in the configuration file
conflict ({'warn', 'ignore'}) – If ‘warn’, when a flag needs to be replaced by a different name (because, for example, the flag name changed between MAGICC versions), a warning is raised. If ‘ignore’, no warning is raised when a replacement is required.
kwargs – Other parameters to pass to the configuration file. No validation on the parameters is performed.

Returns

The contents of the namelist which was written to file

Return type

dict

Warning

If a key is renamed, a warning is raised

Raises: ValueError – An invalid value for conflict is supplied

version = 7¶

write(mdata, name)¶

Write an input file to disk

Parameters

mdata (pymagicc.io.MAGICCData) – A MAGICCData instance with the data to write
name (str) – The name of the file to write. The file will be written to the MAGICC instance’s run directory i.e. self.run_dir

class pymagicc.core.MAGICCBase(root_dir=None, strict=True)[source]¶

Bases: object

Provides access to the MAGICC binary and configuration.

To enable multiple MAGICC ‘setups’ to be configured independently, the MAGICC directory containing the input files, configuration and binary is copied to a new folder. The configuration in this MAGICC copy can then be edited without impacting other instances or your original MAGICC distribution.

A MAGICC instance first has to be setup by calling create_copy. If many model runs are being performed this step only has to be performed once. The run method can then be called many times without re-copying the files each time. Between each call to run, the configuration files can be updated to perform runs with different configurations.

Parameters: root_dir (str) – If root_dir is supplied, an existing MAGICC ‘setup’ is used.

property binary_name¶

Name of the MAGICC binary file

Returns: Name of the binary file
Return type: str

check_config()[source]¶

Check that our MAGICC .CFG files are set to safely work with PYMAGICC

For further detail about why this is required, please see MAGICC flags.

Raises: ValueError – If we are not certain that the config written by PYMAGICC will overwrite all other config i.e. that there will be no unexpected behaviour. A ValueError will also be raised if the user tries to use more than one scenario file.

create_copy()[source]¶

Initialises a temporary directory structure and copy of MAGICC configuration files and binary.

The root folder and bin folders are copied (not recursively). The run folder is copied recursively.

property default_config¶

Default configuration for a run

Returns: Namelist object containing the default configuration
Return type: f90nml.Namelist

diagnose_ecs(**kwargs)[source]¶

Diagnose ECS

The equilibrium climate sensitivity (ECS), is the equilibrium global-mean temperature response to an instantaneous doubling of atmospheric CO₂ concentrations (abrupt-2xCO2 experiment).

Please note that sometimes the run length won’t be long enough to allow MAGICC’s oceans to fully equilibrate and hence the ECS value might not be what you expect (it should match the value of core_climatesensitivity).

Parameters: **kwargs – parameter values to use in the diagnosis e.g. core_climatesensitivity=4
Returns: Dictionary with keys: “ecs” - the diagnosed ECS; “timeseries” - the relevant model input and output timeseries used in the experiment i.e. atmospheric CO₂ concentrations, inverse CO₂ emissions, total radiative forcing and global-mean surface temperature
Return type: dict

diagnose_tcr_ecs_tcre(**kwargs)[source]¶

Diagnose TCR, ECS and TCRE

The transient climate response (TCR), is the global-mean temperature response per unit cumulative CO₂ emissions at the time at which atmospheric CO₂ concentrations double in an experiment where atmospheric CO₂ concentrations are increased at 1% per year from pre-industrial levels (1pctCO2 experiment).

The equilibrium climate sensitivity (ECS), is the equilibrium global-mean temperature response to an instantaneous doubling of atmospheric CO₂ concentrations (abrupt-2xCO2 experiment).

The transient climate response to emissions (TCRE), is the global-mean temperature response per unit cumulative CO₂ emissions at the time at which atmospheric CO₂ concentrations double in the 1pctCO2 experiment.

Please note that sometimes the run length won’t be long enough to allow MAGICC’s oceans to fully equilibrate and hence the ECS value might not be what you expect (it should match the value of core_climatesensitivity).

Parameters: **kwargs – parameter values to use in the diagnosis e.g. core_climatesensitivity=4
Returns: Dictionary with keys: “ecs” - the diagnosed ECS; “tcr” - the diagnosed TCR; “tcre” - the diagnosed TCRE; “timeseries” - the relevant model input and output timeseries used in the experiment i.e. atmospheric CO₂ concentrations, inverse CO₂ emissions, total radiative forcing and global-mean surface temperature
Return type: dict

diagnose_tcr_tcre(**kwargs)[source]¶

Diagnose TCR and TCRE

The transient climate response (TCR), is the global-mean temperature response per unit cumulative CO₂ emissions at the time at which atmospheric CO₂ concentrations double in an experiment where atmospheric CO₂ concentrations are increased at 1% per year from pre-industrial levels (1pctCO2 experiment).

The transient climate response to emissions (TCRE), is the global-mean temperature response per unit cumulative CO₂ emissions at the time at which atmospheric CO₂ concentrations double in the 1pctCO2 experiment.

Parameters: **kwargs – parameter values to use in the diagnosis e.g. core_climatesensitivity=4
Returns: Dictionary with keys: “tcr” - the diagnosed TCR; “tcre” - the diagnosed TCRE; “timeseries” - the relevant model input and output timeseries used in the experiment i.e. atmospheric CO₂ concentrations, inverse CO₂ emissions, total radiative forcing and global-mean surface temperature
Return type: dict

get_ecs_from_diagnosis_results(results_ecs_run)[source]¶

Diagnose ECS from the results of the abrupt-2xCO2 experiment

Parameters: results_ecs_run (ScmRun) – Results of the abrupt-2xCO2 experiment, must contain atmospheric CO₂ concentrations, total radiative forcing and surface temperature.
Returns: ecs – ECS diagnosed from results_ecs_run
Return type: pint.quantity.Quantity

get_executable()[source]¶

Get path to MAGICC executable being used

Returns: Path to MAGICC executable being used
Return type: str

get_tcr_tcre_from_diagnosis_results(results_tcr_tcre_run)[source]¶

Diagnose TCR and TCRE from the results of the 1pctCO2 experiment

Parameters: results_tcr_tcre_run (ScmRun) – Results of the 1pctCO2 experiment, must contain atmospheric CO₂ concentrations, inverse CO₂ emissions, total radiative forcing and surface temperature.
Returns: tcr, tcre – TCR and TCRE diagnosed from results_tcr_tcre_run
Return type: pint.quantity.Quantity, pint.quantity.Quantity

property original_dir¶

Directory of the MAGICC package.

This is the directory which contains the run and out folders.

Returns: Path of the MAGICC package
Return type: str

property out_dir¶

Output directory of the MAGICC package.

This path always ends in out.

Returns: Path of the output directory
Return type: str

read_parameters()[source]¶

Read a parameters.out file

Returns: A dictionary containing all the configuration used by MAGICC
Return type: dict

remove_temp_copy()[source]¶: Removes a temporary copy of the MAGICC version shipped with Pymagicc.

run(scenario=None, only=None, debug=False, **kwargs)[source]¶

Run MAGICC and parse the output.

As a reminder, putting out_parameters=1 will cause MAGICC to write out its parameters into out/PARAMETERS.OUT and they will then be read into output.metadata["parameters"] where output is the returned object.

Any logged output from running magicc will be in``output.metadata[“stderr”]``. For MAGICC7 and above, The level of logging can be controlled with the debug argument.

Any subannual files output by MAGICC will be ignored by this function. These files can be read in manually using pymagicc.io.MAGICCData directly.

Parameters

scenario (pymagicc.io.MAGICCData) – Scenario to run. If None MAGICC will simply run with whatever config has already been set.
only (list of str) – If not None, only extract variables in this list.
debug ({True, False, "verbose"}) – If true, MAGICC will run in debug mode with the maximum amount of logging. If “verbose”, MAGICC will be run in verbose mode.
kwargs – Other config values to pass to MAGICC for the run

Returns

MAGICCData object containing that data in its df attribute and metadata and parameters (depending on the value of include_parameters) in its metadata attribute.

Return type

pymagicc.io.MAGICCData

Raises

ValueError – If no output is found which matches the list specified in only.
subprocess.CalledProcessError – If MAGICC fails to run. Check the ‘stderr’ key of the result’s metadata attribute to inspect the results output from MAGICC.
ValueError – The user attempts to use debug with MAGICC6

property run_dir¶

Run directory of the MAGICC package.

This path always ends in run.

Returns: Path of the run directory
Return type: str

set_config(filename='MAGTUNE_PYMAGICC.CFG', top_level_key='nml_allcfgs', conflict='warn', **kwargs)[source]¶

Create a configuration file for MAGICC.

Writes a fortran namelist in run_dir.

Parameters

filename (str) – Name of configuration file to write
top_level_key (str) – Name of namelist to be written in the configuration file
conflict ({'warn', 'ignore'}) – If ‘warn’, when a flag needs to be replaced by a different name (because, for example, the flag name changed between MAGICC versions), a warning is raised. If ‘ignore’, no warning is raised when a replacement is required.
kwargs – Other parameters to pass to the configuration file. No validation on the parameters is performed.

Returns

The contents of the namelist which was written to file

Return type

dict

Warning

If a key is renamed, a warning is raised

Raises: ValueError – An invalid value for conflict is supplied

set_emission_scenario_setup(scenario, config_dict)[source]¶

Set the emissions flags correctly.

Parameters

scenario (pymagicc.io.MAGICCData) – Scenario to run.
config_dict (dict) – Dictionary with current input configurations which is to be validated and updated where necessary.

Returns

Updated configuration

Return type

dict

set_output_variables(write_ascii=True, write_binary=False, **kwargs)[source]¶

Set the output configuration, minimising output as much as possible

There are a number of configuration parameters which control which variables are written to file and in which format. Limiting the variables that are written to file can greatly speed up the running of MAGICC. By default, calling this function without specifying any variables will disable all output by setting all of MAGICC’s out_xx flags to 0.

This convenience function should not be confused with set_config or update_config which allow the user to set/update the configuration flags directly, without the more convenient syntax and default behaviour provided by this function.

Parameters

write_ascii (bool) – If true, MAGICC is configured to write output files as human readable ascii files.
write_binary (bool) – If true, MAGICC is configured to write binary output files. These files are much faster to process and write, but are not human readable.
**kwargs –
List of variables to write out. A list of possible options are as follows. This may not be a complete list.

’emissions’, ‘gwpemissions’, ‘sum_gwpemissions’, ‘concentrations’, ‘carboncycle’, ‘forcing’, ‘surfaceforcing’, ‘permafrost’, ‘temperature’, ‘sealevel’, ‘parameters’, ‘misc’, ‘lifetimes’, ‘timeseriesmix’, ‘rcpdata’, ‘summaryidx’, ‘inverseemis’, ‘tempoceanlayers’, ‘oceanarea’, ‘heatuptake’, ‘warnings’, ‘precipinput’, ‘aogcmtuning’, ‘ccycletuning’, ‘observationaltuning’, ‘keydata_1’, ‘keydata_2’

set_years(startyear=1765, endyear=2100)[source]¶

Set the start and end dates of the simulations.

Parameters

startyear (int) – Start year of the simulation
endyear (int) – End year of the simulation

Returns

The contents of the namelist

Return type

dict

set_zero_config()[source]¶

Set config such that radiative forcing and temperature output will be zero

This method is intended as a convenience only, it does not handle everything in an obvious way. Adjusting the parameter settings still requires great care and may behave unepexctedly.

update_config(filename='MAGTUNE_PYMAGICC.CFG', top_level_key='nml_allcfgs', conflict='warn', **kwargs)[source]¶

Updates a configuration file for MAGICC

Updates the contents of a fortran namelist in the run directory, creating a new namelist if none exists.

Parameters

filename (str) – Name of configuration file to write
top_level_key (str) – Name of namelist to be written in the configuration file
conflict ({'warn', 'ignore'}) – If ‘warn’, when a flag needs to be replaced by a different name (because, for example, the flag name changed between MAGICC versions), a warning is raised. If ‘ignore’, no warning is raised when a replacement is required.
kwargs – Other parameters to pass to the configuration file. No validation on the parameters is performed.

Returns

The contents of the namelist which was written to file

Return type

dict

Warning

If a key is renamed, a warning is raised

Raises: ValueError – An invalid value for conflict is supplied

version = None¶

write(mdata, name)[source]¶

Write an input file to disk

Parameters

mdata (pymagicc.io.MAGICCData) – A MAGICCData instance with the data to write
name (str) – The name of the file to write. The file will be written to the MAGICC instance’s run directory i.e. self.run_dir

exception pymagicc.core.WineNotInstalledError[source]¶

Bases: Exception

Exception raised if wine is not installed but is required

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.