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 PYMAGICCFor 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). Therun
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 CO2 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 CO2 concentrations, inverse CO2 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 CO2 emissions at the time at which atmospheric CO2 concentrations double in an experiment where atmospheric CO2 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 CO2 concentrations (abrupt-2xCO2 experiment).
The transient climate response to emissions (TCRE), is the global-mean temperature response per unit cumulative CO2 emissions at the time at which atmospheric CO2 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 CO2 concentrations, inverse CO2 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 CO2 emissions at the time at which atmospheric CO2 concentrations double in an experiment where atmospheric CO2 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 CO2 emissions at the time at which atmospheric CO2 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 CO2 concentrations, inverse CO2 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 CO2 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 CO2 concentrations, inverse CO2 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
andout
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 intoout/PARAMETERS.OUT
and they will then be read intooutput.metadata["parameters"]
whereoutput
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 ofinclude_parameters
) in itsmetadata
attribute.- Return type
- 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 to0
.This convenience function should not be confused with
set_config
orupdate_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 writename (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 PYMAGICCFor 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. Ifself.strict
, this will also overwrite the value of allfile_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 CO2 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 CO2 concentrations, inverse CO2 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 CO2 emissions at the time at which atmospheric CO2 concentrations double in an experiment where atmospheric CO2 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 CO2 concentrations (abrupt-2xCO2 experiment).
The transient climate response to emissions (TCRE), is the global-mean temperature response per unit cumulative CO2 emissions at the time at which atmospheric CO2 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 CO2 concentrations, inverse CO2 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 CO2 emissions at the time at which atmospheric CO2 concentrations double in an experiment where atmospheric CO2 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 CO2 emissions at the time at which atmospheric CO2 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 CO2 concentrations, inverse CO2 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 CO2 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 CO2 concentrations, inverse CO2 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
andout
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 intoout/PARAMETERS.OUT
and they will then be read intooutput.metadata["parameters"]
whereoutput
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 ofinclude_parameters
) in itsmetadata
attribute.- Return type
- 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 to0
.This convenience function should not be confused with
set_config
orupdate_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 writename (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 callingcreate_copy
. If many model runs are being performed this step only has to be performed once. Therun
method can then be called many times without re-copying the files each time. Between each call torun
, 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 PYMAGICCFor 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). Therun
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 CO2 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 CO2 concentrations, inverse CO2 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 CO2 emissions at the time at which atmospheric CO2 concentrations double in an experiment where atmospheric CO2 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 CO2 concentrations (abrupt-2xCO2 experiment).
The transient climate response to emissions (TCRE), is the global-mean temperature response per unit cumulative CO2 emissions at the time at which atmospheric CO2 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 CO2 concentrations, inverse CO2 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 CO2 emissions at the time at which atmospheric CO2 concentrations double in an experiment where atmospheric CO2 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 CO2 emissions at the time at which atmospheric CO2 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 CO2 concentrations, inverse CO2 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 CO2 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 CO2 concentrations, inverse CO2 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
andout
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
- 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 intoout/PARAMETERS.OUT
and they will then be read intooutput.metadata["parameters"]
whereoutput
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 ofinclude_parameters
) in itsmetadata
attribute.- Return type
- 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 to0
.This convenience function should not be confused with
set_config
orupdate_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 writename (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