exoplasim package¶
Module contents¶

class
exoplasim.
Earthlike
(resolution='T21', layers=10, ncpus=4, precision=8, debug=False, inityear=0, recompile=False, optimization=None, mars=False, workdir='most', source=None, force991=False, modelname='MOST_EXP', outputtype='.npz', crashtolerant=False)[source]¶ Bases:
exoplasim.Model
Create an Earthlike model, but more flexible.
Identical to
Model
, except configuration options common for Earthlike models requiring slightly more flexibility are the default when configure is called–specifically, 45minute timestep, snapshot output reporting every 480 timesteps, and a model top pinned to 50 mbar. All these defaults can be overridden.
configure
(timestep=45.0, snapshots=480, vtype=4, modeltop=50.0, **kwargs)[source]¶ Configure the model’s namelists and boundary conditions.
The defaults here are appropriate for an Earth model.
Model Operation
 noutputbool, optional
True/False. Whether or not model output should be written.
 restartfilestr, optional
Path to a restart file to use for initial conditions. Can be None.
 writefrequencyint, optional
How many times per day ExoPlaSim should write output. Ignored by default–default is to write timeaveraged output once every 5 days.
 timestepfloat, optional
Model timestep. Defaults to 45 minutes.
 runscriptfunction , optional
A Python function that accepts a Model object as its first argument. This is the routine that will be run when you issue the Model.run() command. Any keyword arguments passed to run() will be forwarded to the specified function. If not set, the default internal routine will be used.
 snapshotsint, optional
How many timesteps should elapse between snapshot outputs. If not set, no snapshots will be written.
 restartfilestring, optional
Path to a restart file to use.
 highcadencedict, optional
A dictionary containing the following arguments:
'toggle'
{0,1}Whether or not highcadence output should be written (1=yes).
'start'
intTimestep at which highcadence output should begin.
'end'
intTimestep at which highcadence output should end.
'interval'
intHow many timesteps should elapse between highcadence outputs.
 thresholdfloat, optional
Energy balance threshold model should run to, if using
runtobalance()
. Default is <0.05 W/m\(^2\)/yr average drift in TOA and surface energy balance over 45year timescales. resourceslist, optional
A list of paths to any additional files that should be available in the run directory.
 runstepsinteger, optional
The number of timesteps to run each ‘year’. By default, this is tuned to 360 Earth days. If set, this will override other controls setting the length of each modelled year.
 otherargsdict, optional
Any namelist parameters not included by default in the configuration options. These should be passed as a dictionary, with “PARAMETER@namelist” as the form of the dictionary key, and the parameter value passed as a string. e.g.
otherargs={"N_RUN_MONTHS@plasim_namelist":'4',"NGUI@plasim_namelist:'1'}
Model Dynamics
 columnmode{None,”“,”clear”,”static”,”staticclear”,”clearstatic”}, optional
The inclusion of ‘static’ will disable horizontal advection, forcing ExoPlaSim into a columnonly mode of operation. The inclusion of ‘clear’ will disable the radiative effects of clouds.
 drycorebool, optional
True/False. If True, evaporation is turned off, and a dry atmosphere will be used.
 physicsfilterstr, optional
If not an empty string, specifies the physics filter(s) to be used. Filters can be used during the transform from gridpoint to spectral (
"gp"
), and/or during the transform from spectral to gridpoint ("sp"
). Filter types are “none”, “cesaro”, “exp”, or “lh” (see the Notes for more details). Combinations of filter types and times should be combined with a
, e.g.physicsfilter="gpexpsp"
orphysicsfilter="gpcesaro"
. filterkappafloat, optional
A constant to be used with the exponential filter. Default is 8.0.
 filterpowerint, optional
A constant integer to be used with the exponential filter. Default is 8.
 filterLHN0float, optional
The constant used in the denominator of the LanderHoskins Filter. Default is 15; typically chosen so f(N)=0.1.
 diffusionwavenint, optional
The critical wavenumber beyond which hyperdiffusion is applied. Default is 15 for T21.
 qdiffusionfloat, optional
Timescale for humidity hyperdiffusion in days. Default for T21 is 0.1.
 tdiffusionfloat, optional
Timescale for temperature hyperdiffusion in days. Default for T21 is 5.6.
 zdiffusionfloat, optional
Timescale for vorticity hyperdiffusion in days. Default for T21 is 1.1.
 ddiffusionfloat, optional
Timescale for divergence hyperdiffusion in days.. Default for T21 is 0.2.
 diffusionpowerint, optional
integer exponent used in hyperdiffusion. Default is 2 for T21.
Radiation
 fluxfloat, optional
Incident stellar flux in W/m\(^2\). Default 1367 for Earth.
 startempfloat, optional
Effective blackbody temperature for the star. Not used if not set.
 starradiusfloat, optional
Radius of the parent star in solar radii. Currently only used for the optional petitRADTRANS direct imaging postprocessor.
 starspecstr, optional
Spectral file for the stellar spectrum. Should have two columns and 965 rows, with wavelength in the first column and radiance or intensity in the second. A similarlynamed file with the “_hr.dat” suffix must also exist and have 2048 wavelengths. Appropriatelyformatted files can be created with
makestellarspec.py
. twobandalbedobool, optional
True/False. If True, separate albedos will be calculated for each of the two shortwave bands. If False (default), a single broadband albedo will be computed and used for both.
 synchronousbool, optional
True/False. If True, the Sun is fixed to one longitude in the sky.
 desyncfloat, optional
The rate of drift of the substellar point in degrees per minute. May be positive or negative.
 substellarlonfloat, optional
The longitude of the substellar point, if synchronous==True. Default 180°
 pressurebroadenbool, optional
True/False. If False, pressurebroadening of absorbers no longer depends on surface pressure. Default is True
 ozonebool or dict, optional
True/False/dict. Whether or not forcing from stratospheric ozone should be included. If a dict is provided, it should contain the keys “height”, “spread”, “amount”,”varlat”,”varseason”, and “seasonoffset”, which correspond to the height in meters of peak O3 concentration, the width of the gaussian distribution in meters, the baseline column amount of ozone in cmSTP, the latitudinal amplitude, the magnitude of seasonal variation, and the time offset of the seasonal variation in fraction of a year. The three amounts are additive. To set a uniform, unvarying O3 distribution, ,place all the ozone in “amount”, and set “varlat” and “varseason” to 0.
 snowicealbedofloat, optional
A uniform albedo to use for all snow and ice.
 soilalbedofloat, optional
A uniform albedo to use for all land.
 wetsoilbool, optional
True/False. If True, land albedo depends on soil moisture (wet=darker).
 oceanalbedofloat, optional
A uniform albedo to use for the ocean.
 oceanzenith{“ECHAM3”,”ECHAM6”,”Lambertian}, optional
The zenithangle dependence to use for bluelight reflectance from the ocean. Can be
'Lambertian'
/'uniform'
,'ECHAM3'
/'plasim'
/'default'
, or'ECHAM6'
. The default is'ECHAM3'
(synonymous with'plasim'
and'default'
), which is the dependence used in the ECHAM3 model.
Orbital Parameters
 yearfloat, optional
Number of 24hour days in a sidereal year. Not necessary if eccentricity and obliquity are zero. Defaults if not set to ~365.25 days
 rotationperiodfloat, optional
Planetary rotation period, in days. Default is 1.0.
 eccentricityfloat, optional
Orbital eccentricity. If not set, defaults to Earth’s (0.016715)
 obliquityfloat, optional
Axial tilt, in degrees. If not set, defaults to Earth’s obliquity (23.441°).
 lonvernaleqfloat, optional
Longitude of periapse, measured from vernal equinox, in degrees. If not set, defaults to Earth’s (102.7°).
 fixedorbitbool, optional
True/False. If True, orbital parameters do not vary over time. If False, variations such as Milankovich cycles will be computed by PlaSim.
 keplerianbool, optional
True/False. If True, a generic Keplerian orbital calculation will be performed. This means no orbital precession, Milankovich cycles, etc, but does allow for accurate calculation of a wide diversity of orbits, including with higher eccentricity. Note that extreme orbits may have extreme results, including extreme crashes.
 meananomaly0float, optional
The initial mean anomaly in degrees. Only used if keplerian=True.
Planet Parameters
 gravityfloat, optional
Surface gravity, in m/s\(^2\). Defaults to 9.80665 m/s\(^2\).
 radiusfloat, optional
Planet radius in Earth radii. Default is 1.0.
 orographyfloat, optional
If set, a scaling factor for topographic relief. If
orography=0.0
, topography will be zeroedout. aquaplanetbool, optional
True/False. If True, the surface will be entirely oceancovered.
 desertplanetbool, optional
True/False. If True, the surface will be entirely landcovered.
 tlcontrastfloat, optional
The initial surface temperature contrast between fixedlon and the anterior point. Default is 0.0 K.
 seaicebool, optional
True/False. If False, disables radiative effects of sea ice (although sea ice itself is still computed).
 landmapstr, optional
Path to a
.sra
file containing a land mask for the chosen resolution. topomapstr, optional
Path to a
.sra
file containing geopotential height map. Must include landmap.
Atmosphere
 gasconfloat, optional
Effective gas constant. Defaults to 287.0 (Earth), or the gas constant corresponding to the composition specified by partial pressures.
 vtype{0,1,2,3,4,5}, optional
Type of vertical discretization. Can be: 0 Pseudolinear scaling with pressure that maintains resolution near the ground. 1 Linear scaling with pressure. 2 Logarithmic scaling with pressure (resolves high altitudes) 3 Pseudologarithmic scaling with pressure that preserves resolution near the ground. 4 Pseudolinear scaling with pressure, pinned to a specified top pressure. 5 If >10 layers, bottom 10 as if
vtype=4
, and upper layers as ifvtype=2
. modeltopfloat, optional
Pressure of the top layer
 tropopausefloat, optional
If stratosphere is being included, pressure of the 10th layer (where scheme switches from linear to logarithmic).
 stratospherebool, optional
True/False. If True, vtype=5 is used, and model is discretized to include a stratosphere.
 pressure: float, optional
Surface pressure in bars, if not specified through partial pressures.
Gas Partial Pressures
Partial pressures of individual gases can be specified. If pressure and gascon are not explicitly set, these will determine surface pressure, mean molecular weight, and effective gas constant. Note however that Rayleigh scattering assumes an Earthlike composition, and the only absorbers explicitly included in the radiation scheme are CO2 and H2O.
 pH2float, optional
H2 partial pressure in bars.
 pHefloat, optional
He partial pressure in bars.
 pN2float, optional
N2 partial pressure in bars.
 pO2float, optional
O2 partial pressure in bars.
 pH2float, optional
H2 partial pressure in bars.
 pArfloat, optional
Ar partial pressure in bars.
 pNefloat, optional
Ne partial pressure in bars.
 pKrfloat, optional
Kr partial pressure in bars.
 pCO2float, optional
CO2 partial pressure in bars. This gets translated into a ppmv concentration, so if you want to specify/vary CO2 but don’t need the other gases, specifying pCO2, pressure, and gascon will do the trick. In most use cases, however, just specifying pN2 and pCO2 will give good enough behavior.
 pH2Ofloat, optional
H2O partial pressure in bars. This is only useful in setting the gas constant and surface pressure; it will have no effect on actual moist processes.
Surface Parameters
 mldepthfloat, optional
Depth of the mixedlayer ocean. Default is 50 meters.
 soildepthfloat, optional
Scaling factor for the depth of soil layers (default total of 12.4 meters)
 cpsoilfloat, optional
Heat capacity of the soil, in J/m^3/K. Default is 2.4*10^6.
 soilwatercapfloat, optional
Water capacity of the soil, in meters. Defaults to 0.5 meters
 soilsaturationfloat, optional
Initial fractional saturation of the soil. Default is 0.0 (dry).
 maxsnowfloat, optional
Maximum snow depth (Default is 5 meters; set to 1 to have no limit).
Additional Physics
 CarbonSilicate Weathering
 co2weatheringbool, optional
True/False. Toggles whether or not carbonsilicate weathering should be computed. Default is False.
 evolveco2bool, optional
True/False. If co2weathering==True, toggles whether or not the CO2 partial pressure should be updated every year. Usually the change in pCO2 will be extremely small, so this is not necessary, and weathering experiments try to estimate the average weathering rate for a given climate in order to interpolate timescales between climates, rather than modelling changes in CO2 over time directly.
 outgassingfloat, optional
The assumed CO2 outgassing rate in units of Earth outgassing. Default is 1.0.
 erosionsupplylimitfloat, optional
If set, the maximum CO2 weathering rate per year permitted by erosion, in ubars/year. This is not simply a hard cutoff, but follows Foley 2015 so high weathering below the cutoff is also reduced.
 Vegetation
 vegetationbool or int, optional
Can be True/False, or 0/1/2. If True or 1, then diagnostic vegetation is turned on. If 2, then coupled vegetation is turned on. Vegetation is computed via the SimBA module.
 vegaccelint, optional
Integer factor by which to accelerate vegetation growth
 nforestgrowth: float, optional
Biomass growth
 initgrowthfloat, optional
Initial aboveground growth
 initstomcondfloat, optional
Initial stomatal conductance
 initroughfloat, optional
Initial vegetative surface roughness
 initsoilcarbonfloat, optional
Initial soil carbon content
 initplantcarbonfloat, optional
Initial vegetative carbon content
See [1]_ for details on the implementation of supplylimited weathering.
 Glaciology
 glaciersdict, optional
A dictionary containing the following arguments: toggle : bool
True/False. Whether or not glaciers should be allowed to grow or shrink in thickness, or be formed from persistent snow on land.
 mindepthfloat
The minimum snow depth in meters of liquid water equivalent that must persist yearround before the grid cell is considered glaciated. Default is 2 meters.
 initialhfloat
If >=0, covers the land surface with ice sheets of a height given in meterss. If 1, no initial ice sheets are assumed.
 Storm Climatology
 stormclimbool, optional
True/False. Toggles whether or not storm climatology (convective available potential energy, maximum potential intensity, ventilation index, etc) should be computed. If True, output fields related to storm climatology will be added to standard output files. Enabling this mode currently roughly doubles the computational cost of the model. This may improve in future updates. Refer to Paradise, et al 2021 for implementation description.
 stormcapturedict, optional
A dictionary containing arguments controlling when highcadence output is triggered by storm activity. This dictionary must contain ‘toggle’, which can be either 1 or 0 (yes or no). It may also contain any namelist parameters accepted by hurricanemod.f90, including the following:
 toggle{0,1}
Whether (1) or not (0) to write highcadence output when storms occur
 NKTRIGGER{0,1}, optional
(0/1=no/yes). Whether or not to use the Komacek, et al 2020 conditions for hurricane cyclogenesis as the output trigger. Default is no.
 VITHRESHfloat, optional
(nktrigger) Ventilation index threshold for nktrigger output. Default 0.145
 VMXTHRESHfloat, optional
(nktrigger) Max potential intensity threshold for nktrigger output.Default 33 m/s
 LAVTHRESHfloat, optional
(nktrigger) Loweratmosphere vorticity threshold for nktrigger output. Default 1.2*10^5 s^1
 VRMTHRESHfloat, optional
(unused) Ventilationreduced maximum intensity threshold. Default 0.577
 GPITHRESHfloat, optional
(default) Genesis Potential Index threshold. Default 0.37.
 MINSURFTEMPfloat, optional
(default) Min. surface temperature for storm activity. Default 25C
 MAXSURFTEMPfloat, optional
(default) Max. surface temperature for storm activity. Default 100C
 WINDTHRESHfloat, optional
(default) Loweratmosphere maximum wind threshold for storm activity. Default 33 m/s
 SWINDTHRESHfloat, optional
(default) Minimum surface windspeed for storm activity. Default 20.5 m/s
 SIZETHRESHfloat, optional
(default) Minimum number of cells that must trigger to start outputDefault 30
 ENDTHRESHfloat, optional
(default) Minimum number of cells at which point storm output ends.Default 16
 MINSTORMLENfloat, optional
(default) Minimum number of timesteps to write output. Default 256
 MAXSTORMLENfloat, optional
(default) Maximum number of timesteps to write output. Default 1024
Note that actual number of writes will be stormlen/interval, as set in highcadence. This interval defaults to 4, so 64 writes minimum, 256 max. For more details on the storm climatology factors considered here, see [5]_.
Notes
In some cases, it may be necessary to include physics filters. This typically becomes necessary when sharp features are projected on the model’s smallest spectral modes, causing Gibbs “ripples”. Earthlike models typically do not require filtering, but tidallylocked models do. Filtering may be beneficial for Earthlike models at very high resolutions as well, or if there is sharp topography.
Three filter functional forms are included in ExoPlaSim: Cesaro, exponential, and LanderHoskins. Their functional forms are given below, where n is the wavenumber, and N is the truncation wavenumber (e.g. 21 for T21):
Cesaro: \(f(n)=1\frac{n}{N+1}\) [2]_
Exponential: \(f(n)=\exp\left[\kappa\left(\frac{n}{N}\right)^\gamma\right]\) [3]_
LanderHoskins: \(f(n)=\exp\left[\left(\frac{n(n+1)}{n_0(n_0+1}\right)^2\right]\) [3]_ [4]_
\(\kappa\) is exposed to the user through
filterkappa
, \(\gamma\) is exposed throughfilterpower
, and \(n_0\) is exposed throughfilterLHN0
.Physics filters can be applied at two different points; either at the transform from gridpoint to spectral, or the reverse. We find that in most cases, the ideal usage is to use both. Generally, a filter at the gridpoint>spectral transform is good for dealing with oscillations caused by sharp jumps and small features in the gridpoint tendencies. Conversely, a filter at the spectral>gridpoint transform is good for dealing with oscillations that come from smallscale features in the spectral fields causing smallscale features to appear in the gridpoint tendencies [3]_. Since we deal with climate systems where everything is coupled, any oscillations not removed by one filter will be amplified through physical feedbacks if not suppressed by the other filter.
References


class
exoplasim.
Model
(resolution='T21', layers=10, ncpus=4, precision=8, debug=False, inityear=0, recompile=False, optimization=None, mars=False, workdir='most', source=None, force991=False, modelname='MOST_EXP', outputtype='.npz', crashtolerant=False)[source]¶ Bases:
object
Create an ExoPlaSim model in a particular directory.
Initialize an ExoPlaSim model in a particular directory. If the necessary executable does not yet exist, compile it.
 Parameters:
resolution (str, optional) – The resolution of the model. Options are T21, T42, T63, T85, T106, T127, and T170, corresponding to 32, 64, 96, 128, 160, 192, and 256 latitudes respectively, and twice as many longitudes. ExoPlaSim has been tested and validated most extensively at T21 and T42. Higher resolutions will take considerable time to run.
layers (int, optional) – The number of vertical layers in the model atmosphere. The default is 10, but PlaSim has been used with 5 layers in many studies. More layers are supported, but not recommended except at higher resolutions.
ncpus (int, optional) – The number of MPI processes to use, typically the number of cores available. If ncpus=1, MPI will not be used.
precision (int, optional) – Either 4 or 8–specifies the number of bytes for a Fortran real.
debug (bool, optional) – If True, compiler optimizations are disabled and the code is compiled with debugging flags enabled that will allow linebyline tracebacks if ExoPlaSim crashes. Only use for development purposes.
inityear (int, optional) – The number to use for the initial model year (default 0).
recompile (bool, optional) – True/False flag used to force a recompile. Cannot force the model to skip compilation if the executable does not exist or compilationinducing flags are set.
optimization (str, optional) – Fortran compiler arguments for optimization. ANY compiler flags can be passed here, but it’s intended for optimization flags. Setting this will trigger a recompile.
mars (bool, optional) – True/False. If True, will use Marsspecific routines.
workdir (str, optional) – The directory in which to construct the model.
source (str, optional) – The directory in which to look for executables, namelists, boundary conditions, etc. If not set, will default to exoplasim/plasim/run/.
force991 (bool, optional) – Force the use of the FFT991 library instead of the default FFT library. Recommended for advanced use only.
modelname (str, optional) – The name to use for the model and its output files when finished.
outputtype (str, optional) – File extension to use for the output, if using the pyburn postprocessor. Supported extensions are .nc, .npy, .npz, .hdf5, .he5, .h5, .csv, .gz, .txt, .tar, .tar.gz, .tar.xz, and .tar.bz2. If using .nc, netcdf4python must be installed. If using any of .hdf5, .he5, or .h5, then h5py must be installed. The default is the numpy compressed format, .npz.
crashtolerant (bool, optional) – If True, then on a crash, ExoPlaSim will rewind 10 years and resume from there. If fewer than 10 years have elapsed, ExoPlaSim will simply crash.
 Returns:
An instantiated Model object that resides in a directory with the namelists and executable necessary to run ExoPlaSim.
 Return type:
Examples
>>> import exoplasim as exo >>> mymodel = exo.Model(workdir="mymodel_testrun",modelname="mymodel",resolution="T21",layers=10,ncpus=8) >>> mymodel.configure() >>> mymodel.exportcfg() >>> mymodel.run(years=100,crashifbroken=True) >>> mymodel.finalize("mymodel_output")
In this example, we initialize a model that will run in the directory “mymodel_testrun”, and has the name “mymodel”, which will be used to label output and error logs. The model has T21 resolution, or 32x64, 10 layers, and will run on 8 CPUs. By default, the compiler will use 8byte precision. 4byte may run slightly faster, but possibly at the cost of reduced stability. If there are machinespecific optimization flags you would like to use when compiling, you may specify them as a string to the optimization argument, e.g.
optimization='mavx'
. ExoPlaSim will check to see if an appropriate executable has already been created, and if not (or if flags indicating special compiler behavior such as debug=True or an optimization flag are set) it will compile one. We then configure the model with all the default parameter choices, which means we will get a model of Earth. We then export the model configurations to a.cfg
file (named automatically after the model), which will allow the model configuration to be recreated exactly by other users. We run the model for 100 years, with errorhandling enabled. Finally, we tell the model to clean up after itself. It will take the most recent output files and rename them after the model name we chose, and delete all the intermediate output and configuration files.
cfgpostprocessor
(ftype='regular', extension='.npz', namelist=None, variables=['50', '51', '52', '53', '54', '110', '129', '130', '131', '132', '133', '134', '135', '137', '138', '139', '140', '141', '142', '143', '144', '145', '146', '147', '148', '149', '151', '152', '155', '156', '157', '158', '159', '160', '161', '162', '163', '164', '165', '166', '167', '168', '169', '170', '171', '172', '173', '174', '175', '176', '177', '178', '179', '180', '181', '182', '183', '184', '203', '204', '205', '207', '208', '209', '210', '211', '218', '221', '230', '232', '238', '259', '260', '261', '262', '263', '264', '265', '266', '267', '268', '269', '273', '274', '277', '278', '279', '280', '298', '299', '300', '301', '302', '303', '304', '305', '306', '307', '308', '318', '319', '320', '321', '322', '323', '324', '325', '326', '327', '328', '329', '404', '405', '406', '407', '408', '409'], mode='grid', zonal=False, substellarlon=180.0, physfilter=False, timeaverage=True, stdev=False, times=12, interpolatetimes=True, transit=False, image=False, h2o_linelist='Exomol', cloudfunc=None, smooth=False, smoothweight=0.95)[source]¶ Configure postprocessor options for pyburn.
Output format is determined by the file extension of outfile. Current supported formats are NetCDF (.nc), numpy’s ``np.savez_compressed`` format (.npz), and CSV format. If NumPy’s singlearray .npy extension is used, .npz will be substituted–this is a compressed ZIP archive containing .npy files. Additionally, the CSV output format can be used in compressed form either individually by using the .gz file extension, or collectively via tarballs (compressed or uncompressed).
If a tarball format (e.g. *.tar or *.tar.gz) is used, output files will be packed into a tarball. gzip (.gz), bzip2 (.bz2), and lzma (.xz) compression types are supported. If a tarball format is not used, then accepted file extensions are .csv, .txt, or .gz. All three will produce a directory named following the filename pattern, with one file per variable in the directory. If the .gz extension is used, NumPy will compress each output file using gzip compression.
CSVtype files will only contain 2D variable information, so the first N1 dimensions will be flattened. The original variable shape is included in the file header (prepended with a # character) as the first items in a comma separated list, with the first nondimension item given as the ‘’ placeholder. On reading variables from these files, they should be reshaped according to these dimensions. This is true even in tarballs (which contain CSV files).
A T21 model output with 10 vertical levels, 12 output times, all supported variables in grid mode,and no standard deviation computation will have the following sizes for each format:
Format
Size
netCDF
12.8 MiB
HDF5
17.2 MiB
NumPy (default)
19.3 MiB
tar.xz
33.6 MiB
tar.bz2
36.8 MiB
gzipped
45.9 MiB
uncompressed
160.2 MiB
Using the NetCDF (.nc) format requires the netCDF4 python package.
Using the HDF4 format (.h5, .hdf5, .he5) requires the h5py python package.
All supported formats can be read by
exoplasim.gcmt.load()
and will return identical data objects analogous to netCDF4 archives. Parameters:
ftype (str, optional) – Which type of output to set for this–is this a regular output file (‘regular’), a snapshot output file (‘snapshot’), or highcadence (‘highcadence’)?
extension (str, optional) – Output format to use, specified via file extension. Supported formats are netCDF (
.nc
), NumPy compressed archives (.npy
,.npz
), HDF5 archives (.hdf5
,.he5
,.h5
), or plaintext commaseparated value files, which may be compressed individually or as a tarball (.csv
,.gz
,.txt
,.tar
,.tar.gz
,.tar.xz
, and.tar.bz2
). If using netCDF,netcdf4python
must be installed. If using HDF5, thenh5py
must be installed. The default is the numpy compressed format,.npz
.namelist (str, optional) – Path to a burn7 postprocessor namelist file. If not given, then variables must be set.
variables (list or dict, optional) – If a list is given, a list of either variable keycodes (integers or strings), or the abbreviated variable name (e.g. ‘ts’ for surface temperature). If a dict is given, each item in the dictionary should have the keycode or variable name as the key, and the desired horizontal mode and additional options for that variable as a subdict. Each member of the subdict should be passable as **kwargs to :py:func`pyburn.advancedDataset() <exoplasim.pyburn.advancedDataset>`. If None, then
namelist
must be set.mode (str, optional) – Horizontal output mode, if modes are not specified for individual variables. Options are ‘grid’, meaning the Gaussian latitudelongitude grid used in ExoPlaSim, ‘spectral’, meaning spherical harmonics, ‘fourier’, meaning Fourier coefficients and latitudes, ‘synchronous’, meaning a Gaussian latitudelongitude grid in the synchronous coordinate system defined in Paradise, et al (2021), with the north pole centered on the substellar point, or ‘syncfourier’, meaning Fourier coefficients computed along the dipolar meridians in the synchronous coordinate system (e.g. the substellarantistellarpolar meridian, which is 0 degrees, or the substellareveningantistellarmorning equatorial meridian, which is 90 degrees). Because this will get assigned to the original latitude array, that will become 90 degrees for the polar meridian, and 0 degrees for the equatorial meridian, identical to the typical equatorial coordinate system.
zonal (bool, optional) – Whether zonal means should be computed for applicable variables.
substellarlon (float, optional) – Longitude of the substellar point. Only relevant if a synchronous coordinate output mode is chosen.
physfilter (bool, optional) – Whether or not a physics filter should be used in spectral transforms.
times (int or arraylike or None, optional) – Either the number of timestamps by which to divide the output, or a list of times given as a fraction of the output file duration (which enables e.g. a higher frequency of outputs during periapse of an eccentric orbit, when insolation is changing more rapidly). Note that if a list is given, all members of the list MUST be between 0 and 1, inclusive. If None, the timestamps in the raw output will be written directly to file.
timeaverage (bool, optional) – Whether or not timestamps in the output file should be averaged to produce the requested number of output timestamps. Timestamps for averaged outputs will correspond to the middle of the averaged time period.
stdev (bool, optional) – Whether or not standard deviations should be computed. If timeaverage is True, this will be the standard deviation over the averaged time period; if False, then it will be the standard deviation over the whole duration of the output file
interpolatetimes (bool, optional) – If true, then if the times requested don’t correspond to existing timestamps, outputs will be linearly interpolated to those times. If false, then nearestneighbor interpolation will be used.

configure
(noutput=True, flux=1367.0, startemp=None, starradius=1.0, starspec=None, pH2=None, pHe=None, pN2=None, pO2=None, pCO2=None, pAr=None, pNe=None, pKr=None, pH2O=None, gascon=None, pressure=None, pressurebroaden=True, vtype=0, rotationperiod=1.0, synchronous=False, substellarlon=180.0, keplerian=False, meananomaly0=None, year=None, glaciers={'initialh':  1.0, 'mindepth': 2.0, 'toggle': False}, restartfile=None, gravity=None, radius=None, eccentricity=None, obliquity=None, lonvernaleq=None, fixedorbit=False, orography=None, seaice=True, co2weathering=False, evolveco2=False, physicsfilter=None, filterkappa=8.0, filterpower=8, filterLHN0=15.0, diffusionwaven=None, qdiffusion=None, tdiffusion=None, zdiffusion=None, ddiffusion=None, diffusionpower=None, erosionsupplylimit=None, outgassing=50.0, snowicealbedo=None, twobandalbedo=False, maxsnow=None, soilalbedo=None, oceanalbedo=None, oceanzenith='ECHAM3', wetsoil=False, soilwatercap=None, vegetation=False, vegaccel=1, nforestgrowth=1.0, initgrowth=0.5, initstomcond=1.0, initrough=2.0, initsoilcarbon=0.0, initplantcarbon=0.0, aquaplanet=False, desertplanet=False, soilsaturation=None, drycore=False, ozone=True, cpsoil=None, soildepth=1.0, mldepth=50.0, tlcontrast=0.0, desync=0.0, writefrequency=None, modeltop=None, stratosphere=False, top_restoretime=None, tropopause=None, timestep=45.0, runscript=None, columnmode=None, runsteps=None, highcadence={'end': 576, 'interval': 4, 'start': 320, 'toggle': 0}, snapshots=None, resources=[], landmap=None, stormclim=False, nstorms=4, stormcapture={'ENDTHRESH': 16, 'GPITHRESH': 0.37, 'LAVTHRESH': 1.2e05, 'MAXSTORMLEN': 1024, 'MAXSURFTEMP': 373.15, 'MINSTORMLEN': 256, 'MINSURFTEMP': 298.15, 'NKTRIGGER': 0, 'SIZETHRESH': 30, 'SWINDTHRESH': 20.5, 'VITHRESH': 0.145, 'VMXTHRESH': 33.0, 'VRMTHRESH': 0.577, 'WINDTHRESH': 33.0, 'toggle': 0}, topomap=None, threshold=0.0005, otherargs={})[source]¶ Configure the model’s namelists and boundary conditions.
The defaults here are appropriate for an Earth model.
Model Operation
 noutputbool, optional
True/False. Whether or not model output should be written.
 restartfilestr, optional
Path to a restart file to use for initial conditions. Can be None.
 writefrequencyint, optional
How many times per day ExoPlaSim should write output. Ignored by default–default is to write timeaveraged output once every 5 days.
 timestepfloat, optional
Model timestep. Defaults to 45 minutes.
 runscriptfunction , optional
A Python function that accepts a Model object as its first argument. This is the routine that will be run when you issue the Model.run() command. Any keyword arguments passed to run() will be forwarded to the specified function. If not set, the default internal routine will be used.
 snapshotsint, optional
How many timesteps should elapse between snapshot outputs. If not set, no snapshots will be written.
 restartfilestring, optional
Path to a restart file to use.
 highcadencedict, optional
A dictionary containing the following arguments:
'toggle'
{0,1}Whether or not highcadence output should be written (1=yes).
'start'
intTimestep at which highcadence output should begin.
'end'
intTimestep at which highcadence output should end.
'interval'
intHow many timesteps should elapse between highcadence outputs.
 thresholdfloat, optional
Energy balance threshold model should run to, if using
runtobalance()
. Default is <0.05 W/m\(^2\)/yr average drift in TOA and surface energy balance over 45year timescales. resourceslist, optional
A list of paths to any additional files that should be available in the run directory.
 runstepsinteger, optional
The number of timesteps to run each ‘year’. By default, this is tuned to 360 Earth days. If set, this will override other controls setting the length of each modelled year.
 otherargsdict, optional
Any namelist parameters not included by default in the configuration options. These should be passed as a dictionary, with “PARAMETER@namelist” as the form of the dictionary key, and the parameter value passed as a string. e.g.
otherargs={"N_RUN_MONTHS@plasim_namelist":'4',"NGUI@plasim_namelist:'1'}
Model Dynamics
 columnmode{None,”“,”clear”,”static”,”staticclear”,”clearstatic”}, optional
The inclusion of ‘static’ will disable horizontal advection, forcing ExoPlaSim into a columnonly mode of operation. The inclusion of ‘clear’ will disable the radiative effects of clouds.
 drycorebool, optional
True/False. If True, evaporation is turned off, and a dry atmosphere will be used.
 physicsfilterstr, optional
If not an empty string, specifies the physics filter(s) to be used. Filters can be used during the transform from gridpoint to spectral (
"gp"
), and/or during the transform from spectral to gridpoint ("sp"
). Filter types are “none”, “cesaro”, “exp”, or “lh” (see the Notes for more details). Combinations of filter types and times should be combined with a
, e.g.physicsfilter="gpexpsp"
orphysicsfilter="gpcesaro"
. filterkappafloat, optional
A constant to be used with the exponential filter. Default is 8.0.
 filterpowerint, optional
A constant integer to be used with the exponential filter. Default is 8.
 filterLHN0float, optional
The constant used in the denominator of the LanderHoskins Filter. Default is 15; typically chosen so f(N)=0.1.
 diffusionwavenint, optional
The critical wavenumber beyond which hyperdiffusion is applied. Default is 15 for T21.
 qdiffusionfloat, optional
Timescale for humidity hyperdiffusion in days. Default for T21 is 0.1.
 tdiffusionfloat, optional
Timescale for temperature hyperdiffusion in days. Default for T21 is 5.6.
 zdiffusionfloat, optional
Timescale for vorticity hyperdiffusion in days. Default for T21 is 1.1.
 ddiffusionfloat, optional
Timescale for divergence hyperdiffusion in days.. Default for T21 is 0.2.
 diffusionpowerint, optional
integer exponent used in hyperdiffusion. Default is 2 for T21.
Radiation
 fluxfloat, optional
Incident stellar flux in W/m\(^2\). Default 1367 for Earth.
 startempfloat, optional
Effective blackbody temperature for the star. Not used if not set.
 starradiusfloat, optional
Radius of the parent star in solar radii. Currently only used for the optional petitRADTRANS direct imaging postprocessor.
 starspecstr, optional
Spectral file for the stellar spectrum. Should have two columns and 965 rows, with wavelength in the first column and radiance or intensity in the second. A similarlynamed file with the “_hr.dat” suffix must also exist and have 2048 wavelengths. Appropriatelyformatted files can be created with
makestellarspec.py
. twobandalbedobool, optional
True/False. If True, separate albedos will be calculated for each of the two shortwave bands. If False (default), a single broadband albedo will be computed and used for both.
 synchronousbool, optional
True/False. If True, the Sun is fixed to one longitude in the sky.
 desyncfloat, optional
The rate of drift of the substellar point in degrees per minute. May be positive or negative.
 substellarlonfloat, optional
The longitude of the substellar point, if synchronous==True. Default 180°
 pressurebroadenbool, optional
True/False. If False, pressurebroadening of absorbers no longer depends on surface pressure. Default is True
 ozonebool or dict, optional
True/False/dict. Whether or not forcing from stratospheric ozone should be included. If a dict is provided, it should contain the keys “height”, “spread”, “amount”,”varlat”,”varseason”, and “seasonoffset”, which correspond to the height in meters of peak O3 concentration, the width of the gaussian distribution in meters, the baseline column amount of ozone in cmSTP, the latitudinal amplitude, the magnitude of seasonal variation, and the time offset of the seasonal variation in fraction of a year. The three amounts are additive. To set a uniform, unvarying O3 distribution, ,place all the ozone in “amount”, and set “varlat” and “varseason” to 0.
 snowicealbedofloat, optional
A uniform albedo to use for all snow and ice.
 soilalbedofloat, optional
A uniform albedo to use for all land.
 wetsoilbool, optional
True/False. If True, land albedo depends on soil moisture (wet=darker).
 oceanalbedofloat, optional
A uniform albedo to use for the ocean.
 oceanzenith{“ECHAM3”,”ECHAM6”,”Lambertian}, optional
The zenithangle dependence to use for bluelight reflectance from the ocean. Can be
'Lambertian'
/'uniform'
,'ECHAM3'
/'plasim'
/'default'
, or'ECHAM6'
. The default is'ECHAM3'
(synonymous with'plasim'
and'default'
), which is the dependence used in the ECHAM3 model.
Orbital Parameters
 yearfloat, optional
Number of 24hour days in a sidereal year. Not necessary if eccentricity and obliquity are zero. Defaults if not set to ~365.25 days
 rotationperiodfloat, optional
Planetary rotation period, in days. Default is 1.0.
 eccentricityfloat, optional
Orbital eccentricity. If not set, defaults to Earth’s (0.016715)
 obliquityfloat, optional
Axial tilt, in degrees. If not set, defaults to Earth’s obliquity (23.441°).
 lonvernaleqfloat, optional
Longitude of periapse, measured from vernal equinox, in degrees. If not set, defaults to Earth’s (102.7°).
 fixedorbitbool, optional
True/False. If True, orbital parameters do not vary over time. If False, variations such as Milankovich cycles will be computed by PlaSim.
 keplerianbool, optional
True/False. If True, a generic Keplerian orbital calculation will be performed. This means no orbital precession, Milankovich cycles, etc, but does allow for accurate calculation of a wide diversity of orbits, including with higher eccentricity. Note that extreme orbits may have extreme results, including extreme crashes.
 meananomaly0float, optional
The initial mean anomaly in degrees. Only used if keplerian=True.
Planet Parameters
 gravityfloat, optional
Surface gravity, in m/s\(^2\). Defaults to 9.80665 m/s\(^2\).
 radiusfloat, optional
Planet radius in Earth radii. Default is 1.0.
 orographyfloat, optional
If set, a scaling factor for topographic relief. If
orography=0.0
, topography will be zeroedout. aquaplanetbool, optional
True/False. If True, the surface will be entirely oceancovered.
 desertplanetbool, optional
True/False. If True, the surface will be entirely landcovered.
 tlcontrastfloat, optional
The initial surface temperature contrast between fixedlon and the anterior point. Default is 0.0 K.
 seaicebool, optional
True/False. If False, disables radiative effects of sea ice (although sea ice itself is still computed).
 landmapstr, optional
Path to a
.sra
file containing a land mask for the chosen resolution. topomapstr, optional
Path to a
.sra
file containing geopotential height map. Must include landmap.
Atmosphere
 gasconfloat, optional
Effective gas constant. Defaults to 287.0 (Earth), or the gas constant corresponding to the composition specified by partial pressures.
 vtype{0,1,2,3,4,5}, optional
Type of vertical discretization. Can be: 0 Pseudolinear scaling with pressure that maintains resolution near the ground. 1 Linear scaling with pressure. 2 Logarithmic scaling with pressure (resolves high altitudes) 3 Pseudologarithmic scaling with pressure that preserves resolution near the ground. 4 Pseudolinear scaling with pressure, pinned to a specified top pressure. 5 If >10 layers, bottom 10 as if
vtype=4
, and upper layers as ifvtype=2
. modeltopfloat, optional
Pressure of the top layer
 tropopausefloat, optional
If stratosphere is being included, pressure of the 10th layer (where scheme switches from linear to logarithmic).
 stratospherebool, optional
True/False. If True, vtype=5 is used, and model is discretized to include a stratosphere.
 pressure: float, optional
Surface pressure in bars, if not specified through partial pressures.
Gas Partial Pressures
Partial pressures of individual gases can be specified. If pressure and gascon are not explicitly set, these will determine surface pressure, mean molecular weight, and effective gas constant. Note however that Rayleigh scattering assumes an Earthlike composition, and the only absorbers explicitly included in the radiation scheme are CO2 and H2O.
 pH2float, optional
H2 partial pressure in bars.
 pHefloat, optional
He partial pressure in bars.
 pN2float, optional
N2 partial pressure in bars.
 pO2float, optional
O2 partial pressure in bars.
 pH2float, optional
H2 partial pressure in bars.
 pArfloat, optional
Ar partial pressure in bars.
 pNefloat, optional
Ne partial pressure in bars.
 pKrfloat, optional
Kr partial pressure in bars.
 pCO2float, optional
CO2 partial pressure in bars. This gets translated into a ppmv concentration, so if you want to specify/vary CO2 but don’t need the other gases, specifying pCO2, pressure, and gascon will do the trick. In most use cases, however, just specifying pN2 and pCO2 will give good enough behavior.
 pH2Ofloat, optional
H2O partial pressure in bars. This is only useful in setting the gas constant and surface pressure; it will have no effect on actual moist processes.
Surface Parameters
 mldepthfloat, optional
Depth of the mixedlayer ocean. Default is 50 meters.
 soildepthfloat, optional
Scaling factor for the depth of soil layers (default total of 12.4 meters)
 cpsoilfloat, optional
Heat capacity of the soil, in J/m^3/K. Default is 2.4*10^6.
 soilwatercapfloat, optional
Water capacity of the soil, in meters. Defaults to 0.5 meters
 soilsaturationfloat, optional
Initial fractional saturation of the soil. Default is 0.0 (dry).
 maxsnowfloat, optional
Maximum snow depth (Default is 5 meters; set to 1 to have no limit).
Additional Physics
 CarbonSilicate Weathering
 co2weatheringbool, optional
True/False. Toggles whether or not carbonsilicate weathering should be computed. Default is False.
 evolveco2bool, optional
True/False. If co2weathering==True, toggles whether or not the CO2 partial pressure should be updated every year. Usually the change in pCO2 will be extremely small, so this is not necessary, and weathering experiments try to estimate the average weathering rate for a given climate in order to interpolate timescales between climates, rather than modelling changes in CO2 over time directly.
 outgassingfloat, optional
The assumed CO2 outgassing rate in units of Earth outgassing. Default is 1.0.
 erosionsupplylimitfloat, optional
If set, the maximum CO2 weathering rate per year permitted by erosion, in ubars/year. This is not simply a hard cutoff, but follows Foley 2015 so high weathering below the cutoff is also reduced.
 Vegetation
 vegetationbool or int, optional
Can be True/False, or 0/1/2. If True or 1, then diagnostic vegetation is turned on. If 2, then coupled vegetation is turned on. Vegetation is computed via the SimBA module.
 vegaccelint, optional
Integer factor by which to accelerate vegetation growth
 nforestgrowth: float, optional
Biomass growth
 initgrowthfloat, optional
Initial aboveground growth
 initstomcondfloat, optional
Initial stomatal conductance
 initroughfloat, optional
Initial vegetative surface roughness
 initsoilcarbonfloat, optional
Initial soil carbon content
 initplantcarbonfloat, optional
Initial vegetative carbon content
See [1]_ for details on the implementation of supplylimited weathering.
 Glaciology
 glaciersdict, optional
A dictionary containing the following arguments: toggle : bool
True/False. Whether or not glaciers should be allowed to grow or shrink in thickness, or be formed from persistent snow on land.
 mindepthfloat
The minimum snow depth in meters of liquid water equivalent that must persist yearround before the grid cell is considered glaciated. Default is 2 meters.
 initialhfloat
If >=0, covers the land surface with ice sheets of a height given in meterss. If 1, no initial ice sheets are assumed.
 Storm Climatology
 stormclimbool, optional
True/False. Toggles whether or not storm climatology (convective available potential energy, maximum potential intensity, ventilation index, etc) should be computed. If True, output fields related to storm climatology will be added to standard output files. Enabling this mode currently roughly doubles the computational cost of the model. This may improve in future updates. Refer to Paradise, et al 2021 for implementation description.
 stormcapturedict, optional
A dictionary containing arguments controlling when highcadence output is triggered by storm activity. This dictionary must contain ‘toggle’, which can be either 1 or 0 (yes or no). It may also contain any namelist parameters accepted by hurricanemod.f90, including the following:
 toggle{0,1}
Whether (1) or not (0) to write highcadence output when storms occur
 NKTRIGGER{0,1}, optional
(0/1=no/yes). Whether or not to use the Komacek, et al 2020 conditions for hurricane cyclogenesis as the output trigger. Default is no.
 VITHRESHfloat, optional
(nktrigger) Ventilation index threshold for nktrigger output. Default 0.145
 VMXTHRESHfloat, optional
(nktrigger) Max potential intensity threshold for nktrigger output.Default 33 m/s
 LAVTHRESHfloat, optional
(nktrigger) Loweratmosphere vorticity threshold for nktrigger output. Default 1.2*10^5 s^1
 VRMTHRESHfloat, optional
(unused) Ventilationreduced maximum intensity threshold. Default 0.577
 GPITHRESHfloat, optional
(default) Genesis Potential Index threshold. Default 0.37.
 MINSURFTEMPfloat, optional
(default) Min. surface temperature for storm activity. Default 25C
 MAXSURFTEMPfloat, optional
(default) Max. surface temperature for storm activity. Default 100C
 WINDTHRESHfloat, optional
(default) Loweratmosphere maximum wind threshold for storm activity. Default 33 m/s
 SWINDTHRESHfloat, optional
(default) Minimum surface windspeed for storm activity. Default 20.5 m/s
 SIZETHRESHfloat, optional
(default) Minimum number of cells that must trigger to start outputDefault 30
 ENDTHRESHfloat, optional
(default) Minimum number of cells at which point storm output ends.Default 16
 MINSTORMLENfloat, optional
(default) Minimum number of timesteps to write output. Default 256
 MAXSTORMLENfloat, optional
(default) Maximum number of timesteps to write output. Default 1024
Note that actual number of writes will be stormlen/interval, as set in highcadence. This interval defaults to 4, so 64 writes minimum, 256 max. For more details on the storm climatology factors considered here, see [5]_.
Notes
In some cases, it may be necessary to include physics filters. This typically becomes necessary when sharp features are projected on the model’s smallest spectral modes, causing Gibbs “ripples”. Earthlike models typically do not require filtering, but tidallylocked models do. Filtering may be beneficial for Earthlike models at very high resolutions as well, or if there is sharp topography.
Three filter functional forms are included in ExoPlaSim: Cesaro, exponential, and LanderHoskins. Their functional forms are given below, where n is the wavenumber, and N is the truncation wavenumber (e.g. 21 for T21):
Cesaro: \(f(n)=1\frac{n}{N+1}\) [2]_
Exponential: \(f(n)=\exp\left[\kappa\left(\frac{n}{N}\right)^\gamma\right]\) [3]_
LanderHoskins: \(f(n)=\exp\left[\left(\frac{n(n+1)}{n_0(n_0+1}\right)^2\right]\) [3]_ [4]_
\(\kappa\) is exposed to the user through
filterkappa
, \(\gamma\) is exposed throughfilterpower
, and \(n_0\) is exposed throughfilterLHN0
.Physics filters can be applied at two different points; either at the transform from gridpoint to spectral, or the reverse. We find that in most cases, the ideal usage is to use both. Generally, a filter at the gridpoint>spectral transform is good for dealing with oscillations caused by sharp jumps and small features in the gridpoint tendencies. Conversely, a filter at the spectral>gridpoint transform is good for dealing with oscillations that come from smallscale features in the spectral fields causing smallscale features to appear in the gridpoint tendencies [3]_. Since we deal with climate systems where everything is coupled, any oscillations not removed by one filter will be amplified through physical feedbacks if not suppressed by the other filter.
References

emergencyabort
()[source]¶ A problem has been encountered by an external script, and the model needs to crash gracefully

exportcfg
(filename=None)[source]¶ Export model configuration to a text file that can be used as configuration input
Write the current model configuration to a text file. This file can be shared and used by other users to recreate your model configuration.
 Parameters:
filename (str, optional) – Path to the file that should be written. If None (default), <modelname>.cfg will be created in the working directory.
See also
loadconfig
: Load a saved configuration.

finalize
(outputdir, allyears=False, keeprestarts=False, clean=True)[source]¶ Move outputs and optionally restarts to a specified output directory.
If more than the final year of output is being kept, a folder will be created in the output directory using the model name. Otherwise, finalized files will be renamed using the model name.
 Parameters:
outputdir (str) – Directory in which to put output.
allyears (bool, optional) – True/False. If True, output from all years will be kept, in a directory in outputdir named with the model name. Otherwise, the most recent year will be kept in outputdir, using the model name. Default False.
keeprestarts (bool, optional) – True/False: If True, restart files will be kept as well as output files. Default False.
clean (bool, optional) – True/False. If True, the original working directory will be deleted after files are moved. Default True.

get
(year, snapshot=False, highcadence=False)[source]¶ Return an open NetCDF data object for the given year. Defaults is to return timeaveraged output.
 Parameters:
year (int) – Integer year of output to return
snapshot (bool, optional) – True/False. If True, return the snapshot version.
highcadence (bool, optional) – True/False. If True, return the highcadence version.
 Returns:
An open netCDF4 data opject
 Return type:
netCDF4.Dataset

getbalance
(key, year= 1)[source]¶ Return the global annual mean of a given variable for a given year
 Parameters:
key (str) – The output variable string to return
year (int, optional) – Which year to go to for output
 Returns:
Global annual mean of requested quantity
 Return type:
float

gethistory
(key='ts', mean=True, layer= 1)[source]¶ Return the an array of global annual means of a given variable for each year
 Parameters:
key (str, optional) – The output variable string to return
mean (bool, optional) – Toggle whether we return the mean or the sum
year (int, optional) – Which year to go to for output
 Returns:
1D Array of global annual means
 Return type:
numpy.ndarray

image
(year, times, obsv_coords, snapshot=True, highcadence=False, h2o_linelist='Exomol', num_cpus=None, cloudfunc=None, smooth=True, smoothweight=0.95, filldry=1e06, orennayar=True, debug=False, logfile=None, filename=None, inputfile=None, baremountainz=50000.0, colorspace='sRGB', gamma=True, consistency=True, vegpowerlaw=1.0)[source]¶ Compute reflection+emission spectra for snapshot output
This routine computes the reflection+emission spectrum for the planet at each indicated time.
Note that deciding what the observer coordinates ought to be may not be a trivial operation. Simply setting them to always be the same is fine for a 1:1 synchronouslyrotating planet, where the insolation pattern never changes. But for an Earthlike rotator, you will need to be mindful of rotation rate and the local time when snapshots are written. Perhaps you would like to see how things look as the local time changes, as a geosynchronous satellite might observe, or maybe you’d like to only observe in secondary eclipse or in quadrature, and so the observerfacing coordinates may not be the same each time.
 Parameters:
year (int) – Year of output that should be imaged.
times (list(int)) – List of time indices at which the image should be computed.
obsv_coords (numpy.ndarray (3D)) – List of observer (lat,lon) coordinates for each observing time. First axis is time, second axis is for each observer; the third axis is for lat and lon. Should have shape (time,observers,latlon). These are the surface coordinates that are directly facing the observer.
snapshot (bool, optional) – Whether snapshot output should be used.
highcadence (bool, optional) – Whether highcadence output should be used.
h2o_linelist ({'HITEMP','EXOMOL'}, optional) – Either ‘HITEMP’ or ‘EXOMOL’–the line list from which H2O absorption should be sourced
num_cpus (int, optional) – The number of CPUs to use
cloudfunc (function, optional) – A routine which takes pressure, temperature, and cloud water content as arguments, and returns keyword arguments to be unpacked into calc_flux_transm. If not specified, basicclouds will be used.
smooth (bool, optional) – Whether or not to smooth humidity and cloud columns. As of Nov 12, 2021, it is recommended that you use smooth=True for wellbehaved spectra. This is a conservative smoothing operation, meaning the water and cloud column mass should be conserved–what this does is move some water from the waterrich layers into the layers directly above and below.
smoothweight (float, optional) – The fraction of the water in a layer that should be retained during smoothing. A higher value means the smoothing is less severe. 0.95 is probably the upper limit for wellbehaved spectra.
filldry (float, optional) – If nonzero, the floor value for water humidity when moist layers are present above dry layers. Columns will be adjusted in a massconserving manner with excess humidity accounted for in layers above the filled layer, such that total optical depth from TOA is maintained at the dry layer.
orennayar (bool, optional) – If True, compute truecolour intensity using OrenNayar scattering instead of Lambertian scattering. Most solar system bodies do not exhibit Lambertian scattering.
debug (bool, optional) – Optional debugging mode, that outputs intermediate quantities used in the imaging process.
logfile (str, optional) – Optional log file to write diagnostics to.
filename (str, optional) – Output filename; will be autogenerated if None.
inputfile (str, optional) – If provided, ignore the year argument and image the provided output file.
baremountainz (float, optional) – If vegetation is present, the geopotential above which mountains become bare rock instead of eroded vegetative regolith. Functionally, this means gray rock instead of brown/tan ground.
colorspace (str or np.ndarray(3,3)) – Color gamut to be used. For available builtin color gamuts, see colormatch.colorgamuts.
gamma (bool or float, optional) – If True, use the piecewise gammafunction defined for sRGB; otherwise if a float, use rgb^(1/gamma). If None, gamma=1.0 is used.
consistency (bool, optional) – If True, force surface albedo to match model output
vegpowerlaw (float, optional) – Scale the apparent vegetation fraction by a power law. Setting this to 0.1, for example, will increase the area that appears partiallyvegetated, while setting it to 1.0 leaves vegetation unchanged.
 Returns:
pRT Atmosphere object, filename the output file generated. Output file can be stored in any of ExoPlaSim’s standard supported output formats.
 Return type:
petitRADTRANS.Atmosphere, str

inspect
(variable, year= 1, ignoreNaNs=True, snapshot=False, highcadence=False, savg=False, tavg=False, layer=None)[source]¶ Return a given output variable from a given year or list of years, with optional averaging parameters.
 Parameters:
variable (str) – The name of the variable to return.
year (int, optional OR arraylike) – Which year of output to return. Year indexing follows Pythonic rules. If the model has been finalized, only the final year of output will be returned. If year is an arraylike with length>1, the years implied by the list will be concatenated into a single output, along the time axis.
ignoreNaNs (bool, optional) – True/False. If True, use NaNtolerant numpy functions.
snapshot (bool, optional) – True/False. If True, use snapshot output instead of timeaveraged.
highcadence (bool, optional) – True/False. If True, use highcadednce output instead of timeaveraged.
savg (bool, optional) – True/False. If True, compute the spatial average. Default False
tavg (bool, optional) – True/False. If True, compute the annual average. Default False
layer (int, optional) – If specified and data has 3 spatial dimensions, extract the specified layer. If unspecified and data has 3 spatial dimensions, the vertical dimension will be preserved (even if spatial averages are being computed).
 Returns:
The requested data, averaged if that was requested.
 Return type:
float or numpy.ndarray

integritycheck
(ncfile)[source]¶ Check an output file to see it contains the expected variables and isn’t full of NaNs.
If the file does not exist, exoplasim will attempt to create it using the postprocessor. If the file does not have the expected variables or is full of trash, an exception will be raised. If the file is fine, this function returns a 1. If the file did not exist and cannot be created, this function will return a 0.
 Parameters:
ncfile (str) – The output file to check.
 Returns:
0 or 1 depending on failure or success respectively
 Return type:
int

loadconfig
(configfile)[source]¶ Load a previouslyexported configuration file and configure the model accordingly.
 Parameters:
configfile (str) – Path to the configuration file to load
See also
exportcfg
: Export model configuration to a text file.

modify
(**kwargs)[source]¶ Modify any alreadyconfigured parameters. All parameters accepted by
configure()
can be passed as arguments.See also
configure
: Set model parameters and boundary conditions

postprocess
(inputfile, variables, ftype='regular', log='postprocess.log', crashifbroken=False, transit=False, image=False, **kwargs)[source]¶ Produce NetCDF output from an input file, using a specified postprocessing namelist.
 Parameters:
inputfile (str) – The raw output file to be processed
variables (str or list or dict or None) – Can be a path to a burn7style namelist, a list of variable codes or keys, or a dictionary containing output options for each variable. If None, then a variable set preconfigured with :py:func`Model.cfgpostprocessor() <exoplasim.Model.cfgpostprocessor>` will be used. If the postprocessor was not preconfigured, this will prompt pyburn to use the default set.
ftype (str, optional) – Which type of output to set for this–is this a regular output file (‘regular’), a snapshot output file (‘snapshot’), or highcadence (‘highcadence’)?
log (str, optional) – The log file to which pyburn should output standard output and errors
crashifbroken (bool, optional) – True/False. If True, exoplasim will run .integritycheck() on the file.
**kwargs (keyword arguments) – Keyword arguments accepted by pyburn.postprocess. Do not specify radius, gravity, or gascon. These are set by the model configuration. Specifying additional keywords here will override any options set via :py:func`Model.cfgpostprocessor() <exoplasim.Model.cfgpostprocessor>`
 Returns:
1 if successful, 0 if not
 Return type:
int

run
(**kwargs)[source]¶ Run the Model’s designated run routine.
This may have been passed as runscript when the model was created, or it could be the model’s internal ._run() routine. That method takes the following arguments:
 Parameters:
years (int, optional) – Number of years to run
postprocess (bool, optional) – True/False. Whether or not output files should be produced onthefly
crashifbroken (bool, optional) – True/False. If True, use Pythonic error handling
clean (bool, optional) – True/False. If True, delete raw output files once output files are made

runtobalance
(threshold=None, baseline=50, maxyears=300, minyears=75, timelimit=None, crashifbroken=True, clean=True, diagnosticvars=None)[source]¶ Run the model until energy balance equilibrium is reached at the top and surface.
 Parameters:
threshold (float, optional) – If specified, overrides the threshold set by
.config()
. The model will run until the energy balance at the top and surface drifts by less than this amount per year over a given baseline.baseline (int, optional) – The number of years over which to evaluate energy balance drift. Default 50
maxyears (int, optional) – The maximum number of years to run before returning. Default 300. This is useful if you are running on a scratch disk with limited space.
minyears (int, optional) – The minimum number of years to run before determining that the model is in equilibrium.
timelimit (float, optional) – If set, maxyears will be revised each year based on the average minutes per year thus far, to try to avoid going over the time limit, which should be given in minutes.
crashifbroken (bool, optional) – True/False. If True, Pythonic error handling is enabled. Default True.
clean (bool, optional) – True/False. If True, raw output is deleted once postprocessed. Default True.
diagnosticvars (arraylike, optional) – List of output variables for which global annual means should be computed and printed to standard output each year.
 Returns:
True if the model reached equilibrium, False if not.
 Return type:
bool

save
(filename=None)[source]¶ Save the current Model object to a NumPy save file.
The model object can then be reinstantiated using
numpy.load(savefile).item()
. Parameters:
filename (str, optional) – Filename to save to. If unspecified, will default to <modelname>.npy.
Notes
Note that these files are often not portable between versions of Python or machine architectures, so their use is only recommended internally. For sharing with other users, it is recommended that you use the
exportcfg
function.See also
exportcfg
: Export model configuration to a portable text file.

transit
(year, times, inputfile=None, snapshot=True, highcadence=False, h2o_linelist='Exomol', num_cpus=1, cloudfunc=None, smooth=False, smoothweight=0.95, logfile=None, filename=None)[source]¶ Compute transmission spectra for snapshot output
This routine computes the transmission spectrum for each atmospheric column along the terminator, for each time in transittimes.
Note: This routine does not currently include emission from atmospheric layers.
 Parameters:
year (int) – Year of output that should be imaged.
times (list(int)) – List of time indices at which the image should be computed.
inputfile (str, optional) – If provided, ignore the year argument and image the provided output file.
snapshot (bool, optional) – Whether snapshot output should be used.
highcadence (bool, optional) – Whether highcadence output should be used.
h2o_lines ({'HITEMP','EXOMOL'}, optional) – Either ‘HITEMP’ or ‘EXOMOL’–the line list from which H2O absorption should be sourced
num_cpus (int, optional) – The number of CPUs to use
cloudfunc (function, optional) – A routine which takes pressure, temperature, and cloud water content as arguments, and returns keyword arguments to be unpacked into calc_flux_transm. If not specified, basicclouds will be used.
smooth (bool, optional) – Whether or not to smooth humidity and cloud columns. As of Nov 12, 2021, it is recommended that you use smooth=True for wellbehaved spectra. This is a conservative smoothing operation, meaning the water and cloud column mass should be conserved–what this does is move some water from the waterrich layers into the layers directly above and below.
smoothweight (float, optional) – The fraction of the water in a layer that should be retained during smoothing. A higher value means the smoothing is less severe. 0.95 is probably the upper limit for wellbehaved spectra.
logfile (str, optional) – Optional log file to which diagnostic info will be written.
filename (str, optional) – Output filename; will be autogenerated if None.
 Returns:
pRT Atmosphere object, filename the output file generated. Output file can be stored in any of ExoPlaSim’s standard supported output formats. Transit radius is in km.
 Return type:
petitRADTRANS.Atmosphere, str

class
exoplasim.
TLaquaplanet
(resolution='T21', layers=10, ncpus=4, precision=8, debug=False, inityear=0, recompile=False, optimization=None, mars=False, workdir='most', source=None, force991=False, modelname='MOST_EXP', outputtype='.npz', crashtolerant=False)[source]¶ Bases:
exoplasim.Model
Create a tidallylocked planet with no land.
Identical to
Model
, except configuration options suitable for tidallylocked models are the default when configure() is called, and the surface is entirely oceancovered. Specifically, a 30minute timestep, snapshot outputs every 720 timesteps, eccentricity=0.0, 0degree obliquity, exponential physics filtering, fixed orbital parameters, and no ozone. All these defaults can be overridden.
configure
(timestep=30.0, snapshots=720, eccentricity=0.0, ozone=False, obliquity=0.0, physicsfilter='gpexpsp', tlcontrast=100.0, **kwargs)[source]¶ Configure the model’s namelists and boundary conditions.
The defaults here are appropriate for an Earth model.
Model Operation
 noutputbool, optional
True/False. Whether or not model output should be written.
 restartfilestr, optional
Path to a restart file to use for initial conditions. Can be None.
 writefrequencyint, optional
How many times per day ExoPlaSim should write output. Ignored by default–default is to write timeaveraged output once every 5 days.
 timestepfloat, optional
Model timestep. Defaults to 45 minutes.
 runscriptfunction , optional
A Python function that accepts a Model object as its first argument. This is the routine that will be run when you issue the Model.run() command. Any keyword arguments passed to run() will be forwarded to the specified function. If not set, the default internal routine will be used.
 snapshotsint, optional
How many timesteps should elapse between snapshot outputs. If not set, no snapshots will be written.
 restartfilestring, optional
Path to a restart file to use.
 highcadencedict, optional
A dictionary containing the following arguments:
'toggle'
{0,1}Whether or not highcadence output should be written (1=yes).
'start'
intTimestep at which highcadence output should begin.
'end'
intTimestep at which highcadence output should end.
'interval'
intHow many timesteps should elapse between highcadence outputs.
 thresholdfloat, optional
Energy balance threshold model should run to, if using
runtobalance()
. Default is <0.05 W/m\(^2\)/yr average drift in TOA and surface energy balance over 45year timescales. resourceslist, optional
A list of paths to any additional files that should be available in the run directory.
 runstepsinteger, optional
The number of timesteps to run each ‘year’. By default, this is tuned to 360 Earth days. If set, this will override other controls setting the length of each modelled year.
 otherargsdict, optional
Any namelist parameters not included by default in the configuration options. These should be passed as a dictionary, with “PARAMETER@namelist” as the form of the dictionary key, and the parameter value passed as a string. e.g.
otherargs={"N_RUN_MONTHS@plasim_namelist":'4',"NGUI@plasim_namelist:'1'}
Model Dynamics
 columnmode{None,”“,”clear”,”static”,”staticclear”,”clearstatic”}, optional
The inclusion of ‘static’ will disable horizontal advection, forcing ExoPlaSim into a columnonly mode of operation. The inclusion of ‘clear’ will disable the radiative effects of clouds.
 drycorebool, optional
True/False. If True, evaporation is turned off, and a dry atmosphere will be used.
 physicsfilterstr, optional
If not an empty string, specifies the physics filter(s) to be used. Filters can be used during the transform from gridpoint to spectral (
"gp"
), and/or during the transform from spectral to gridpoint ("sp"
). Filter types are “none”, “cesaro”, “exp”, or “lh” (see the Notes for more details). Combinations of filter types and times should be combined with a
, e.g.physicsfilter="gpexpsp"
orphysicsfilter="gpcesaro"
. filterkappafloat, optional
A constant to be used with the exponential filter. Default is 8.0.
 filterpowerint, optional
A constant integer to be used with the exponential filter. Default is 8.
 filterLHN0float, optional
The constant used in the denominator of the LanderHoskins Filter. Default is 15; typically chosen so f(N)=0.1.
 diffusionwavenint, optional
The critical wavenumber beyond which hyperdiffusion is applied. Default is 15 for T21.
 qdiffusionfloat, optional
Timescale for humidity hyperdiffusion in days. Default for T21 is 0.1.
 tdiffusionfloat, optional
Timescale for temperature hyperdiffusion in days. Default for T21 is 5.6.
 zdiffusionfloat, optional
Timescale for vorticity hyperdiffusion in days. Default for T21 is 1.1.
 ddiffusionfloat, optional
Timescale for divergence hyperdiffusion in days.. Default for T21 is 0.2.
 diffusionpowerint, optional
integer exponent used in hyperdiffusion. Default is 2 for T21.
Radiation
 fluxfloat, optional
Incident stellar flux in W/m\(^2\). Default 1367 for Earth.
 startempfloat, optional
Effective blackbody temperature for the star. Not used if not set.
 starradiusfloat, optional
Radius of the parent star in solar radii. Currently only used for the optional petitRADTRANS direct imaging postprocessor.
 starspecstr, optional
Spectral file for the stellar spectrum. Should have two columns and 965 rows, with wavelength in the first column and radiance or intensity in the second. A similarlynamed file with the “_hr.dat” suffix must also exist and have 2048 wavelengths. Appropriatelyformatted files can be created with
makestellarspec.py
. twobandalbedobool, optional
True/False. If True, separate albedos will be calculated for each of the two shortwave bands. If False (default), a single broadband albedo will be computed and used for both.
 synchronousbool, optional
True/False. If True, the Sun is fixed to one longitude in the sky.
 desyncfloat, optional
The rate of drift of the substellar point in degrees per minute. May be positive or negative.
 substellarlonfloat, optional
The longitude of the substellar point, if synchronous==True. Default 180°
 pressurebroadenbool, optional
True/False. If False, pressurebroadening of absorbers no longer depends on surface pressure. Default is True
 ozonebool or dict, optional
True/False/dict. Whether or not forcing from stratospheric ozone should be included. If a dict is provided, it should contain the keys “height”, “spread”, “amount”,”varlat”,”varseason”, and “seasonoffset”, which correspond to the height in meters of peak O3 concentration, the width of the gaussian distribution in meters, the baseline column amount of ozone in cmSTP, the latitudinal amplitude, the magnitude of seasonal variation, and the time offset of the seasonal variation in fraction of a year. The three amounts are additive. To set a uniform, unvarying O3 distribution, ,place all the ozone in “amount”, and set “varlat” and “varseason” to 0.
 snowicealbedofloat, optional
A uniform albedo to use for all snow and ice.
 soilalbedofloat, optional
A uniform albedo to use for all land.
 wetsoilbool, optional
True/False. If True, land albedo depends on soil moisture (wet=darker).
 oceanalbedofloat, optional
A uniform albedo to use for the ocean.
 oceanzenith{“ECHAM3”,”ECHAM6”,”Lambertian}, optional
The zenithangle dependence to use for bluelight reflectance from the ocean. Can be
'Lambertian'
/'uniform'
,'ECHAM3'
/'plasim'
/'default'
, or'ECHAM6'
. The default is'ECHAM3'
(synonymous with'plasim'
and'default'
), which is the dependence used in the ECHAM3 model.
Orbital Parameters
 yearfloat, optional
Number of 24hour days in a sidereal year. Not necessary if eccentricity and obliquity are zero. Defaults if not set to ~365.25 days
 rotationperiodfloat, optional
Planetary rotation period, in days. Default is 1.0.
 eccentricityfloat, optional
Orbital eccentricity. If not set, defaults to Earth’s (0.016715)
 obliquityfloat, optional
Axial tilt, in degrees. If not set, defaults to Earth’s obliquity (23.441°).
 lonvernaleqfloat, optional
Longitude of periapse, measured from vernal equinox, in degrees. If not set, defaults to Earth’s (102.7°).
 fixedorbitbool, optional
True/False. If True, orbital parameters do not vary over time. If False, variations such as Milankovich cycles will be computed by PlaSim.
 keplerianbool, optional
True/False. If True, a generic Keplerian orbital calculation will be performed. This means no orbital precession, Milankovich cycles, etc, but does allow for accurate calculation of a wide diversity of orbits, including with higher eccentricity. Note that extreme orbits may have extreme results, including extreme crashes.
 meananomaly0float, optional
The initial mean anomaly in degrees. Only used if keplerian=True.
Planet Parameters
 gravityfloat, optional
Surface gravity, in m/s\(^2\). Defaults to 9.80665 m/s\(^2\).
 radiusfloat, optional
Planet radius in Earth radii. Default is 1.0.
 orographyfloat, optional
If set, a scaling factor for topographic relief. If
orography=0.0
, topography will be zeroedout. aquaplanetbool, optional
True/False. If True, the surface will be entirely oceancovered.
 desertplanetbool, optional
True/False. If True, the surface will be entirely landcovered.
 tlcontrastfloat, optional
The initial surface temperature contrast between fixedlon and the anterior point. Default is 0.0 K.
 seaicebool, optional
True/False. If False, disables radiative effects of sea ice (although sea ice itself is still computed).
 landmapstr, optional
Path to a
.sra
file containing a land mask for the chosen resolution. topomapstr, optional
Path to a
.sra
file containing geopotential height map. Must include landmap.
Atmosphere
 gasconfloat, optional
Effective gas constant. Defaults to 287.0 (Earth), or the gas constant corresponding to the composition specified by partial pressures.
 vtype{0,1,2,3,4,5}, optional
Type of vertical discretization. Can be: 0 Pseudolinear scaling with pressure that maintains resolution near the ground. 1 Linear scaling with pressure. 2 Logarithmic scaling with pressure (resolves high altitudes) 3 Pseudologarithmic scaling with pressure that preserves resolution near the ground. 4 Pseudolinear scaling with pressure, pinned to a specified top pressure. 5 If >10 layers, bottom 10 as if
vtype=4
, and upper layers as ifvtype=2
. modeltopfloat, optional
Pressure of the top layer
 tropopausefloat, optional
If stratosphere is being included, pressure of the 10th layer (where scheme switches from linear to logarithmic).
 stratospherebool, optional
True/False. If True, vtype=5 is used, and model is discretized to include a stratosphere.
 pressure: float, optional
Surface pressure in bars, if not specified through partial pressures.
Gas Partial Pressures
Partial pressures of individual gases can be specified. If pressure and gascon are not explicitly set, these will determine surface pressure, mean molecular weight, and effective gas constant. Note however that Rayleigh scattering assumes an Earthlike composition, and the only absorbers explicitly included in the radiation scheme are CO2 and H2O.
 pH2float, optional
H2 partial pressure in bars.
 pHefloat, optional
He partial pressure in bars.
 pN2float, optional
N2 partial pressure in bars.
 pO2float, optional
O2 partial pressure in bars.
 pH2float, optional
H2 partial pressure in bars.
 pArfloat, optional
Ar partial pressure in bars.
 pNefloat, optional
Ne partial pressure in bars.
 pKrfloat, optional
Kr partial pressure in bars.
 pCO2float, optional
CO2 partial pressure in bars. This gets translated into a ppmv concentration, so if you want to specify/vary CO2 but don’t need the other gases, specifying pCO2, pressure, and gascon will do the trick. In most use cases, however, just specifying pN2 and pCO2 will give good enough behavior.
 pH2Ofloat, optional
H2O partial pressure in bars. This is only useful in setting the gas constant and surface pressure; it will have no effect on actual moist processes.
Surface Parameters
 mldepthfloat, optional
Depth of the mixedlayer ocean. Default is 50 meters.
 soildepthfloat, optional
Scaling factor for the depth of soil layers (default total of 12.4 meters)
 cpsoilfloat, optional
Heat capacity of the soil, in J/m^3/K. Default is 2.4*10^6.
 soilwatercapfloat, optional
Water capacity of the soil, in meters. Defaults to 0.5 meters
 soilsaturationfloat, optional
Initial fractional saturation of the soil. Default is 0.0 (dry).
 maxsnowfloat, optional
Maximum snow depth (Default is 5 meters; set to 1 to have no limit).
Additional Physics
 CarbonSilicate Weathering
 co2weatheringbool, optional
True/False. Toggles whether or not carbonsilicate weathering should be computed. Default is False.
 evolveco2bool, optional
True/False. If co2weathering==True, toggles whether or not the CO2 partial pressure should be updated every year. Usually the change in pCO2 will be extremely small, so this is not necessary, and weathering experiments try to estimate the average weathering rate for a given climate in order to interpolate timescales between climates, rather than modelling changes in CO2 over time directly.
 outgassingfloat, optional
The assumed CO2 outgassing rate in units of Earth outgassing. Default is 1.0.
 erosionsupplylimitfloat, optional
If set, the maximum CO2 weathering rate per year permitted by erosion, in ubars/year. This is not simply a hard cutoff, but follows Foley 2015 so high weathering below the cutoff is also reduced.
 Vegetation
 vegetationbool or int, optional
Can be True/False, or 0/1/2. If True or 1, then diagnostic vegetation is turned on. If 2, then coupled vegetation is turned on. Vegetation is computed via the SimBA module.
 vegaccelint, optional
Integer factor by which to accelerate vegetation growth
 nforestgrowth: float, optional
Biomass growth
 initgrowthfloat, optional
Initial aboveground growth
 initstomcondfloat, optional
Initial stomatal conductance
 initroughfloat, optional
Initial vegetative surface roughness
 initsoilcarbonfloat, optional
Initial soil carbon content
 initplantcarbonfloat, optional
Initial vegetative carbon content
See [1]_ for details on the implementation of supplylimited weathering.
 Glaciology
 glaciersdict, optional
A dictionary containing the following arguments: toggle : bool
True/False. Whether or not glaciers should be allowed to grow or shrink in thickness, or be formed from persistent snow on land.
 mindepthfloat
The minimum snow depth in meters of liquid water equivalent that must persist yearround before the grid cell is considered glaciated. Default is 2 meters.
 initialhfloat
If >=0, covers the land surface with ice sheets of a height given in meterss. If 1, no initial ice sheets are assumed.
 Storm Climatology
 stormclimbool, optional
True/False. Toggles whether or not storm climatology (convective available potential energy, maximum potential intensity, ventilation index, etc) should be computed. If True, output fields related to storm climatology will be added to standard output files. Enabling this mode currently roughly doubles the computational cost of the model. This may improve in future updates. Refer to Paradise, et al 2021 for implementation description.
 stormcapturedict, optional
A dictionary containing arguments controlling when highcadence output is triggered by storm activity. This dictionary must contain ‘toggle’, which can be either 1 or 0 (yes or no). It may also contain any namelist parameters accepted by hurricanemod.f90, including the following:
 toggle{0,1}
Whether (1) or not (0) to write highcadence output when storms occur
 NKTRIGGER{0,1}, optional
(0/1=no/yes). Whether or not to use the Komacek, et al 2020 conditions for hurricane cyclogenesis as the output trigger. Default is no.
 VITHRESHfloat, optional
(nktrigger) Ventilation index threshold for nktrigger output. Default 0.145
 VMXTHRESHfloat, optional
(nktrigger) Max potential intensity threshold for nktrigger output.Default 33 m/s
 LAVTHRESHfloat, optional
(nktrigger) Loweratmosphere vorticity threshold for nktrigger output. Default 1.2*10^5 s^1
 VRMTHRESHfloat, optional
(unused) Ventilationreduced maximum intensity threshold. Default 0.577
 GPITHRESHfloat, optional
(default) Genesis Potential Index threshold. Default 0.37.
 MINSURFTEMPfloat, optional
(default) Min. surface temperature for storm activity. Default 25C
 MAXSURFTEMPfloat, optional
(default) Max. surface temperature for storm activity. Default 100C
 WINDTHRESHfloat, optional
(default) Loweratmosphere maximum wind threshold for storm activity. Default 33 m/s
 SWINDTHRESHfloat, optional
(default) Minimum surface windspeed for storm activity. Default 20.5 m/s
 SIZETHRESHfloat, optional
(default) Minimum number of cells that must trigger to start outputDefault 30
 ENDTHRESHfloat, optional
(default) Minimum number of cells at which point storm output ends.Default 16
 MINSTORMLENfloat, optional
(default) Minimum number of timesteps to write output. Default 256
 MAXSTORMLENfloat, optional
(default) Maximum number of timesteps to write output. Default 1024
Note that actual number of writes will be stormlen/interval, as set in highcadence. This interval defaults to 4, so 64 writes minimum, 256 max. For more details on the storm climatology factors considered here, see [5]_.
Notes
In some cases, it may be necessary to include physics filters. This typically becomes necessary when sharp features are projected on the model’s smallest spectral modes, causing Gibbs “ripples”. Earthlike models typically do not require filtering, but tidallylocked models do. Filtering may be beneficial for Earthlike models at very high resolutions as well, or if there is sharp topography.
Three filter functional forms are included in ExoPlaSim: Cesaro, exponential, and LanderHoskins. Their functional forms are given below, where n is the wavenumber, and N is the truncation wavenumber (e.g. 21 for T21):
Cesaro: \(f(n)=1\frac{n}{N+1}\) [2]_
Exponential: \(f(n)=\exp\left[\kappa\left(\frac{n}{N}\right)^\gamma\right]\) [3]_
LanderHoskins: \(f(n)=\exp\left[\left(\frac{n(n+1)}{n_0(n_0+1}\right)^2\right]\) [3]_ [4]_
\(\kappa\) is exposed to the user through
filterkappa
, \(\gamma\) is exposed throughfilterpower
, and \(n_0\) is exposed throughfilterLHN0
.Physics filters can be applied at two different points; either at the transform from gridpoint to spectral, or the reverse. We find that in most cases, the ideal usage is to use both. Generally, a filter at the gridpoint>spectral transform is good for dealing with oscillations caused by sharp jumps and small features in the gridpoint tendencies. Conversely, a filter at the spectral>gridpoint transform is good for dealing with oscillations that come from smallscale features in the spectral fields causing smallscale features to appear in the gridpoint tendencies [3]_. Since we deal with climate systems where everything is coupled, any oscillations not removed by one filter will be amplified through physical feedbacks if not suppressed by the other filter.
References


class
exoplasim.
TLlandplanet
(resolution='T21', layers=10, ncpus=4, precision=8, debug=False, inityear=0, recompile=False, optimization=None, mars=False, workdir='most', source=None, force991=False, modelname='MOST_EXP', outputtype='.npz', crashtolerant=False)[source]¶ Bases:
exoplasim.Model
Create a tidallylocked model with no oceans.
Identical to
Model
, except configuration options suitable for tidallylocked models are the default when configure() is called, and the surface is entirely landcovered. Specifically, a 30minute timestep, snapshot outputs every 720 timesteps, eccentricity=0.0, 0degree obliquity, exponential physics filtering, fixed orbital parameters, and no ozone. All these defaults can be overridden.Notes
The default is to include zero soil water initially. This will result in a completely dry model. Set soilsaturation to something nonzero if you want groundwater.

configure
(timestep=30.0, snapshots=720, eccentricity=0.0, ozone=False, obliquity=0.0, physicsfilter='gpexpsp', tlcontrast=100.0, **kwargs)[source]¶ Configure the model’s namelists and boundary conditions.
The defaults here are appropriate for an Earth model.
Model Operation
 noutputbool, optional
True/False. Whether or not model output should be written.
 restartfilestr, optional
Path to a restart file to use for initial conditions. Can be None.
 writefrequencyint, optional
How many times per day ExoPlaSim should write output. Ignored by default–default is to write timeaveraged output once every 5 days.
 timestepfloat, optional
Model timestep. Defaults to 45 minutes.
 runscriptfunction , optional
A Python function that accepts a Model object as its first argument. This is the routine that will be run when you issue the Model.run() command. Any keyword arguments passed to run() will be forwarded to the specified function. If not set, the default internal routine will be used.
 snapshotsint, optional
How many timesteps should elapse between snapshot outputs. If not set, no snapshots will be written.
 restartfilestring, optional
Path to a restart file to use.
 highcadencedict, optional
A dictionary containing the following arguments:
'toggle'
{0,1}Whether or not highcadence output should be written (1=yes).
'start'
intTimestep at which highcadence output should begin.
'end'
intTimestep at which highcadence output should end.
'interval'
intHow many timesteps should elapse between highcadence outputs.
 thresholdfloat, optional
Energy balance threshold model should run to, if using
runtobalance()
. Default is <0.05 W/m\(^2\)/yr average drift in TOA and surface energy balance over 45year timescales. resourceslist, optional
A list of paths to any additional files that should be available in the run directory.
 runstepsinteger, optional
The number of timesteps to run each ‘year’. By default, this is tuned to 360 Earth days. If set, this will override other controls setting the length of each modelled year.
 otherargsdict, optional
Any namelist parameters not included by default in the configuration options. These should be passed as a dictionary, with “PARAMETER@namelist” as the form of the dictionary key, and the parameter value passed as a string. e.g.
otherargs={"N_RUN_MONTHS@plasim_namelist":'4',"NGUI@plasim_namelist:'1'}
Model Dynamics
 columnmode{None,”“,”clear”,”static”,”staticclear”,”clearstatic”}, optional
The inclusion of ‘static’ will disable horizontal advection, forcing ExoPlaSim into a columnonly mode of operation. The inclusion of ‘clear’ will disable the radiative effects of clouds.
 drycorebool, optional
True/False. If True, evaporation is turned off, and a dry atmosphere will be used.
 physicsfilterstr, optional
If not an empty string, specifies the physics filter(s) to be used. Filters can be used during the transform from gridpoint to spectral (
"gp"
), and/or during the transform from spectral to gridpoint ("sp"
). Filter types are “none”, “cesaro”, “exp”, or “lh” (see the Notes for more details). Combinations of filter types and times should be combined with a
, e.g.physicsfilter="gpexpsp"
orphysicsfilter="gpcesaro"
. filterkappafloat, optional
A constant to be used with the exponential filter. Default is 8.0.
 filterpowerint, optional
A constant integer to be used with the exponential filter. Default is 8.
 filterLHN0float, optional
The constant used in the denominator of the LanderHoskins Filter. Default is 15; typically chosen so f(N)=0.1.
 diffusionwavenint, optional
The critical wavenumber beyond which hyperdiffusion is applied. Default is 15 for T21.
 qdiffusionfloat, optional
Timescale for humidity hyperdiffusion in days. Default for T21 is 0.1.
 tdiffusionfloat, optional
Timescale for temperature hyperdiffusion in days. Default for T21 is 5.6.
 zdiffusionfloat, optional
Timescale for vorticity hyperdiffusion in days. Default for T21 is 1.1.
 ddiffusionfloat, optional
Timescale for divergence hyperdiffusion in days.. Default for T21 is 0.2.
 diffusionpowerint, optional
integer exponent used in hyperdiffusion. Default is 2 for T21.
Radiation
 fluxfloat, optional
Incident stellar flux in W/m\(^2\). Default 1367 for Earth.
 startempfloat, optional
Effective blackbody temperature for the star. Not used if not set.
 starradiusfloat, optional
Radius of the parent star in solar radii. Currently only used for the optional petitRADTRANS direct imaging postprocessor.
 starspecstr, optional
Spectral file for the stellar spectrum. Should have two columns and 965 rows, with wavelength in the first column and radiance or intensity in the second. A similarlynamed file with the “_hr.dat” suffix must also exist and have 2048 wavelengths. Appropriatelyformatted files can be created with
makestellarspec.py
. twobandalbedobool, optional
True/False. If True, separate albedos will be calculated for each of the two shortwave bands. If False (default), a single broadband albedo will be computed and used for both.
 synchronousbool, optional
True/False. If True, the Sun is fixed to one longitude in the sky.
 desyncfloat, optional
The rate of drift of the substellar point in degrees per minute. May be positive or negative.
 substellarlonfloat, optional
The longitude of the substellar point, if synchronous==True. Default 180°
 pressurebroadenbool, optional
True/False. If False, pressurebroadening of absorbers no longer depends on surface pressure. Default is True
 ozonebool or dict, optional
True/False/dict. Whether or not forcing from stratospheric ozone should be included. If a dict is provided, it should contain the keys “height”, “spread”, “amount”,”varlat”,”varseason”, and “seasonoffset”, which correspond to the height in meters of peak O3 concentration, the width of the gaussian distribution in meters, the baseline column amount of ozone in cmSTP, the latitudinal amplitude, the magnitude of seasonal variation, and the time offset of the seasonal variation in fraction of a year. The three amounts are additive. To set a uniform, unvarying O3 distribution, ,place all the ozone in “amount”, and set “varlat” and “varseason” to 0.
 snowicealbedofloat, optional
A uniform albedo to use for all snow and ice.
 soilalbedofloat, optional
A uniform albedo to use for all land.
 wetsoilbool, optional
True/False. If True, land albedo depends on soil moisture (wet=darker).
 oceanalbedofloat, optional
A uniform albedo to use for the ocean.
 oceanzenith{“ECHAM3”,”ECHAM6”,”Lambertian}, optional
The zenithangle dependence to use for bluelight reflectance from the ocean. Can be
'Lambertian'
/'uniform'
,'ECHAM3'
/'plasim'
/'default'
, or'ECHAM6'
. The default is'ECHAM3'
(synonymous with'plasim'
and'default'
), which is the dependence used in the ECHAM3 model.
Orbital Parameters
 yearfloat, optional
Number of 24hour days in a sidereal year. Not necessary if eccentricity and obliquity are zero. Defaults if not set to ~365.25 days
 rotationperiodfloat, optional
Planetary rotation period, in days. Default is 1.0.
 eccentricityfloat, optional
Orbital eccentricity. If not set, defaults to Earth’s (0.016715)
 obliquityfloat, optional
Axial tilt, in degrees. If not set, defaults to Earth’s obliquity (23.441°).
 lonvernaleqfloat, optional
Longitude of periapse, measured from vernal equinox, in degrees. If not set, defaults to Earth’s (102.7°).
 fixedorbitbool, optional
True/False. If True, orbital parameters do not vary over time. If False, variations such as Milankovich cycles will be computed by PlaSim.
 keplerianbool, optional
True/False. If True, a generic Keplerian orbital calculation will be performed. This means no orbital precession, Milankovich cycles, etc, but does allow for accurate calculation of a wide diversity of orbits, including with higher eccentricity. Note that extreme orbits may have extreme results, including extreme crashes.
 meananomaly0float, optional
The initial mean anomaly in degrees. Only used if keplerian=True.
Planet Parameters
 gravityfloat, optional
Surface gravity, in m/s\(^2\). Defaults to 9.80665 m/s\(^2\).
 radiusfloat, optional
Planet radius in Earth radii. Default is 1.0.
 orographyfloat, optional
If set, a scaling factor for topographic relief. If
orography=0.0
, topography will be zeroedout. aquaplanetbool, optional
True/False. If True, the surface will be entirely oceancovered.
 desertplanetbool, optional
True/False. If True, the surface will be entirely landcovered.
 tlcontrastfloat, optional
The initial surface temperature contrast between fixedlon and the anterior point. Default is 0.0 K.
 seaicebool, optional
True/False. If False, disables radiative effects of sea ice (although sea ice itself is still computed).
 landmapstr, optional
Path to a
.sra
file containing a land mask for the chosen resolution. topomapstr, optional
Path to a
.sra
file containing geopotential height map. Must include landmap.
Atmosphere
 gasconfloat, optional
Effective gas constant. Defaults to 287.0 (Earth), or the gas constant corresponding to the composition specified by partial pressures.
 vtype{0,1,2,3,4,5}, optional
Type of vertical discretization. Can be: 0 Pseudolinear scaling with pressure that maintains resolution near the ground. 1 Linear scaling with pressure. 2 Logarithmic scaling with pressure (resolves high altitudes) 3 Pseudologarithmic scaling with pressure that preserves resolution near the ground. 4 Pseudolinear scaling with pressure, pinned to a specified top pressure. 5 If >10 layers, bottom 10 as if
vtype=4
, and upper layers as ifvtype=2
. modeltopfloat, optional
Pressure of the top layer
 tropopausefloat, optional
If stratosphere is being included, pressure of the 10th layer (where scheme switches from linear to logarithmic).
 stratospherebool, optional
True/False. If True, vtype=5 is used, and model is discretized to include a stratosphere.
 pressure: float, optional
Surface pressure in bars, if not specified through partial pressures.
Gas Partial Pressures
Partial pressures of individual gases can be specified. If pressure and gascon are not explicitly set, these will determine surface pressure, mean molecular weight, and effective gas constant. Note however that Rayleigh scattering assumes an Earthlike composition, and the only absorbers explicitly included in the radiation scheme are CO2 and H2O.
 pH2float, optional
H2 partial pressure in bars.
 pHefloat, optional
He partial pressure in bars.
 pN2float, optional
N2 partial pressure in bars.
 pO2float, optional
O2 partial pressure in bars.
 pH2float, optional
H2 partial pressure in bars.
 pArfloat, optional
Ar partial pressure in bars.
 pNefloat, optional
Ne partial pressure in bars.
 pKrfloat, optional
Kr partial pressure in bars.
 pCO2float, optional
CO2 partial pressure in bars. This gets translated into a ppmv concentration, so if you want to specify/vary CO2 but don’t need the other gases, specifying pCO2, pressure, and gascon will do the trick. In most use cases, however, just specifying pN2 and pCO2 will give good enough behavior.
 pH2Ofloat, optional
H2O partial pressure in bars. This is only useful in setting the gas constant and surface pressure; it will have no effect on actual moist processes.
Surface Parameters
 mldepthfloat, optional
Depth of the mixedlayer ocean. Default is 50 meters.
 soildepthfloat, optional
Scaling factor for the depth of soil layers (default total of 12.4 meters)
 cpsoilfloat, optional
Heat capacity of the soil, in J/m^3/K. Default is 2.4*10^6.
 soilwatercapfloat, optional
Water capacity of the soil, in meters. Defaults to 0.5 meters
 soilsaturationfloat, optional
Initial fractional saturation of the soil. Default is 0.0 (dry).
 maxsnowfloat, optional
Maximum snow depth (Default is 5 meters; set to 1 to have no limit).
Additional Physics
 CarbonSilicate Weathering
 co2weatheringbool, optional
True/False. Toggles whether or not carbonsilicate weathering should be computed. Default is False.
 evolveco2bool, optional
True/False. If co2weathering==True, toggles whether or not the CO2 partial pressure should be updated every year. Usually the change in pCO2 will be extremely small, so this is not necessary, and weathering experiments try to estimate the average weathering rate for a given climate in order to interpolate timescales between climates, rather than modelling changes in CO2 over time directly.
 outgassingfloat, optional
The assumed CO2 outgassing rate in units of Earth outgassing. Default is 1.0.
 erosionsupplylimitfloat, optional
If set, the maximum CO2 weathering rate per year permitted by erosion, in ubars/year. This is not simply a hard cutoff, but follows Foley 2015 so high weathering below the cutoff is also reduced.
 Vegetation
 vegetationbool or int, optional
Can be True/False, or 0/1/2. If True or 1, then diagnostic vegetation is turned on. If 2, then coupled vegetation is turned on. Vegetation is computed via the SimBA module.
 vegaccelint, optional
Integer factor by which to accelerate vegetation growth
 nforestgrowth: float, optional
Biomass growth
 initgrowthfloat, optional
Initial aboveground growth
 initstomcondfloat, optional
Initial stomatal conductance
 initroughfloat, optional
Initial vegetative surface roughness
 initsoilcarbonfloat, optional
Initial soil carbon content
 initplantcarbonfloat, optional
Initial vegetative carbon content
See [1]_ for details on the implementation of supplylimited weathering.
 Glaciology
 glaciersdict, optional
A dictionary containing the following arguments: toggle : bool
True/False. Whether or not glaciers should be allowed to grow or shrink in thickness, or be formed from persistent snow on land.
 mindepthfloat
The minimum snow depth in meters of liquid water equivalent that must persist yearround before the grid cell is considered glaciated. Default is 2 meters.
 initialhfloat
If >=0, covers the land surface with ice sheets of a height given in meterss. If 1, no initial ice sheets are assumed.
 Storm Climatology
 stormclimbool, optional
True/False. Toggles whether or not storm climatology (convective available potential energy, maximum potential intensity, ventilation index, etc) should be computed. If True, output fields related to storm climatology will be added to standard output files. Enabling this mode currently roughly doubles the computational cost of the model. This may improve in future updates. Refer to Paradise, et al 2021 for implementation description.
 stormcapturedict, optional
A dictionary containing arguments controlling when highcadence output is triggered by storm activity. This dictionary must contain ‘toggle’, which can be either 1 or 0 (yes or no). It may also contain any namelist parameters accepted by hurricanemod.f90, including the following:
 toggle{0,1}
Whether (1) or not (0) to write highcadence output when storms occur
 NKTRIGGER{0,1}, optional
(0/1=no/yes). Whether or not to use the Komacek, et al 2020 conditions for hurricane cyclogenesis as the output trigger. Default is no.
 VITHRESHfloat, optional
(nktrigger) Ventilation index threshold for nktrigger output. Default 0.145
 VMXTHRESHfloat, optional
(nktrigger) Max potential intensity threshold for nktrigger output.Default 33 m/s
 LAVTHRESHfloat, optional
(nktrigger) Loweratmosphere vorticity threshold for nktrigger output. Default 1.2*10^5 s^1
 VRMTHRESHfloat, optional
(unused) Ventilationreduced maximum intensity threshold. Default 0.577
 GPITHRESHfloat, optional
(default) Genesis Potential Index threshold. Default 0.37.
 MINSURFTEMPfloat, optional
(default) Min. surface temperature for storm activity. Default 25C
 MAXSURFTEMPfloat, optional
(default) Max. surface temperature for storm activity. Default 100C
 WINDTHRESHfloat, optional
(default) Loweratmosphere maximum wind threshold for storm activity. Default 33 m/s
 SWINDTHRESHfloat, optional
(default) Minimum surface windspeed for storm activity. Default 20.5 m/s
 SIZETHRESHfloat, optional
(default) Minimum number of cells that must trigger to start outputDefault 30
 ENDTHRESHfloat, optional
(default) Minimum number of cells at which point storm output ends.Default 16
 MINSTORMLENfloat, optional
(default) Minimum number of timesteps to write output. Default 256
 MAXSTORMLENfloat, optional
(default) Maximum number of timesteps to write output. Default 1024
Note that actual number of writes will be stormlen/interval, as set in highcadence. This interval defaults to 4, so 64 writes minimum, 256 max. For more details on the storm climatology factors considered here, see [5]_.
Notes
In some cases, it may be necessary to include physics filters. This typically becomes necessary when sharp features are projected on the model’s smallest spectral modes, causing Gibbs “ripples”. Earthlike models typically do not require filtering, but tidallylocked models do. Filtering may be beneficial for Earthlike models at very high resolutions as well, or if there is sharp topography.
Three filter functional forms are included in ExoPlaSim: Cesaro, exponential, and LanderHoskins. Their functional forms are given below, where n is the wavenumber, and N is the truncation wavenumber (e.g. 21 for T21):
Cesaro: \(f(n)=1\frac{n}{N+1}\) [2]_
Exponential: \(f(n)=\exp\left[\kappa\left(\frac{n}{N}\right)^\gamma\right]\) [3]_
LanderHoskins: \(f(n)=\exp\left[\left(\frac{n(n+1)}{n_0(n_0+1}\right)^2\right]\) [3]_ [4]_
\(\kappa\) is exposed to the user through
filterkappa
, \(\gamma\) is exposed throughfilterpower
, and \(n_0\) is exposed throughfilterLHN0
.Physics filters can be applied at two different points; either at the transform from gridpoint to spectral, or the reverse. We find that in most cases, the ideal usage is to use both. Generally, a filter at the gridpoint>spectral transform is good for dealing with oscillations caused by sharp jumps and small features in the gridpoint tendencies. Conversely, a filter at the spectral>gridpoint transform is good for dealing with oscillations that come from smallscale features in the spectral fields causing smallscale features to appear in the gridpoint tendencies [3]_. Since we deal with climate systems where everything is coupled, any oscillations not removed by one filter will be amplified through physical feedbacks if not suppressed by the other filter.
References


class
exoplasim.
TLmodel
(resolution='T21', layers=10, ncpus=4, precision=8, debug=False, inityear=0, recompile=False, optimization=None, mars=False, workdir='most', source=None, force991=False, modelname='MOST_EXP', outputtype='.npz', crashtolerant=False)[source]¶ Bases:
exoplasim.Model
Create a tidallylocked model.
Identical to
Model
, except configuration options suitable for tidallylocked models are the default when configure() is called.
configure
(timestep=30.0, snapshots=720, eccentricity=0.0, ozone=False, obliquity=0.0, physicsfilter='gpexpsp', tlcontrast=100.0, **kwargs)[source]¶ Configure the model’s namelists and boundary conditions.
The defaults here are appropriate for an Earth model.
Model Operation
 noutputbool, optional
True/False. Whether or not model output should be written.
 restartfilestr, optional
Path to a restart file to use for initial conditions. Can be None.
 writefrequencyint, optional
How many times per day ExoPlaSim should write output. Ignored by default–default is to write timeaveraged output once every 5 days.
 timestepfloat, optional
Model timestep. Defaults to 45 minutes.
 runscriptfunction , optional
A Python function that accepts a Model object as its first argument. This is the routine that will be run when you issue the Model.run() command. Any keyword arguments passed to run() will be forwarded to the specified function. If not set, the default internal routine will be used.
 snapshotsint, optional
How many timesteps should elapse between snapshot outputs. If not set, no snapshots will be written.
 restartfilestring, optional
Path to a restart file to use.
 highcadencedict, optional
A dictionary containing the following arguments:
'toggle'
{0,1}Whether or not highcadence output should be written (1=yes).
'start'
intTimestep at which highcadence output should begin.
'end'
intTimestep at which highcadence output should end.
'interval'
intHow many timesteps should elapse between highcadence outputs.
 thresholdfloat, optional
Energy balance threshold model should run to, if using
runtobalance()
. Default is <0.05 W/m\(^2\)/yr average drift in TOA and surface energy balance over 45year timescales. resourceslist, optional
A list of paths to any additional files that should be available in the run directory.
 runstepsinteger, optional
The number of timesteps to run each ‘year’. By default, this is tuned to 360 Earth days. If set, this will override other controls setting the length of each modelled year.
 otherargsdict, optional
Any namelist parameters not included by default in the configuration options. These should be passed as a dictionary, with “PARAMETER@namelist” as the form of the dictionary key, and the parameter value passed as a string. e.g.
otherargs={"N_RUN_MONTHS@plasim_namelist":'4',"NGUI@plasim_namelist:'1'}
Model Dynamics
 columnmode{None,”“,”clear”,”static”,”staticclear”,”clearstatic”}, optional
The inclusion of ‘static’ will disable horizontal advection, forcing ExoPlaSim into a columnonly mode of operation. The inclusion of ‘clear’ will disable the radiative effects of clouds.
 drycorebool, optional
True/False. If True, evaporation is turned off, and a dry atmosphere will be used.
 physicsfilterstr, optional
If not an empty string, specifies the physics filter(s) to be used. Filters can be used during the transform from gridpoint to spectral (
"gp"
), and/or during the transform from spectral to gridpoint ("sp"
). Filter types are “none”, “cesaro”, “exp”, or “lh” (see the Notes for more details). Combinations of filter types and times should be combined with a
, e.g.physicsfilter="gpexpsp"
orphysicsfilter="gpcesaro"
. filterkappafloat, optional
A constant to be used with the exponential filter. Default is 8.0.
 filterpowerint, optional
A constant integer to be used with the exponential filter. Default is 8.
 filterLHN0float, optional
The constant used in the denominator of the LanderHoskins Filter. Default is 15; typically chosen so f(N)=0.1.
 diffusionwavenint, optional
The critical wavenumber beyond which hyperdiffusion is applied. Default is 15 for T21.
 qdiffusionfloat, optional
Timescale for humidity hyperdiffusion in days. Default for T21 is 0.1.
 tdiffusionfloat, optional
Timescale for temperature hyperdiffusion in days. Default for T21 is 5.6.
 zdiffusionfloat, optional
Timescale for vorticity hyperdiffusion in days. Default for T21 is 1.1.
 ddiffusionfloat, optional
Timescale for divergence hyperdiffusion in days.. Default for T21 is 0.2.
 diffusionpowerint, optional
integer exponent used in hyperdiffusion. Default is 2 for T21.
Radiation
 fluxfloat, optional
Incident stellar flux in W/m\(^2\). Default 1367 for Earth.
 startempfloat, optional
Effective blackbody temperature for the star. Not used if not set.
 starradiusfloat, optional
Radius of the parent star in solar radii. Currently only used for the optional petitRADTRANS direct imaging postprocessor.
 starspecstr, optional
Spectral file for the stellar spectrum. Should have two columns and 965 rows, with wavelength in the first column and radiance or intensity in the second. A similarlynamed file with the “_hr.dat” suffix must also exist and have 2048 wavelengths. Appropriatelyformatted files can be created with
makestellarspec.py
. twobandalbedobool, optional
True/False. If True, separate albedos will be calculated for each of the two shortwave bands. If False (default), a single broadband albedo will be computed and used for both.
 synchronousbool, optional
True/False. If True, the Sun is fixed to one longitude in the sky.
 desyncfloat, optional
The rate of drift of the substellar point in degrees per minute. May be positive or negative.
 substellarlonfloat, optional
The longitude of the substellar point, if synchronous==True. Default 180°
 pressurebroadenbool, optional
True/False. If False, pressurebroadening of absorbers no longer depends on surface pressure. Default is True
 ozonebool or dict, optional
True/False/dict. Whether or not forcing from stratospheric ozone should be included. If a dict is provided, it should contain the keys “height”, “spread”, “amount”,”varlat”,”varseason”, and “seasonoffset”, which correspond to the height in meters of peak O3 concentration, the width of the gaussian distribution in meters, the baseline column amount of ozone in cmSTP, the latitudinal amplitude, the magnitude of seasonal variation, and the time offset of the seasonal variation in fraction of a year. The three amounts are additive. To set a uniform, unvarying O3 distribution, ,place all the ozone in “amount”, and set “varlat” and “varseason” to 0.
 snowicealbedofloat, optional
A uniform albedo to use for all snow and ice.
 soilalbedofloat, optional
A uniform albedo to use for all land.
 wetsoilbool, optional
True/False. If True, land albedo depends on soil moisture (wet=darker).
 oceanalbedofloat, optional
A uniform albedo to use for the ocean.
 oceanzenith{“ECHAM3”,”ECHAM6”,”Lambertian}, optional
The zenithangle dependence to use for bluelight reflectance from the ocean. Can be
'Lambertian'
/'uniform'
,'ECHAM3'
/'plasim'
/'default'
, or'ECHAM6'
. The default is'ECHAM3'
(synonymous with'plasim'
and'default'
), which is the dependence used in the ECHAM3 model.
Orbital Parameters
 yearfloat, optional
Number of 24hour days in a sidereal year. Not necessary if eccentricity and obliquity are zero. Defaults if not set to ~365.25 days
 rotationperiodfloat, optional
Planetary rotation period, in days. Default is 1.0.
 eccentricityfloat, optional
Orbital eccentricity. If not set, defaults to Earth’s (0.016715)
 obliquityfloat, optional
Axial tilt, in degrees. If not set, defaults to Earth’s obliquity (23.441°).
 lonvernaleqfloat, optional
Longitude of periapse, measured from vernal equinox, in degrees. If not set, defaults to Earth’s (102.7°).
 fixedorbitbool, optional
True/False. If True, orbital parameters do not vary over time. If False, variations such as Milankovich cycles will be computed by PlaSim.
 keplerianbool, optional
True/False. If True, a generic Keplerian orbital calculation will be performed. This means no orbital precession, Milankovich cycles, etc, but does allow for accurate calculation of a wide diversity of orbits, including with higher eccentricity. Note that extreme orbits may have extreme results, including extreme crashes.
 meananomaly0float, optional
The initial mean anomaly in degrees. Only used if keplerian=True.
Planet Parameters
 gravityfloat, optional
Surface gravity, in m/s\(^2\). Defaults to 9.80665 m/s\(^2\).
 radiusfloat, optional
Planet radius in Earth radii. Default is 1.0.
 orographyfloat, optional
If set, a scaling factor for topographic relief. If
orography=0.0
, topography will be zeroedout. aquaplanetbool, optional
True/False. If True, the surface will be entirely oceancovered.
 desertplanetbool, optional
True/False. If True, the surface will be entirely landcovered.
 tlcontrastfloat, optional
The initial surface temperature contrast between fixedlon and the anterior point. Default is 0.0 K.
 seaicebool, optional
True/False. If False, disables radiative effects of sea ice (although sea ice itself is still computed).
 landmapstr, optional
Path to a
.sra
file containing a land mask for the chosen resolution. topomapstr, optional
Path to a
.sra
file containing geopotential height map. Must include landmap.
Atmosphere
 gasconfloat, optional
Effective gas constant. Defaults to 287.0 (Earth), or the gas constant corresponding to the composition specified by partial pressures.
 vtype{0,1,2,3,4,5}, optional
Type of vertical discretization. Can be: 0 Pseudolinear scaling with pressure that maintains resolution near the ground. 1 Linear scaling with pressure. 2 Logarithmic scaling with pressure (resolves high altitudes) 3 Pseudologarithmic scaling with pressure that preserves resolution near the ground. 4 Pseudolinear scaling with pressure, pinned to a specified top pressure. 5 If >10 layers, bottom 10 as if
vtype=4
, and upper layers as ifvtype=2
. modeltopfloat, optional
Pressure of the top layer
 tropopausefloat, optional
If stratosphere is being included, pressure of the 10th layer (where scheme switches from linear to logarithmic).
 stratospherebool, optional
True/False. If True, vtype=5 is used, and model is discretized to include a stratosphere.
 pressure: float, optional
Surface pressure in bars, if not specified through partial pressures.
Gas Partial Pressures
Partial pressures of individual gases can be specified. If pressure and gascon are not explicitly set, these will determine surface pressure, mean molecular weight, and effective gas constant. Note however that Rayleigh scattering assumes an Earthlike composition, and the only absorbers explicitly included in the radiation scheme are CO2 and H2O.
 pH2float, optional
H2 partial pressure in bars.
 pHefloat, optional
He partial pressure in bars.
 pN2float, optional
N2 partial pressure in bars.
 pO2float, optional
O2 partial pressure in bars.
 pH2float, optional
H2 partial pressure in bars.
 pArfloat, optional
Ar partial pressure in bars.
 pNefloat, optional
Ne partial pressure in bars.
 pKrfloat, optional
Kr partial pressure in bars.
 pCO2float, optional
CO2 partial pressure in bars. This gets translated into a ppmv concentration, so if you want to specify/vary CO2 but don’t need the other gases, specifying pCO2, pressure, and gascon will do the trick. In most use cases, however, just specifying pN2 and pCO2 will give good enough behavior.
 pH2Ofloat, optional
H2O partial pressure in bars. This is only useful in setting the gas constant and surface pressure; it will have no effect on actual moist processes.
Surface Parameters
 mldepthfloat, optional
Depth of the mixedlayer ocean. Default is 50 meters.
 soildepthfloat, optional
Scaling factor for the depth of soil layers (default total of 12.4 meters)
 cpsoilfloat, optional
Heat capacity of the soil, in J/m^3/K. Default is 2.4*10^6.
 soilwatercapfloat, optional
Water capacity of the soil, in meters. Defaults to 0.5 meters
 soilsaturationfloat, optional
Initial fractional saturation of the soil. Default is 0.0 (dry).
 maxsnowfloat, optional
Maximum snow depth (Default is 5 meters; set to 1 to have no limit).
Additional Physics
 CarbonSilicate Weathering
 co2weatheringbool, optional
True/False. Toggles whether or not carbonsilicate weathering should be computed. Default is False.
 evolveco2bool, optional
True/False. If co2weathering==True, toggles whether or not the CO2 partial pressure should be updated every year. Usually the change in pCO2 will be extremely small, so this is not necessary, and weathering experiments try to estimate the average weathering rate for a given climate in order to interpolate timescales between climates, rather than modelling changes in CO2 over time directly.
 outgassingfloat, optional
The assumed CO2 outgassing rate in units of Earth outgassing. Default is 1.0.
 erosionsupplylimitfloat, optional
If set, the maximum CO2 weathering rate per year permitted by erosion, in ubars/year. This is not simply a hard cutoff, but follows Foley 2015 so high weathering below the cutoff is also reduced.
 Vegetation
 vegetationbool or int, optional
Can be True/False, or 0/1/2. If True or 1, then diagnostic vegetation is turned on. If 2, then coupled vegetation is turned on. Vegetation is computed via the SimBA module.
 vegaccelint, optional
Integer factor by which to accelerate vegetation growth
 nforestgrowth: float, optional
Biomass growth
 initgrowthfloat, optional
Initial aboveground growth
 initstomcondfloat, optional
Initial stomatal conductance
 initroughfloat, optional
Initial vegetative surface roughness
 initsoilcarbonfloat, optional
Initial soil carbon content
 initplantcarbonfloat, optional
Initial vegetative carbon content
See [1]_ for details on the implementation of supplylimited weathering.
 Glaciology
 glaciersdict, optional
A dictionary containing the following arguments: toggle : bool
True/False. Whether or not glaciers should be allowed to grow or shrink in thickness, or be formed from persistent snow on land.
 mindepthfloat
The minimum snow depth in meters of liquid water equivalent that must persist yearround before the grid cell is considered glaciated. Default is 2 meters.
 initialhfloat
If >=0, covers the land surface with ice sheets of a height given in meterss. If 1, no initial ice sheets are assumed.
 Storm Climatology
 stormclimbool, optional
True/False. Toggles whether or not storm climatology (convective available potential energy, maximum potential intensity, ventilation index, etc) should be computed. If True, output fields related to storm climatology will be added to standard output files. Enabling this mode currently roughly doubles the computational cost of the model. This may improve in future updates. Refer to Paradise, et al 2021 for implementation description.
 stormcapturedict, optional
A dictionary containing arguments controlling when highcadence output is triggered by storm activity. This dictionary must contain ‘toggle’, which can be either 1 or 0 (yes or no). It may also contain any namelist parameters accepted by hurricanemod.f90, including the following:
 toggle{0,1}
Whether (1) or not (0) to write highcadence output when storms occur
 NKTRIGGER{0,1}, optional
(0/1=no/yes). Whether or not to use the Komacek, et al 2020 conditions for hurricane cyclogenesis as the output trigger. Default is no.
 VITHRESHfloat, optional
(nktrigger) Ventilation index threshold for nktrigger output. Default 0.145
 VMXTHRESHfloat, optional
(nktrigger) Max potential intensity threshold for nktrigger output.Default 33 m/s
 LAVTHRESHfloat, optional
(nktrigger) Loweratmosphere vorticity threshold for nktrigger output. Default 1.2*10^5 s^1
 VRMTHRESHfloat, optional
(unused) Ventilationreduced maximum intensity threshold. Default 0.577
 GPITHRESHfloat, optional
(default) Genesis Potential Index threshold. Default 0.37.
 MINSURFTEMPfloat, optional
(default) Min. surface temperature for storm activity. Default 25C
 MAXSURFTEMPfloat, optional
(default) Max. surface temperature for storm activity. Default 100C
 WINDTHRESHfloat, optional
(default) Loweratmosphere maximum wind threshold for storm activity. Default 33 m/s
 SWINDTHRESHfloat, optional
(default) Minimum surface windspeed for storm activity. Default 20.5 m/s
 SIZETHRESHfloat, optional
(default) Minimum number of cells that must trigger to start outputDefault 30
 ENDTHRESHfloat, optional
(default) Minimum number of cells at which point storm output ends.Default 16
 MINSTORMLENfloat, optional
(default) Minimum number of timesteps to write output. Default 256
 MAXSTORMLENfloat, optional
(default) Maximum number of timesteps to write output. Default 1024
Note that actual number of writes will be stormlen/interval, as set in highcadence. This interval defaults to 4, so 64 writes minimum, 256 max. For more details on the storm climatology factors considered here, see [5]_.
Notes
In some cases, it may be necessary to include physics filters. This typically becomes necessary when sharp features are projected on the model’s smallest spectral modes, causing Gibbs “ripples”. Earthlike models typically do not require filtering, but tidallylocked models do. Filtering may be beneficial for Earthlike models at very high resolutions as well, or if there is sharp topography.
Three filter functional forms are included in ExoPlaSim: Cesaro, exponential, and LanderHoskins. Their functional forms are given below, where n is the wavenumber, and N is the truncation wavenumber (e.g. 21 for T21):
Cesaro: \(f(n)=1\frac{n}{N+1}\) [2]_
Exponential: \(f(n)=\exp\left[\kappa\left(\frac{n}{N}\right)^\gamma\right]\) [3]_
LanderHoskins: \(f(n)=\exp\left[\left(\frac{n(n+1)}{n_0(n_0+1}\right)^2\right]\) [3]_ [4]_
\(\kappa\) is exposed to the user through
filterkappa
, \(\gamma\) is exposed throughfilterpower
, and \(n_0\) is exposed throughfilterLHN0
.Physics filters can be applied at two different points; either at the transform from gridpoint to spectral, or the reverse. We find that in most cases, the ideal usage is to use both. Generally, a filter at the gridpoint>spectral transform is good for dealing with oscillations caused by sharp jumps and small features in the gridpoint tendencies. Conversely, a filter at the spectral>gridpoint transform is good for dealing with oscillations that come from smallscale features in the spectral fields causing smallscale features to appear in the gridpoint tendencies [3]_. Since we deal with climate systems where everything is coupled, any oscillations not removed by one filter will be amplified through physical feedbacks if not suppressed by the other filter.
References

Submodules¶
exoplasim.gcmt module¶

exoplasim.gcmt.
adist
(lon1, lat1, lon2, lat2)[source]¶ Return angular distance(s) in degrees between two points (or sets of points) on a sphere.
 Parameters:
lon1 (float or numpy.ndarray) – Longitudes of first point(s)
lat1 (float or numpy.ndarray) – Latitudes of first point(s)
lon2 (float or numpy.ndarray) – Longitudes of second point(s)
lat2 (float or numpy.ndarray) – Latitudes of second point(s)
 Returns:
Angular distance(s) between given points
 Return type:
float or numpy.ndarray

exoplasim.gcmt.
blackbody
(wavelengths, temperature)[source]¶ Compute the Planck function for a set of wavelengths and a given effective temperature.
 Parameters:
wavelengths (arraylike) – Wavelengths in microns
temperature (float) – Effective temperature in Kelvins
 Returns:
Spectral radiance F_lambda(lambda,T) for the provided wavelengths assuming a perfect blackbody.
 Return type:
arraylike

exoplasim.gcmt.
cspatialmath
(variable, lat=None, lon=None, file=None, mean=True, time=None, ignoreNaNs=True, lev=None, radius=6371000.0, poles=False)[source]¶ Compute spatial means or sums of data, but optionally don’t go all the way to the poles.
Sometimes, saying that the latitudes covered go all the way to \(\pm90^\circ\) results in errors, and accurate accounting requires excluding the poles themselves. This function is identical to spatialmath, except that it provides that option.
 Parameters:
variable (str, numpy.ndarray) – The variable to operate on. Can either be a data array, or the name of a variable. If the latter, file must be specified.
lat (numpy.ndarray, optional) – Latitude and longitude arrays. If file is provided and lat and lon are not, they will be extracted from the file.
lon (numpy.ndarray, optional) – Latitude and longitude arrays. If file is provided and lat and lon are not, they will be extracted from the file.
file (str, optional) – Path to a NetCDF output file to open and extract data from.
mean (bool, optional) – If True, compute a global mean. If False, compute a global sum.
time (int, optional) – The time index on which to slice. If unspecified, a time average will be returned.
ignoreNaNs (bool, optional) – If True, use NaNsafe numpy operators.
lev (int, optional) – If set, slice a 3D spatial array at the specified level.
radius (float, optional) – Radius of the planet in meters. Only used if mean=False.
poles (bool, optional) – If False (default), exclude the poles.
 Returns:
 Return type:
float

exoplasim.gcmt.
eq2tl
(variable, lon, lat, substellar=0.0, polemethod='interp')[source]¶ Transform a variable to tidallylocked coordinates
Note that in our tidallylocked coordinate system, 0 degrees longitude is the substellarsouth poleantistellar meridian, and 90 degrees latitude is the substellar point, such that the evening hemisphere is 0180 degrees longitude, the morning hemisphere is 180360 degrees longitude, the north equatorial pole is at (0, 180), and easterly flow is counterclockwise. Note that this differs from the coordinate system introduced in Koll & Abbot (2015) in that theirs is a lefthanded coordinate system, with the south pole at (0, 180) and counterclockwise easterly flow, which represents a southfacing observer inside the sphere, while ours is a righthanded coordinate system, representing a southfacing observer outside the sphere, which is the usual convention for spherical coordinate systems.
 Parameters:
variable (numpy.ndarray (2D, 3D, or 4D)) – ND data array to be transformed. Final two dimensions must be (lat,lon)
lon (numpy.ndarray) – 1D array of longitudes [deg]
lat (numpy.ndarray) – 1D array of latitudes [deg]
substellar (float, optional) – Longitude of the substellar point (defaults to 0 degrees)
polemethod (str, optional) – Interpolation method for polar latitudes. If “nearest”, then instead of inversedistance linear interpolation, will use nearestneighbor. This is recommended for vector variables. For scalars, leave as “interp”.
 Returns:
Transformed longitudes, latitudes, and data array.
 Return type:
numpy.ndarray, numpy.ndarray, numpy.ndarray

exoplasim.gcmt.
eq2tl_coords
(lon, lat, substellar=0.0)[source]¶ Compute tidallylocked coordinates of a set of equatorial latlon coordinates.
Transforms equatorial coordinates into a tidallylocked coordinate system where 0 degrees longitude is the substellarsouth poleantistellar meridian, and 90 degrees latitude is the substellar point, such that the evening hemisphere is 0180 degrees longitude, the morning hemisphere is 180360 degrees longitude, the north equatorial pole is at (0, 180), and easterly flow is counterclockwise. Note that this differs from the coordinate system introduced in Koll & Abbot (2015) in that theirs is a lefthanded coordinate system, with the south pole at (0, 180) and counterclockwise easterly flow, which represents a southfacing observer inside the sphere, while ours is a righthanded coordinate system, representing a southfacing observer outside the sphere, which is the usual convention for spherical coordinate systems.
 Parameters:
lon (numpy.ndarray) – Longitudes in equatorial coordinates [degrees]
lat (numpy.ndarray) – Latitudes in equatorial coordinates [degrees]
substellar (float, optional) – Longitude of the substellar point. [degrees]
 Returns:
Transformed longitudes and latitudes [degrees]
 Return type:
numpy.ndarray, numpy.ndarray

exoplasim.gcmt.
eq2tl_uv
(u, v, lon, lat, substellar=0.0)[source]¶ Transform velocity variables to tidallylocked coordinates
 Parameters:
u (numpy.ndarray (2D, 3D, or 4D)) – ND data array of zonal velocities to be transformed. Final two dimensions must be (lat,lon)
v (numpy.ndarray (2D, 3D, or 4D)) – ND data array of meridional velocities to be transformed. Final two dimensions must be (lat,lon)
lon (numpy.ndarray) – 1D array of longitudes [deg]
lat (numpy.ndarray) – 1D array of latitudes [deg]
substellar (float, optional) – Longitude of the substellar point (defaults to 0 degrees)
 Returns:
Transformed longitudes, latitudes, and velocity data arrays.
 Return type:
numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray

exoplasim.gcmt.
eqstream
(file, radius=6371000.0, gravity=9.80665)[source]¶ Compute the tidallylocked streamfunction
 Parameters:
dataset (str or ExoPlaSim Dataset) – Either path to ExoPlaSim Dataset of model output or an instance of the dataset.
plarad (float, optional) – Planetary radius [m]
grav (float, optional) – Surface gravity [m/s^2]
 Returns:
tidallylocked latitude, layer interface pressures, and TL streamfunction
 Return type:
numpy.ndarray(1D), numpy.ndarray(1D), numpy.ndarray(2D)

exoplasim.gcmt.
latmean
(variable, latitudes)[source]¶ Compute meriodional mean (i.e. the variable that changes is latitude).
Compute the areaweighted mean of a latitude array \(x\), such that:
\[\bar{x} = \frac{\sum_{i=1}^N \sin(\phi_{i1/2})\sin(\phi_{i+1/2})x_i}{\sum_{i=1}^N \sin(\phi_{i1/2})\sin(\phi_{i+1/2})}\] Parameters:
variable (numpy.ndarray) – Array to be averaged. Assumption is that if 2D, lat is the first dimension, if 3D, the second dimension, and if 4D. the 3rd dimension.
latitudes (arraylike) – Array or list of latitudes
 Returns:
Depending on the dimensionality of the input array, output may have 0, 1, or 2 dimensions.
 Return type:
scalar or numpy.ndarray

exoplasim.gcmt.
latsum
(variable, latitudes, dlon=360.0, radius=6371000.0)[source]¶ Compute meriodional sum (i.e. the variable that changes is latitude).
Compute the areaweighted sum of a latitude array \(x\) given a longitude span \(\Delta\theta\) and planet radius \(R\), such that:
\[X = \sum_{i=1}^N \sin(\phi_{i1/2})\sin(\phi_{i+1/2})\Delta\theta R^2x_i\] Parameters:
variable (numpy.ndarray) – Array to be summed. Assumption is that if 2D, lat is the first dimension, if 3D, the second dimension, and if 4D. the 3rd dimension.
latitudes (arraylike) – Array or list of latitudes
dlon (float, optional) – Longitude span in degrees.
radius (float, optional) – Planet radius in meters.
 Returns:
Depending on the dimensionality of the input array, output may have 0, 1, or 2 dimensions.
 Return type:
scalar or numpy.ndarray

exoplasim.gcmt.
load
(filename, csvbuffersize=1)[source]¶ Open a postprocessed ExoPlaSim output file.
Supported formats include netCDF, CSV/TXT (can be compressed), NumPy, and HDF5. If the data archive is a group of files that are not tarballed, such as a directory of CSV/TXT or gzipped files, then the filename should be the name of the directory with the final file extension.
For example, if the dataset is a group of CSV files in a folder called “MOST_output.002”, then filename ought to be “MOST_output.002.csv”, even though no such file exists.
When accessing a file archive comprised of CSV/TXT files such as that described above, only part of the archive will be extracted/read into memory at once, with the exception of the first read, when the entire archive is extracted to read header information. Dimensional arrays, such as latitude, longitude, etc will be ready into memory and stored as attributes of the returned object (but are accessed with the usual dictionary pattern). Other data arrays however may need to be extracted and read from the archive. A memory buffer exists to hold recentlyaccessed arrays in memory, which will prioritize the most recentlyaccessed variables. The number of variables that can be stored in memory can be set with the csvbuffersize keyword. The default is 1. This means that the first time the variable is accessed, access times will be roughly the time it takes to extract the file and read it into memory. Subsequent accesses, however, will use RAM speeds. Once the variable has left the buffer, due to other variables being accessed, the next access will return to file access speeds. This behavior is intended to mimic the npz, netcdf, and hdf5 protocols.
 Parameters:
filename (str) – Path to the file
csvbuffersize (int, optional) – If the file (or group of files) is a file archive such as a directory, tarball, etc, this is the number of variables to keep in a memory buffer when the archive is accessed.
 Returns:
gmct._Dataset
object that can be queried like a netCDF file. Return type:
object

exoplasim.gcmt.
lonmean
(variable, longitudes)[source]¶ Compute zonal mean (i.e. the variable that changes is longitude).
Compute the areaweighted mean of a longitude array \(x\), such that:
\[\bar{x} = \frac{\sum_{i=1}^N \theta_{i1/2}\theta_{i+1/2}x_i}{\sum_{i=1}^N \theta_{i1/2}\theta_{i+1/2}}\] Parameters:
variable (numpy.ndarray) – Array to be summed. Assumption is that longitude is always the last dimension.
 Returns:
Depending on the dimensionality of the input array, output may be a scalar or have N1 dimensions.
 Return type:
scalar or numpy.ndarray

exoplasim.gcmt.
lonsum
(variable, longitudes, dsinlat=2.0, radius=6371000.0)[source]¶ Compute zonal sum (i.e. the variable that changes is longitude).
Compute the areaweighted sum of a longitude array \(x\) given a latitude span \(\Delta\sin\phi\) and planet radius \(R\), such that:
\[X = \sum_{i=1}^N \theta_{i1/2}\theta_{i+1/2}\Delta\sin\phi R^2x_i\] Parameters:
variable (numpy.ndarray) – Array to be summed. Assumption is that longitude is always the last dimension.
longitudes (arraylike) – Array or list of longitudes
dsinlat (float, optional) – The sinelatitude span for the longitude span considered. The default is 2, corresponding to 90 degrees to 90 degrees.
radius (float, optional) – Planet radius in meters.
 Returns:
Depending on the dimensionality of the input array, output may have 0, 1, or 2 dimensions.
 Return type:
scalar or numpy.ndarray

exoplasim.gcmt.
make2d
(variable, lat=None, lon=None, time=None, lev=None, ignoreNaNs=True, radius=6371000.0, latitudes=None, longitudes=None)[source]¶ Compress a variable in two dimensions by slicing or averaging.
 Parameters:
variable (numpy.ndarray) – The variable to operate on
lat (int, str, optional) – Either an index on which to slice, or either of “sum” or “mean”, indicating what should be done along that axis.
lon (int, str, optional) – Either an index on which to slice, or either of “sum” or “mean”, indicating what should be done along that axis.
lev (int, str, optional) – Either an index on which to slice, or either of “sum” or “mean”, indicating what should be done along that axis.
time (int, optional) – The time index on which to slice. If unspecified, a time average will be returned.
ignoreNaNs (bool, optional) – If set, will use NaNsafe numpy operators.
radius (float, optional) – Planet radius in meters (only used for summation)
latitudes (numpy.ndarray, optional) – Latitude array–required if lat is “mean”, or if either lat or lon is “sum”
longitudes (numpy.ndarray, optional) – Longitude array–required if lon is “mean” or if either lat or lon is “sum”
 Returns:
A 2D array
 Return type:
numpy.ndarray

exoplasim.gcmt.
orthographic
(lon, lat, imap, central_longitude=0, central_latitude=0, ny=200, nx=200, interp='bilinear')[source]¶ Perform an orthographic projection.
 Parameters:
lon (numpy.ndarray (1D)) – Longitude array [degrees]
lat (numpy.ndarray (1D)) – Latitude array [degrees]
imap (numpy.ndarray) – Data array to be projected. The first two dimensions should be (lat,lon)
central_longitude (float, optional) – Longitude in degrees to be centered beneath the observer
central_latitude (float, optional) – Latitude in degrees to be centered beneath the observer
ny (int, optional) – Number of pixels in the Y direction for the output projection
nx (int, optional) – Number of pixels in the X direction for the output projection
interp (str, optional) – Interpolation to use. Currently only ‘bilinear’ is accepted; otherwise nearestneighbor will be used.
 Returns:
The projected output
 Return type:
numpy.ndarray (ny,nx)

exoplasim.gcmt.
parse
(file, variable, lat=None, lon=None)[source]¶ Retrieve a variable from a NetCDF file
 Parameters:
file (str) – Path to a NetCDF file
variable (str) – Name of the variable to extract
lat (str, optional) – If the latitude and longitude arrays have nonstandard names, specify them here.
lon (str, optional) – If the latitude and longitude arrays have nonstandard names, specify them here.
 Returns:
Requested output field
 Return type:
numpy.ndarray

exoplasim.gcmt.
spatialmath
(variable, lat=None, lon=None, file=None, mean=True, time=None, ignoreNaNs=True, lev=None, radius=6371000.0)[source]¶ Compute spatial means or sums of data
 Parameters:
variable (str, numpy.ndarray) – The variable to operate on. Can either be a data array, or the name of a variable. If the latter, file must be specified.
lat (numpy.ndarray, optional) – Latitude and longitude arrays. If file is provided and lat and lon are not, they will be extracted from the file.
lon (numpy.ndarray, optional) – Latitude and longitude arrays. If file is provided and lat and lon are not, they will be extracted from the file.
file (str, optional) – Path to a NetCDF output file to open and extract data from.
mean (bool, optional) – If True, compute a global mean. If False, compute a global sum.
time (int, optional, or "all") – The time index on which to slice. If unspecified, a time average will be returned. If set to “all”, the time axis will be preserved.
ignoreNaNs (bool, optional) – If True, use NaNsafe numpy operators.
lev (int, optional) – If set, slice a 3D spatial array at the specified level.
radius (float, optional) – Radius of the planet in meters. Only used if mean=False.
 Returns:
 Return type:
float

exoplasim.gcmt.
tl2eq
(variable, lon, lat, substellar=0.0)[source]¶ Transform a tidallylocked variable to standard equatorial coordinates
Note that in our tidallylocked coordinate system, 0 degrees longitude is the substellarsouth poleantistellar meridian, and 90 degrees latitude is the substellar point, such that the evening hemisphere is 0180 degrees longitude, the morning hemisphere is 180360 degrees longitude, the north equatorial pole is at (0, 180), and easterly flow is counterclockwise. Note that this differs from the coordinate system introduced in Koll & Abbot (2015) in that theirs is a lefthanded coordinate system, with the south pole at (0, 180) and counterclockwise easterly flow, which represents a southfacing observer inside the sphere, while ours is a righthanded coordinate system, representing a southfacing observer outside the sphere, which is the usual convention for spherical coordinate systems.
 Parameters:
variable (numpy.ndarray (2D, 3D, or 4D)) – ND data array to be transformed. Final two dimensions must be (lat,lon)
lon (numpy.ndarray) – 1D array of longitudes [deg]
lat (numpy.ndarray) – 1D array of latitudes [deg]
substellar (float, optional) – Longitude of the substellar point (defaults to 0 degrees)
 Returns:
Transformed longitudes, latitudes, and data array.
 Return type:
numpy.ndarray, numpy.ndarray, numpy.ndarray

exoplasim.gcmt.
tl2eq_coords
(lon, lat, substellar=0.0)[source]¶ Compute equatorial coordinates of a set of tidallylocked latlon coordinates.
Transforms tidallylocked coordinates into the standard equatorial coordinate system. Note that in our tidallylocked coordinate system, 0 degrees longitude is the substellarsouth poleantistellar meridian, and 90 degrees latitude is the substellar point, such that the evening hemisphere is 0180 degrees longitude, the morning hemisphere is 180360 degrees longitude, the north equatorial pole is at (0, 180), and easterly flow is counterclockwise. Note that this differs from the coordinate system introduced in Koll & Abbot (2015) in that theirs is a lefthanded coordinate system, with the south pole at (0, 180) and counterclockwise easterly flow, which represents a southfacing observer inside the sphere, while ours is a righthanded coordinate system, representing a southfacing observer outside the sphere, which is the usual convention for spherical coordinate systems.
 Parameters:
lon (numpy.ndarray) – Longitudes in tidallylocked coordinates [degrees]
lat (numpy.ndarray) – Latitudes in tidallylocked coordinates [degrees]
substellar (float, optional) – Longitude of the substellar point. [degrees]
 Returns:
Transformed longitudes and latitudes [degrees]
 Return type:
numpy.ndarray, numpy.ndarray

exoplasim.gcmt.
tlstream
(dataset, radius=6371000.0, gravity=9.80665, substellar=0.0)[source]¶ Compute the tidallylocked streamfunction
 Parameters:
dataset (str or ExoPlaSim Dataset) – Either path to ExoPlaSim Dataset of model output or an instance of the dataset.
radius (float, optional) – Planetary radius [m]
gravity (float, optional) – Surface gravity [m/s^2]
substellar (float, optional) – Longitude of the substellar point in degrees.
 Returns:
tidallylocked latitude, layer interface pressures, and TL streamfunction
 Return type:
numpy.ndarray(1D), numpy.ndarray(1D), numpy.ndarray(2D)
exoplasim.pyburn module¶
Read raw exoplasim output files and postprocess them into netCDF output files.

exoplasim.pyburn.
advancedDataset
(filename, variablecodes, substellarlon=180.0, radius=1.0, gravity=9.80665, gascon=287.0, logfile=None)[source]¶ Read a raw output file, and construct a dataset.
 Parameters:
filename (str) – Path to the raw output file
variablecodes (dict) –
Variables to include. Each member must use the variable name as the key, and contain a subdict with the horizontal mode, zonal averaging, and physics filtering options optionall set as members. For example:
{"ts":{"mode":"grid","zonal":False}, "stf":{"mode":"grid","zonal":True,"physfilter":True}}
Options that are not set take on their default values from
dataset()
.mode (str, optional) – Horizontal output mode. Can be ‘grid’, meaning the Gaussian latitudelongitude grid used in ExoPlaSim, ‘spectral’, meaning spherical harmonics, ‘fourier’, meaning Fourier coefficients and latitudes, ‘synchronous’, meaning a Gaussian latitudelongitude grid in the synchronous coordinate system defined in Paradise, et al (2021), with the north pole centered on the substellar point, or ‘syncfourier’, meaning Fourier coefficients computed along the dipolar meridians in the synchronous coordinate system (e.g. the substellarantistellarpolar meridian, which is 0 degrees, or the substellareveningantistellarmorning equatorial meridian, which is 90 degrees). Because this will get assigned to the original latitude array, that will become 90 degrees for the polar meridian, and 0 degrees for the equatorial meridian, identical to the typical equatorial coordinate system.
zonal (bool, optional) – For grid modes (“grid” and “synchronous”), compute and output zonal means
physfilter (bool, optional) – Whether or not a physics filter should be used when transforming spectral variables to Fourier or grid domains
substellarlon (float, optional) – If mode=’synchronous’, the longitude of the substellar point in equatorial coordinates, in degrees
radius (float, optional) – Planet radius in Earth radii
gravity (float, optional) – Surface gravity in m/s^2.
gascon (float, optional) – Specific gas constant for dry gas (R$_d$) in J/kg/K.
logfile (str or None, optional) – If None, log diagnostics will get printed to standard output. Otherwise, the log file to which diagnostic output should be written.
 Returns:
Dictionary of extracted variables
 Return type:
dict

exoplasim.pyburn.
csv
(rdataset, filename='most_output.tar.gz', logfile=None, extracompression=False)[source]¶ Write a dataset to CSV/TXTtype output, optionally compressed.
If a tarball format (e.g. *.tar or *.tar.gz) is used, output files will be packed into a tarball. gzip (.gz), bzip2 (.bz2), and lzma (.xz) compression types are supported. If a tarball format is not used, then accepted file extensions are .csv, .txt, or .gz. All three will produce a directory named following the filename pattern, with one file per variable in the directory. If the .gz extension is used, NumPy will compress each output file using gzip compression.
Files will only contain 2D variable information, so the first N1 dimensions will be flattened. The original variable shape is included in the file header (prepended with a # character) as the first items in a commaseparated list, with the first nondimension item given as the ‘’ placeholder. On reading variables from these files, they should be reshaped according to these dimensions. This is true even in tarballs (which contain CSV files).
 Parameters:
rdataset (dict) – A dictionary of outputs as generated from
pyburn.dataset()
filename (str, optional) – Path to the output file that should be written. This will be parsed to determine output type.
logfile (str or None, optional) – If None, log diagnostics will get printed to standard output. Otherwise, the log file to which diagnostic output should be written.
extracompression (bool, optional) – If True, then component files in tarball outputs will be compressed individually with gzip, instead of being plaintext CSV files.
 Returns:
If nontarball output was used, a tuple containing a list of paths to output files, and a string giving the name of the output directory. If tarball output was used, a relative path to the tarball.
 Return type:
tuple or str

exoplasim.pyburn.
dataset
(filename, variablecodes, mode='grid', zonal=False, substellarlon=180.0, physfilter=False, radius=1.0, gravity=9.80665, gascon=287.0, logfile=None)[source]¶ Read a raw output file, and construct a dataset.
 Parameters:
filename (str) – Path to the raw output file
variablecodes (arraylike) – list of variables to include. Can be the integer variable codes from the burn7 postprocessor conventions (as either strings or integers), or the short variable name strings (e.g. ‘rlut’), or a combination of the two.
mode (str, optional) – Horizontal output mode. Can be ‘grid’, meaning the Gaussian latitudelongitude grid used in ExoPlaSim, ‘spectral’, meaning spherical harmonics, ‘fourier’, meaning Fourier coefficients and latitudes, ‘synchronous’, meaning a Gaussian latitudelongitude grid in the synchronous coordinate system defined in Paradise, et al (2021), with the north pole centered on the substellar point, or ‘syncfourier’, meaning Fourier coefficients computed along the dipolar meridians in the synchronous coordinate system (e.g. the substellarantistellarpolar meridian, which is 0 degrees, or the substellareveningantistellarmorning equatorial meridian, which is 90 degrees). Because this will get assigned to the original latitude array, that will become 90 degrees for the polar meridian, and 0 degrees for the equatorial meridian, identical to the typical equatorial coordinate system.
zonal (bool, optional) – For grid modes (“grid” and “synchronous”), compute and output zonal means
substellarlon (float, optional) – If mode=’synchronous’, the longitude of the substellar point in equatorial coordinates, in degrees
physfilter (bool, optional) – Whether or not a physics filter should be used when transforming spectral variables to Fourier or grid domains
radius (float, optional) – Planet radius in Earth radii
gravity (float, optional) – Surface gravity in m/s^2.
gascon (float, optional) – Specific gas constant for dry gas (R$_d$) in J/kg/K.
logfile (str or None, optional) – If None, log diagnostics will get printed to standard output. Otherwise, the log file to which diagnostic output should be written.
 Returns:
Dictionary of extracted variables
 Return type:
dict

exoplasim.pyburn.
hdf5
(rdataset, filename='most_output.hdf5', append=False, logfile=None)[source]¶ Write a dataset to HDF5 output.
Note: HDF5 files are opened in append mode. This means that this format can be used to create a single output dataset for an entire simulation.
HDF5 files here are generated with gzip compression at level 9, with chunk rearrangement and Fletcher32 checksum data protection.
 Parameters:
rdataset (dict) – A dictionary of outputs as generated from
pyburn.dataset()
filename (str, optional) – Path to the output file that should be written.
append (bool, optional) – Whether or not the file should be opened in append mode, or overwritten (default).
logfile (str or None, optional) – If None, log diagnostics will get printed to standard output. Otherwise, the log file to which diagnostic output should be written.
 Returns:
An HDF5 object corresponding to the file that has been written.
 Return type:
object

exoplasim.pyburn.
netcdf
(rdataset, filename='most_output.nc', append=False, logfile=None)[source]¶ Write a dataset to a netCDF file.
 Parameters:
rdataset (dict) – A dictionary of outputs as generated from
pyburn.dataset()
filename (str, optional) – Path to the output file that should be written.
append (bool, optional) – Whether the file should be opened in “append” mode, or overwritten (default).
logfile (str or None, optional) – If None, log diagnostics will get printed to standard output. Otherwise, the log file to which diagnostic output should be written.
 Returns:
A netCDF object corresponding to the file that has been written.
 Return type:
object

exoplasim.pyburn.
npsavez
(rdataset, filename='most_output.npz', logfile=None)[source]¶ Write a dataset to a NumPy compressed .npz file.
Two output files will be created: filename as specified (e.g. most_output.npz), which contains the data variables, and a metadata file (e.g. most_output_metadata.npz), which contains the metadata headers associated with each variable.
 Parameters:
rdataset (dict) – A dictionary of outputs as generated from
pyburn.dataset()
filename (str, optional) – Path to the output file that should be written.
logfile (str or None, optional) – If None, log diagnostics will get printed to standard output. Otherwise, the log file to which diagnostic output should be written.
 Returns:
A 2item tuple containing (variables, meta), each of which is a dictionary with variable names as keys.
 Return type:
tuple

exoplasim.pyburn.
postprocess
(rawfile, outfile, logfile=None, namelist=None, variables=None, mode='grid', zonal=False, substellarlon=180.0, physfilter=False, timeaverage=True, stdev=False, times=12, interpolatetimes=True, radius=1.0, gravity=9.80665, gascon=287.0, mars=False)[source]¶ Convert a raw output file into a postprocessed formatted file.
Output format is determined by the file extension of outfile. Current supported formats are NetCDF (*.nc), HDF5 (*.hdf5, *.he5, *.h5), numpy’s
np.savez_compressed
format (*.npz), and CSV format. If NumPy’s singlearray .npy extension is used, .npz will be substituted–this is a compressed ZIP archive containing .npy files. Additionally, the CSV output format can be used in compressed form either individually by using the .gz file extension, or collectively via tarballs (compressed or uncompressed).If a tarball format (e.g. *.tar or *.tar.gz) is used, output files will be packed into a tarball. gzip (.gz), bzip2 (.bz2), and lzma (.xz) compression types are supported. If a tarball format is not used, then accepted file extensions are .csv, .txt, or .gz. All three will produce a directory named following the filename pattern, with one file per variable in the directory. If the .gz extension is used, NumPy will compress each output file using gzip compression.
CSVtype files will only contain 2D variable information, so the first N1 dimensions will be flattened. The original variable shape is included in the file header (prepended with a # character) as the first items in a commaseparated list, with the first nondimension item given as the ‘’ placeholder. On reading variables from these files, they should be reshaped according to these dimensions. This is true even in tarballs (which contain CSV files).
A T21 model output with 10 vertical levels, 12 output times, all supported variables in grid mode,and no standard deviation computation will have the following sizes for each format:
Format
Size
netCDF
12.8 MiB
HDF5
17.2 MiB
NumPy (default)
19.3 MiB
tar.xz
33.6 MiB
tar.bz2
36.8 MiB
gzipped
45.9 MiB
uncompressed
160.2 MiB
Using the NetCDF (.nc) format requires the netCDF4 python package.
Using the HDF5 format (.h5, .hdf5, .he5) requires the h5py python package.
 Parameters:
rawfile (str) – Path to the raw output file
outfile (str) – Path to the destination output file. The file extension determines the format. Currently, netCDF (*.nc). numpy compressed (*.npz), HDF5 (*.hdf5, *.he5, *.h5), or CSVtype (*.csv, *.txt, *.gz, *.tar, *.tar.gz, *.tar.bz2, *.tar.xz) are supported. If a format (such as npz) that requires that metadata be placed in a separate file is chosen, a second file with a ‘_metadata’ suffix will be created.
append (bool, optional) – If True, and outfile already exists, then append to outfile rather than overwriting it. Currently only supported for netCDF and HDF5 formats. Support for other formats coming soon.
logfile (str or None, optional) – If None, log diagnostics will get printed to standard output. Otherwise, the log file to which diagnostic output should be written.
namelist (str, optional) – Path to a burn7 postprocessor namelist file. If not given, then
variables
must be set.variables (list or dict, optional) – If a list is given, a list of either variable keycodes (integers or strings), or the abbreviated variable name (e.g. ‘ts’ for surface temperature). If a dict is given, each item in the dictionary should have the keycode or variable name as the key, and the desired horizontal mode and additional options for that variable as a subdict. Each member of the subdict should be passable as **kwargs to
advancedDataset()
. If None, thennamelist
must be set.mode (str, optional) – Horizontal output mode, if modes are not specified for individual variables. Options are ‘grid’, meaning the Gaussian latitudelongitude grid used in ExoPlaSim, ‘spectral’, meaning spherical harmonics, ‘fourier’, meaning Fourier coefficients and latitudes, ‘synchronous’, meaning a Gaussian latitudelongitude grid in the synchronous coordinate system defined in Paradise, et al (2021), with the north pole centered on the substellar point, or ‘syncfourier’, meaning Fourier coefficients computed along the dipolar meridians in the synchronous coordinate system (e.g. the substellarantistellarpolar meridian, which is 0 degrees, or the substellareveningantistellarmorning equatorial meridian, which is 90 degrees). Because this will get assigned to the original latitude array, that will become 90 degrees for the polar meridian, and 0 degrees for the equatorial meridian, identical to the typical equatorial coordinate system.
zonal (bool, optional) – Whether zonal means should be computed for applicable variables.
substellarlon (float, optional) – Longitude of the substellar point. Only relevant if a synchronous coordinate output mode is chosen.
physfilter (bool, optional) – Whether or not a physics filter should be used in spectral transforms.
times (int or arraylike or None, optional) – Either the number of timestamps by which to divide the output, or a list of times given as a fraction of the output file duration (which enables e.g. a higher frequency of outputs during periapse of an eccentric orbit, when insolation is changing more rapidly). If None, the timestamps in the raw output will be written directly to file.
timeaverage (bool, optional) – Whether or not timestamps in the output file should be averaged to produce the requested number of output timestamps. Timestamps for averaged outputs will correspond to the middle of the averaged time period.
stdev (bool, optional) – Whether or not standard deviations should be computed. If timeaverage is True, this will be the standard deviation over the averaged time period; if False, then it will be the standard deviation over the whole duration of the output file
interpolatetimes (bool, optional) – If true, then if the times requested don’t correspond to existing timestamps, outputs will be linearly interpolated to those times. If false, then nearestneighbor interpolation will be used.
radius (float, optional) – Planet radius in Earth radii
gravity (float, optional) – Surface gravity in m/s^2.
gascon (float, optional) – Specific gas constant for dry gas (R$_d$) in J/kg/K.
mars (bool, optional) – If True, use Mars constants

exoplasim.pyburn.
readallvariables
(fbuffer)[source]¶ Extract all variables and their headers from a file byte buffer.
Doing this and then only keeping the codes you want may be faster than extracting variables one by one, because it only needs to seek through the file one time.
 Parameters:
fbuffer (bytes) – Binary bytes read from a file opened with
mode='rb'
and read withfile.read()
. Returns:
A dictionary containing all variable headers (by variable code), and a dictionary containing all variables, again by variable code.
 Return type:
dict, dict

exoplasim.pyburn.
readfile
(filename)[source]¶ Extract all variables from a raw plasim output file and refactor them into the right shapes
This routine will only produce what it is in the file; it will not compute derived variables.
 Parameters:
filename (str) – Path to the output file to read
 Returns:
Dictionary of model variables, indexed by numerical code
 Return type:
dict

exoplasim.pyburn.
readrecord
(fbuffer, n, en, ml, mf)[source]¶ Read a Fortran record from the buffer, starting at index n, and return the header, data, and updated n.
 Parameters:
fbuffer (bytes) – Binary bytes read from a file opened with
mode='rb'
and read withfile.read()
.n (int) – The index of the word at which to start, in bytes. A 32bit word has length 4, so the current position in words would be 4*n assuming 4byte words, or 8*n if 64 bits and 8byte words.
en (str) – Endianness, denoted by “>” or “<”
ml (int) – Length of a record marker
mf (str) – Format of the record marker (‘i’ or ‘l’)
 Returns:
A tuple containing first the header, then the data contained in the record, and finally the new position in the buffer in bytes.
 Return type:
arraylike, arraylike, int

exoplasim.pyburn.
readvariablecode
(fbuffer, kcode, en, ml, mf)[source]¶ Seek through a binary output buffer and extract all records associated with a variable code.
Note, assembling a variable list piece by piece in this way may be slower than reading all variables at once, because it requires seeking all the way through the buffer multiple times for each variable. This will likely only be faster if you only need a small number of variables.
 Parameters:
fbuffer (bytes) – Binary bytes read from a file opened with
mode='rb'
and read withfile.read()
.kcode (int) – The integer code associated with the variable. For possible codes, refer to the ``Postprocessor Variable Codes. <postprocessor.html#postprocessorvariablecodes>`_
en (str) – Endianness, denoted by “>” or “<”
ml (int) – Length of a record marker
mf (str) – Format of the record marker (‘i’ or ‘l’)
 Returns:
A tuple containing first the header, then the variable data, as one concatenated 1D variable.
 Return type:
arraylike, arraylike

exoplasim.pyburn.
refactorvariable
(variable, header, nlev=10)[source]¶ Given a 1D data array extracted from a file with
readrecord
, reshape it into its appropriate dimensions. Parameters:
variable (arraylike) – Data array extracted from an output file using
readrecord
. Can also be the product of a concatenated file assembled withreadvariable
.header (arraylike) – The header array extracted from the record associated with
variable
. This header contains dimensional information.nlev (int, optional) – The number of vertical levels in the variable. If 1, vertical levels will not be a dimension in the output variable.
 Returns:
A numpy array with dimensions inferred from the header.
 Return type:
numpy.ndarray
exoplasim.randomcontinents module¶
usage: randomcontinents.py [h] [z] [c CONTINENTS] [f LANDFRACTION]
[n NAME] [m MAXZ] [nlats NLATS]
[l HEMISPHERELONGITUDE] [o]
Randomly generate continents up to a specified landfraction. Topography
optional.
optional arguments:
h, help show this help message and exit
z, topo Generate topographical geopotential map
c CONTINENTS, continents CONTINENTS
Number of continental cratons
f LANDFRACTION, landfraction LANDFRACTION
Land fraction
n NAME, name NAME Assign a name for the planet
m MAXZ, maxz MAXZ Maximum elevation in km assuming Earth gravity
nlats NLATS Number of latitudes (evenlyspaced)will also set
longitudes (twice as many).
l HEMISPHERELONGITUDE, hemispherelongitude HEMISPHERELONGITUDE
Confine land to a hemisphere centered on a given
longitude
o, orthographic Plot orthographic projections centered on
hemispherelongitude

exoplasim.randomcontinents.
generate
(name='Alderaan', continents=7, landfraction=0.29, maxz=10.0, nlats=32, hemispherelongitude=nan, ntopo=False, orthographic=False)[source]¶ Randomly generate continents up to specified land fraction. Topography optional.
Generates name_surf_0172.sra, the land mask file, and (if requested) name_surf_0129.sra, the topography file.
 Parameters:
name (str, optional) – Name for the planet; will be used in filenames.
continents (int, optional) – Number of initial continental cratons. Note that due to craton collisions, this may not be the number of final landmasses.
landfraction (float, optional) – Target land fraction (may deviate slightly).
maxz (float, optional) – Maximum surface elevation under Earth gravity (nonEarth gravity will change the final elevation)
nlats (int, optional) – Number of latitudes. If set to False, T21 Gaussian latitudes will be used. Longitudes are 2*nlats.
hemispherelongitude (float, optional) – If finite, confine land to a hemisphere centered on this longitude.
topo (bool, optional) – If True, compute topography.
orthorgraphic (bool, optional) – If True, plot orthographic projections centered on hemispherelongitude.
 Returns:
Longitude, Latitude, landsea mask, and if requested, surface geopotential (topography)
 Return type:
np.ndarray(2*nlat), np.ndarray(nlat), np.ndarray(nlat,2*nlat)[, np.ndarray(nlat,2*nlat)]

exoplasim.randomcontinents.
main
()[source]¶ Commandline tool to randomly generate continents up to specified land fraction. Topography optional.
Do not invoke as an imported function; must run directly.
 Options
 z,–topo
Generate topographical geopotential map
 c,–continents
Number of continental cratons
 f,–landfraction
Land fraction
 n,–name
Assign a name for the planet
 m,–maxz
Maximum elevation in km assuming Earth gravity
 nlats
Number of latitudes (evenlyspaced)–will also set longitudes (twice as many). If unset, PlaSim latitudes and longitudes will be used (T21 resolution)”
 l,–hemispherelongitude
Confine land to a hemisphere centered on a given longitude
 o,–orthographic
Plot orthographic projections centered on hemispherelongitude
 name_surf_0172.sra
Land mask SRA file
 name_surf_0129.sra (optional)
Topography geopotential SRA file (if requested)

exoplasim.randomcontinents.
writePGM
(name, heightfield)[source]¶ Write a latlon field to a .pgm image file (usually topo field)
 Parameters:
name (str) – The name with which to label this map
heightfield (numpy.ndarray) – The 2D map to write to file.

exoplasim.randomcontinents.
writeSRA
(name, kcode, field, NLAT, NLON)[source]¶ Write a latlon field to a formatted .sra file
 Parameters:
name (str) – The name with which to label this map
kcode (int) – The integer map code for specifying what kind of boundary file this is (see the PlaSim documentation for more details)
field (numpy.ndarray) – The map to write to file. Should have the dimensions (NLAT,NLON).
NLAT (int) – The number of latitudes
NLON (int) – The number of longitudes
exoplasim.makestellarspec module¶

exoplasim.makestellarspec.
main
()[source]¶ Convert spectral files to exoplasimcompliant formats, including resampling to the necessary resolutions.
Must give as input a spectrum file generated by the Phoenix stellar spectrum web simulator, https://phoenix.enslyon.fr/simulatorjsf2226. Do not use as an imported function; only call directly as a commandline program.
Usage
>>> python makestellarspec.py spectrum.txt mystarsname
 Yields:
mystarsname.dat – 965 wavelengths
mystarsname_hr.dat – 2048 wavelengths

exoplasim.makestellarspec.
readspec
(sfile, cgs=False)[source]¶ Read a Phoenix stellar spectrum and return wavelengths, fluxes, and units
Takes as input a spectrum file generated by the Phoenix stellar spectrum web simulator, https://phoenix.enslyon.fr/simulatorjsf2226.
 Parameters:
sfile (str) – Path to the spectrum file
cgs (bool, optional) – Whether or not we should try to use CGS units (irrelevant for exoplasim)
 Returns:
Returns wavelengths, fluxes, and the units
 Return type:
numpy.ndarray, numpy.ndarray, str

exoplasim.makestellarspec.
writedat
(wvls, fluxes, name)[source]¶ Write wavelengths and fluxes to a .dat file ExoPlaSim can read.
 Parameters:
wvls (arraylike) – An arraylike object containing a monotonic list of wavelengths going from short to long
fluxes (arraylike) – An arraylike object containing a flux for each wavelength in
wvls
.name (str) – A name to use when generating output files.
 Yields:
name.dat – The provided spectrum in a format ExoPlaSim can read.
exoplasim.pRT module¶

exoplasim.pRT.
basicclouds
(pressure, temperature, cloudwater)[source]¶ A basic cloud parameterization using Tdependent particle size distribution.
This could be replaced with a different (better) cloud particle parameterization, but it should have the same call signature and return the same thing. This parameterization is borrowed from Edwards, et al (2007, doi:10.1016/j.atmosres.2006.03.002).
 Parameters:
pressure (numpy.ndarray) – Pressure array for a column of the model
temperature (numpy.ndarray) – Air temperatures for a column [K]
cloudwater (numpy.ndarray) – Cloud water as a mass fraction [kg/kg] – this is condensed water suspended in the cloud.
 Returns:
Dictionary of keyword arguments for setting clouds with an empirical particle size distribution.
 Return type:
dict

exoplasim.pRT.
image
(output, imagetimes, gases_vmr, obsv_coords, gascon=287.0, gravity=9.80665, Tstar=5778.0, Rstar=1.0, orbdistances=1.0, h2o_lines='HITEMP', num_cpus=4, cloudfunc=None, smooth=True, smoothweight=0.5, filldry=0.0, stellarspec=None, ozone=False, stepsperyear=11520.0, logfile=None, debug=False, orennayar=True, sigma=None, allforest=False, baremountainz=50000.0, colorspace='sRGB', gamma=True, consistency=True, vegpowerlaw=1.0)[source]¶ Compute reflection+emission spectra for snapshot output
This routine computes the reflection+emission spectrum for the planet at each indicated time.
Note that deciding what the observer coordinates ought to be may not be a trivial operation. Simply setting them to always be the same is fine for a 1:1 synchronouslyrotating planet, where the insolation pattern never changes. But for an Earthlike rotator, you will need to be mindful of rotation rate and the local time when snapshots are written. Perhaps you would like to see how things look as the local time changes, as a geosynchronous satellite might observe, or maybe you’d like to only observe in secondary eclipse or in quadrature, and so the observerfacing coordinates may not be the same each time.
 Parameters:
output (ExoPlaSim snapshot output) – Preferably opened with
exoplasim.gcmt.load()
.imagetimes (list(int)) – List of time indices at which the image should be computed.
gases_vmr (dict) – Dictionary of gas species volume mixing ratios for the atmosphere
obsv_coords (numpy.ndarray (3D)) – List of observer (lat,lon) coordinates for each observing time. First axis is time, second axis is for each observer; the third axis is for lat and lon. Should have shape (time,observers,latlon). These are the surface coordinates that are directly facing the observer.
gascon (float, optional) – Specific gas constant
gravity (float, optional) – Surface gravity in SI units
Tstar (float, optional) – Effective temperature of the parent star [K]
Rstar (float, optional) – Radius of the parent star in solar radii
orbdistances (float or numpy.ndarray, optional) – Distance between planet and star in AU
h2o_lines ({'HITEMP','EXOMOL'}, optional) – Either ‘HITEMP’ or ‘EXOMOL’–the line list from which H2O absorption should be sourced
num_cpus (int, optional) – The number of CPUs to use
cloudfunc (function, optional) – A routine which takes pressure, temperature, and cloud water content as arguments, and returns keyword arguments to be unpacked into calc_flux_transm. If not specified, basicclouds will be used.
smooth (bool, optional) – Whether or not to smooth humidity and cloud columns. As of Nov 12, 2021, it is recommended that you use smooth=True for wellbehaved spectra. This is a conservative smoothing operation, meaning the water and cloud column mass should be conserved–what this does is move some water from the waterrich layers into the layers directly above and below.
smoothweight (float, optional) – The fraction of the water in a layer that should be retained during smoothing. A higher value means the smoothing is less severe. 0.95 is probably the upper limit for wellbehaved spectra.
filldry (float, optional) – If nonzero, the floor value for water humidity when moist layers are present above dry layers. Columns will be adjusted in a massconserving manner with excess humidity accounted for in layers above the filled layer, such that total optical depth from TOA is maintained at the dry layer.
stellarspec (arraylike (optional)) – A stellar spectrum measured at the wavelengths in surfacespecs.wvl. If None, a blackbody will be used.
ozone (bool or dict, optional) – True/False/dict. Whether or not forcing from stratospheric ozone should be included. If a dict is provided, it should contain the keys “height”, “spread”, “amount”,”varlat”,”varseason”, and “seasonoffset”, which correspond to the height in meters of peak O3 concentration, the width of the gaussian distribution in meters, the baseline column amount of ozone in cmSTP, the latitudinal amplitude, the magnitude of seasonal variation, and the time offset of the seasonal variation in fraction of a year. The three amounts are additive. To set a uniform, unvarying O3 distribution, ,place all the ozone in “amount”, and set “varlat” and “varseason” to 0.
stepsperyear (int or float, optional) – Number of timesteps per sidereal year. Only used for computing ozone seasonality.
orennayar (bool, optional) – If True, compute truecolour intensity using OrenNayar scattering instead of Lambertian scattering. Most solar system bodies do not exhibit Lambertian scattering.
sigma (float, optional) – If not None and orennayar is True, then this sets the roughness parameter for OrenNayar scattering. sigma=0 is the limit of Lambertian scattering, while sigma=0.97 is the limit for energy conservation. sigma is the standard deviation of the distribution of microfacet normal angles relative to the mean, normalized such that sigma=1.0 would imply truly isotropic microfacet distribution. If sigma is None (default), then sigma is determined based on the surface type in a column and whether clouds are present, using 0.4 for ground, 0.1 for ocean, 0.9 for snow/ice, and 0.95 for clouds.
allforest (bool, optional) – If True, force all land surface to be forested.
baremountainz (float, optional) – If vegetation is present, the geopotential above which mountains become bare rock instead of eroded vegetative regolith. Functionally, this means gray rock instead of brown/tan ground.
colorspace (str or np.ndarray(3,3)) – Color gamut to be used. For available builtin color gamuts, see colormatch.colorgamuts.
gamma (bool or float, optional) – If True, use the piecewise gammafunction defined for sRGB; otherwise if a float, use rgb^(1/gamma). If None, gamma=1.0 is used.
consistency (bool, optional) – If True, force surface albedo to match model output
vegpowerlaw (float, optional) – Scale the apparent vegetation fraction by a power law. Setting this to 0.1, for example, will increase the area that appears partiallyvegetated, while setting it to 1.0 leaves vegetation unchanged.
 Returns:
pRT Atmosphere object, wavelength in microns, Numpy array with dimensions (ntimes,nlat,nlon,nfreq), where ntimes is the number of output times, and nfreq is the number of frequencies in the spectrum, longitudes, latitudes, and an array with dimensions (ntimes,nfreq) corresponding to diskaveraged spectra, with individual contributions weighted by visibility and projected area.
 Return type:
Atmosphere, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray

exoplasim.pRT.
makecolors
(intensities, gamma=True, colorspace='sRGB')[source]¶ Convert (x,y,Y) intensities to RGB values.
Uses CIE colormatching functions and a widegamut RGB colorspace to convert XYZcoordinate color intensities to RGB intensities.
 Parameters:
intensities (arraylike) – Last index must have length 3–array of (x,y,Y) intensities
 Returns:
RGB color values.
 Return type:
arraylike (N,3)

exoplasim.pRT.
makeintensities
(wvl, fluxes)[source]¶ Convert spectrum to (x,y,Y) intensities.
 Parameters:
wvl (arraylike) – Wavelengths in microns
fluxes (arraylike) – Spectrum in fluxes (units are arbitrary)
 Returns:
(x,y,Y) tuple
 Return type:
(float,float,float)

exoplasim.pRT.
orennayarcorrection
(intensity, lon, lat, sollon, sollat, zenith, observer, albedo, sigma)[source]¶ Correct scattering intensity from Lambertian to full OrenNayar.
 Parameters:
intensity (arraylike or float) – Intensity to correct
lon (arraylike or float) – Column(s) longitude in degrees
lat (arraylike or float) – Column(s) latitude in degrees
sollon (float) – Substellar longitude
sollat (float) – Substellar latitude
zenith (arraylike or float) – Solar zenith angle(s) in degrees
observer (tuple) – (lat,lon) tuple of subobserver coordinates
albedo (arraylike or float) – Scattering surface reflectivity (0–1)
sigma (arraylike or float) – Scattering surface roughness. 0.0 is Lambertian, 0.97 is the maximum energyconserving roughness. 0.250.3 is appropriate for many planetary bodies.
 Returns:
Corrected intensity of the same shape as the input intensity
 Return type:
arraylike

exoplasim.pRT.
orennayarcorrection_col
(intensity, lon, lat, sollon, sollat, zenith, observer, albedo, sigma)[source]¶ Correct scattering intensity from Lambertian to full OrenNayar.
 Parameters:
intensity (arraylike or float) – Intensity to correct
lon (arraylike or float) – Column(s) longitude in degrees
lat (arraylike or float) – Column(s) latitude in degrees
sollon (float) – Substellar longitude
sollat (float) – Substellar latitude
zenith (arraylike or float) – Solar zenith angle(s) in degrees
observer (tuple) – (lat,lon) tuple of subobserver coordinates
albedo (arraylike or float) – Scattering surface reflectivity (0–1)
sigma (arraylike or float) – Scattering surface roughness. 0.0 is Lambertian, 0.97 is the maximum energyconserving roughness. 0.250.3 is appropriate for many planetary bodies.
 Returns:
Corrected intensity of the same shape as the input intensity
 Return type:
arraylike

exoplasim.pRT.
save
(filename, dataset, logfile=None, extracompression=False)[source]¶ Save petitRADTRANS ExoPlaSim output to a file.
Output format is determined by the file extension in filename. Current supported formats are NetCDF (*.nc), HDF5 (*.hdf5, *.he5, *.h5), numpy’s
np.savez_compressed
format (*.npz), and CSV format. If NumPy’s singlearray .npy extension is used, .npz will be substituted–this is a compressed ZIP archive containing .npy files. Additionally, the CSV output format can be used in compressed form either individually by using the .gz file extension, or collectively via tarballs (compressed or uncompressed).If a tarball format (e.g. *.tar or *.tar.gz) is used, output files will be packed into a tarball. gzip (.gz), bzip2 (.bz2), and lzma (.xz) compression types are supported. If a tarball format is not used, then accepted file extensions are .csv, .txt, or .gz. All three will produce a directory named following the filename pattern, with one file per variable in the directory. If the .gz extension is used, NumPy will compress each output file using gzip compression.
CSVtype files will only contain 2D variable information, so the first N1 dimensions will be flattened. The original variable shape is included in the file header (prepended with a # character) as the first items in a commaseparated list, with the first nondimension item given as the ‘’ placeholder. On reading variables from these files, they should be reshaped according to these dimensions. This is true even in tarballs (which contain CSV files).
A T21 model output with 10 vertical levels, 12 output times, all supported variables in grid mode,and no standard deviation computation will have the following sizes for each format:
Format
Size
netCDF
12.8 MiB
HDF5
17.2 MiB
NumPy (default)
19.3 MiB
tar.xz
33.6 MiB
tar.bz2
36.8 MiB
gzipped
45.9 MiB
uncompressed
160.2 MiB
Using the NetCDF (.nc) format requires the netCDF4 python package.
Using the HDF5 format (.h5, .hdf5, .he5) requires the h5py python package.
 Parameters:
filename (str) – Path to the destination output file. The file extension determines the format. Currently, netCDF (*.nc). numpy compressed (*.npz), HDF5 (*.hdf5, *.he5, *.h5), or CSVtype (*.csv, *.txt, *.gz, *.tar, *.tar.gz, *.tar.bz2, *.tar.xz) are supported. If a format (such as npz) that requires that metadata be placed in a separate file is chosen, a second file with a ‘_metadata’ suffix will be created.
dataset (dict) – A dictionary containing the fields that should be written to output.
logfile (str or None, optional) – If None, log diagnostics will get printed to standard output. Otherwise, the log file to which diagnostic output should be written.
 Returns:
Open crossformat dataset object
 Return type:
gcmt._Dataset object

exoplasim.pRT.
transit
(output, transittimes, gases_vmr, gascon=287.0, gravity=9.80665, rplanet=6371.0, h2o_lines='HITEMP', num_cpus=4, cloudfunc=None, smooth=False, smoothweight=0.95, ozone=False, stepsperyear=11520.0, logfile=None)[source]¶ Compute transmission spectra for snapshot output
This routine computes the transmission spectrum for each atmospheric column along the terminator, for each time in transittimes.
Note: This routine does not currently include emission from atmospheric layers.
 Parameters:
output (ExoPlaSim snapshot output) – Preferably opened with
exoplasim.gcmt.load()
.transittimes (list(int)) – List of time indices at which the transit should be computed.
gases_vmr (dict) – Dictionary of gas species volume mixing ratios for the atmosphere
gascon (float, optional) – Specific gas constant
gravity (float, optional) – Surface gravity in SI units
rplanet (float, optional) – Planet radius in km
h2o_lines ({'HITEMP','EXOMOL'}, optional) – Either ‘HITEMP’ or ‘EXOMOL’–the line list from which H2O absorption should be sourced
num_cpus (int, optional) – The number of CPUs to use
cloudfunc (function, optional) – A routine which takes pressure, temperature, and cloud water content as arguments, and returns keyword arguments to be unpacked into calc_flux_transm. If not specified, basicclouds will be used.
smooth (bool, optional) – Whether or not to smooth humidity and cloud columns. As of Nov 12, 2021, it is recommended that you use smooth=True for wellbehaved spectra. This is a conservative smoothing operation, meaning the water and cloud column mass should be conserved–what this does is move some water from the waterrich layers into the layers directly above and below.
smoothweight (float, optional) – The fraction of the water in a layer that should be retained during smoothing. A higher value means the smoothing is less severe. 0.95 is probably the upper limit for wellbehaved spectra.
 Returns:
pRT Atmosphere object, Wavelength in microns, array of all transit columns with shape (ntimes,nterm,nfreq), where nterm is the number of terminator columns (timevarying), and nfreq is the number of frequencies in the spectrum, array of lonlat coordinates for each transit specturm, array of spatial weights for each column with the shape (ntimes,nterm) (for averaging), and the spatiallyaveraged transit spectrum, with shape (ntimes,nfreq). Transit radius is in km.
 Return type:
Atmosphere,numpy.ndarray,numpy.ndarray,numpy.darray,numpy.ndarray