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 Earth-like model, but more flexible.
Identical to
Model
, except configuration options common for Earth-like models requiring slightly more flexibility are the default when configure is called–specifically, 45-minute 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 time-averaged 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 high-cadence output should be written (1=yes).
'start'
intTimestep at which high-cadence output should begin.
'end'
intTimestep at which high-cadence output should end.
'interval'
intHow many timesteps should elapse between high-cadence 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 45-year 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”,”static|clear”,”clear|static”}, optional
The inclusion of ‘static’ will disable horizontal advection, forcing ExoPlaSim into a column-only 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="gp|exp|sp"
orphysicsfilter="gp|cesaro"
.- 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 Lander-Hoskins 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 similarly-named file with the “_hr.dat” suffix must also exist and have 2048 wavelengths. Appropriately-formatted 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, pressure-broadening 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 cm-STP, 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{“ECHAM-3”,”ECHAM-6”,”Lambertian}, optional
The zenith-angle dependence to use for blue-light reflectance from the ocean. Can be
'Lambertian'
/'uniform'
,'ECHAM-3'
/'plasim'
/'default'
, or'ECHAM-6'
. The default is'ECHAM-3'
(synonymous with'plasim'
and'default'
), which is the dependence used in the ECHAM-3 model.
Orbital Parameters
- yearfloat, optional
Number of 24-hour 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 zeroed-out.- aquaplanetbool, optional
True/False. If True, the surface will be entirely ocean-covered.
- desertplanetbool, optional
True/False. If True, the surface will be entirely land-covered.
- 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 Earth-like 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 mixed-layer 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
- Carbon-Silicate Weathering
- co2weatheringbool, optional
True/False. Toggles whether or not carbon-silicate 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 above-ground 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 supply-limited 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 year-round 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 high-cadence 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 high-cadence 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) Lower-atmosphere vorticity threshold for nktrigger output. Default 1.2*10^-5 s^-1
- VRMTHRESHfloat, optional
(unused) Ventilation-reduced 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) Lower-atmosphere 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”. Earth-like models typically do not require filtering, but tidally-locked models do. Filtering may be beneficial for Earth-like models at very high resolutions as well, or if there is sharp topography.
Three filter functional forms are included in ExoPlaSim: Cesaro, exponential, and Lander-Hoskins. 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]_
Lander-Hoskins: \(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 small-scale features in the spectral fields causing small-scale 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 line-by-line 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 compilation-inducing 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 Mars-specific 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, netcdf4-python 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 8-byte precision. 4-byte may run slightly faster, but possibly at the cost of reduced stability. If there are machine-specific 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 error-handling 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 single-array .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.
CSV-type files will only contain 2D variable information, so the first N-1 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 non-dimension 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 high-cadence (‘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 plain-text comma-separated 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,netcdf4-python
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 sub-dict. 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 latitude-longitude grid used in ExoPlaSim, ‘spectral’, meaning spherical harmonics, ‘fourier’, meaning Fourier coefficients and latitudes, ‘synchronous’, meaning a Gaussian latitude-longitude 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 substellar-antistellar-polar meridian, which is 0 degrees, or the substellar-evening-antistellar-morning 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 array-like 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 nearest-neighbor 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='ECHAM-3', 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.2e-05, '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 time-averaged 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 high-cadence output should be written (1=yes).
'start'
intTimestep at which high-cadence output should begin.
'end'
intTimestep at which high-cadence output should end.
'interval'
intHow many timesteps should elapse between high-cadence 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 45-year 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”,”static|clear”,”clear|static”}, optional
The inclusion of ‘static’ will disable horizontal advection, forcing ExoPlaSim into a column-only 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="gp|exp|sp"
orphysicsfilter="gp|cesaro"
.- 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 Lander-Hoskins 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 similarly-named file with the “_hr.dat” suffix must also exist and have 2048 wavelengths. Appropriately-formatted 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, pressure-broadening 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 cm-STP, 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{“ECHAM-3”,”ECHAM-6”,”Lambertian}, optional
The zenith-angle dependence to use for blue-light reflectance from the ocean. Can be
'Lambertian'
/'uniform'
,'ECHAM-3'
/'plasim'
/'default'
, or'ECHAM-6'
. The default is'ECHAM-3'
(synonymous with'plasim'
and'default'
), which is the dependence used in the ECHAM-3 model.
Orbital Parameters
- yearfloat, optional
Number of 24-hour 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 zeroed-out.- aquaplanetbool, optional
True/False. If True, the surface will be entirely ocean-covered.
- desertplanetbool, optional
True/False. If True, the surface will be entirely land-covered.
- 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 Earth-like 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 mixed-layer 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
- Carbon-Silicate Weathering
- co2weatheringbool, optional
True/False. Toggles whether or not carbon-silicate 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 above-ground 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 supply-limited 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 year-round 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 high-cadence 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 high-cadence 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) Lower-atmosphere vorticity threshold for nktrigger output. Default 1.2*10^-5 s^-1
- VRMTHRESHfloat, optional
(unused) Ventilation-reduced 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) Lower-atmosphere 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”. Earth-like models typically do not require filtering, but tidally-locked models do. Filtering may be beneficial for Earth-like models at very high resolutions as well, or if there is sharp topography.
Three filter functional forms are included in ExoPlaSim: Cesaro, exponential, and Lander-Hoskins. 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]_
Lander-Hoskins: \(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 small-scale features in the spectral fields causing small-scale 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 time-averaged 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 high-cadence 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:
1-D 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=1e-06, 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 synchronously-rotating planet, where the insolation pattern never changes. But for an Earth-like 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 observer-facing 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,lat-lon). These are the surface coordinates that are directly facing the observer.
snapshot (bool, optional) – Whether snapshot output should be used.
highcadence (bool, optional) – Whether high-cadence 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 well-behaved 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 water-rich 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 well-behaved 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 mass-conserving 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 true-colour intensity using Oren-Nayar 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 auto-generated 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 built-in color gamuts, see colormatch.colorgamuts.
gamma (bool or float, optional) – If True, use the piecewise gamma-function 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 partially-vegetated, 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 array-like) – 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 array-like 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 NaN-tolerant numpy functions.
snapshot (bool, optional) – True/False. If True, use snapshot output instead of time-averaged.
highcadence (bool, optional) – True/False. If True, use high-cadednce output instead of time-averaged.
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 previously-exported 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 already-configured 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 burn7-style namelist, a list of variable codes or keys, or a dictionary containing output options for each variable. If None, then a variable set pre-configured with :py:func`Model.cfgpostprocessor() <exoplasim.Model.cfgpostprocessor>` will be used. If the postprocessor was not pre-configured, 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 high-cadence (‘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 on-the-fly
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 (array-like, 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 high-cadence 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 well-behaved 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 water-rich 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 well-behaved spectra.
logfile (str, optional) – Optional log file to which diagnostic info will be written.
filename (str, optional) – Output filename; will be auto-generated 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 tidally-locked planet with no land.
Identical to
Model
, except configuration options suitable for tidally-locked models are the default when configure() is called, and the surface is entirely ocean-covered. Specifically, a 30-minute timestep, snapshot outputs every 720 timesteps, eccentricity=0.0, 0-degree 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='gp|exp|sp', 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 time-averaged 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 high-cadence output should be written (1=yes).
'start'
intTimestep at which high-cadence output should begin.
'end'
intTimestep at which high-cadence output should end.
'interval'
intHow many timesteps should elapse between high-cadence 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 45-year 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”,”static|clear”,”clear|static”}, optional
The inclusion of ‘static’ will disable horizontal advection, forcing ExoPlaSim into a column-only 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="gp|exp|sp"
orphysicsfilter="gp|cesaro"
.- 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 Lander-Hoskins 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 similarly-named file with the “_hr.dat” suffix must also exist and have 2048 wavelengths. Appropriately-formatted 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, pressure-broadening 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 cm-STP, 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{“ECHAM-3”,”ECHAM-6”,”Lambertian}, optional
The zenith-angle dependence to use for blue-light reflectance from the ocean. Can be
'Lambertian'
/'uniform'
,'ECHAM-3'
/'plasim'
/'default'
, or'ECHAM-6'
. The default is'ECHAM-3'
(synonymous with'plasim'
and'default'
), which is the dependence used in the ECHAM-3 model.
Orbital Parameters
- yearfloat, optional
Number of 24-hour 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 zeroed-out.- aquaplanetbool, optional
True/False. If True, the surface will be entirely ocean-covered.
- desertplanetbool, optional
True/False. If True, the surface will be entirely land-covered.
- 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 Earth-like 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 mixed-layer 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
- Carbon-Silicate Weathering
- co2weatheringbool, optional
True/False. Toggles whether or not carbon-silicate 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 above-ground 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 supply-limited 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 year-round 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 high-cadence 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 high-cadence 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) Lower-atmosphere vorticity threshold for nktrigger output. Default 1.2*10^-5 s^-1
- VRMTHRESHfloat, optional
(unused) Ventilation-reduced 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) Lower-atmosphere 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”. Earth-like models typically do not require filtering, but tidally-locked models do. Filtering may be beneficial for Earth-like models at very high resolutions as well, or if there is sharp topography.
Three filter functional forms are included in ExoPlaSim: Cesaro, exponential, and Lander-Hoskins. 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]_
Lander-Hoskins: \(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 small-scale features in the spectral fields causing small-scale 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 tidally-locked model with no oceans.
Identical to
Model
, except configuration options suitable for tidally-locked models are the default when configure() is called, and the surface is entirely land-covered. Specifically, a 30-minute timestep, snapshot outputs every 720 timesteps, eccentricity=0.0, 0-degree 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='gp|exp|sp', 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 time-averaged 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 high-cadence output should be written (1=yes).
'start'
intTimestep at which high-cadence output should begin.
'end'
intTimestep at which high-cadence output should end.
'interval'
intHow many timesteps should elapse between high-cadence 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 45-year 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”,”static|clear”,”clear|static”}, optional
The inclusion of ‘static’ will disable horizontal advection, forcing ExoPlaSim into a column-only 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="gp|exp|sp"
orphysicsfilter="gp|cesaro"
.- 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 Lander-Hoskins 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 similarly-named file with the “_hr.dat” suffix must also exist and have 2048 wavelengths. Appropriately-formatted 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, pressure-broadening 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 cm-STP, 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{“ECHAM-3”,”ECHAM-6”,”Lambertian}, optional
The zenith-angle dependence to use for blue-light reflectance from the ocean. Can be
'Lambertian'
/'uniform'
,'ECHAM-3'
/'plasim'
/'default'
, or'ECHAM-6'
. The default is'ECHAM-3'
(synonymous with'plasim'
and'default'
), which is the dependence used in the ECHAM-3 model.
Orbital Parameters
- yearfloat, optional
Number of 24-hour 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 zeroed-out.- aquaplanetbool, optional
True/False. If True, the surface will be entirely ocean-covered.
- desertplanetbool, optional
True/False. If True, the surface will be entirely land-covered.
- 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 Earth-like 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 mixed-layer 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
- Carbon-Silicate Weathering
- co2weatheringbool, optional
True/False. Toggles whether or not carbon-silicate 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 above-ground 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 supply-limited 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 year-round 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 high-cadence 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 high-cadence 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) Lower-atmosphere vorticity threshold for nktrigger output. Default 1.2*10^-5 s^-1
- VRMTHRESHfloat, optional
(unused) Ventilation-reduced 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) Lower-atmosphere 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”. Earth-like models typically do not require filtering, but tidally-locked models do. Filtering may be beneficial for Earth-like models at very high resolutions as well, or if there is sharp topography.
Three filter functional forms are included in ExoPlaSim: Cesaro, exponential, and Lander-Hoskins. 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]_
Lander-Hoskins: \(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 small-scale features in the spectral fields causing small-scale 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 tidally-locked model.
Identical to
Model
, except configuration options suitable for tidally-locked models are the default when configure() is called.-
configure
(timestep=30.0, snapshots=720, eccentricity=0.0, ozone=False, obliquity=0.0, physicsfilter='gp|exp|sp', 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 time-averaged 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 high-cadence output should be written (1=yes).
'start'
intTimestep at which high-cadence output should begin.
'end'
intTimestep at which high-cadence output should end.
'interval'
intHow many timesteps should elapse between high-cadence 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 45-year 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”,”static|clear”,”clear|static”}, optional
The inclusion of ‘static’ will disable horizontal advection, forcing ExoPlaSim into a column-only 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="gp|exp|sp"
orphysicsfilter="gp|cesaro"
.- 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 Lander-Hoskins 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 similarly-named file with the “_hr.dat” suffix must also exist and have 2048 wavelengths. Appropriately-formatted 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, pressure-broadening 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 cm-STP, 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{“ECHAM-3”,”ECHAM-6”,”Lambertian}, optional
The zenith-angle dependence to use for blue-light reflectance from the ocean. Can be
'Lambertian'
/'uniform'
,'ECHAM-3'
/'plasim'
/'default'
, or'ECHAM-6'
. The default is'ECHAM-3'
(synonymous with'plasim'
and'default'
), which is the dependence used in the ECHAM-3 model.
Orbital Parameters
- yearfloat, optional
Number of 24-hour 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 zeroed-out.- aquaplanetbool, optional
True/False. If True, the surface will be entirely ocean-covered.
- desertplanetbool, optional
True/False. If True, the surface will be entirely land-covered.
- 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 Earth-like 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 mixed-layer 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
- Carbon-Silicate Weathering
- co2weatheringbool, optional
True/False. Toggles whether or not carbon-silicate 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 above-ground 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 supply-limited 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 year-round 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 high-cadence 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 high-cadence 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) Lower-atmosphere vorticity threshold for nktrigger output. Default 1.2*10^-5 s^-1
- VRMTHRESHfloat, optional
(unused) Ventilation-reduced 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) Lower-atmosphere 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”. Earth-like models typically do not require filtering, but tidally-locked models do. Filtering may be beneficial for Earth-like models at very high resolutions as well, or if there is sharp topography.
Three filter functional forms are included in ExoPlaSim: Cesaro, exponential, and Lander-Hoskins. 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]_
Lander-Hoskins: \(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 small-scale features in the spectral fields causing small-scale 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 (array-like) – 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:
array-like
-
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 NaN-safe 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 tidally-locked coordinates
Note that in our tidally-locked coordinate system, 0 degrees longitude is the substellar-south pole-antistellar meridian, and 90 degrees latitude is the substellar point, such that the evening hemisphere is 0-180 degrees longitude, the morning hemisphere is 180-360 degrees longitude, the north equatorial pole is at (0, 180), and easterly flow is counter-clockwise. Note that this differs from the coordinate system introduced in Koll & Abbot (2015) in that theirs is a left-handed coordinate system, with the south pole at (0, 180) and counter-clockwise easterly flow, which represents a south-facing observer inside the sphere, while ours is a right-handed coordinate system, representing a south-facing observer outside the sphere, which is the usual convention for spherical coordinate systems.
- Parameters:
variable (numpy.ndarray (2D, 3D, or 4D)) – N-D 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 inverse-distance linear interpolation, will use nearest-neighbor. 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 tidally-locked coordinates of a set of equatorial lat-lon coordinates.
Transforms equatorial coordinates into a tidally-locked coordinate system where 0 degrees longitude is the substellar-south pole-antistellar meridian, and 90 degrees latitude is the substellar point, such that the evening hemisphere is 0-180 degrees longitude, the morning hemisphere is 180-360 degrees longitude, the north equatorial pole is at (0, 180), and easterly flow is counter-clockwise. Note that this differs from the coordinate system introduced in Koll & Abbot (2015) in that theirs is a left-handed coordinate system, with the south pole at (0, 180) and counter-clockwise easterly flow, which represents a south-facing observer inside the sphere, while ours is a right-handed coordinate system, representing a south-facing 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 tidally-locked coordinates
- Parameters:
u (numpy.ndarray (2D, 3D, or 4D)) – N-D data array of zonal velocities to be transformed. Final two dimensions must be (lat,lon)
v (numpy.ndarray (2D, 3D, or 4D)) – N-D 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 tidally-locked 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:
tidally-locked 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 area-weighted mean of a latitude array \(x\), such that:
\[\bar{x} = \frac{\sum_{i=1}^N |\sin(\phi_{i-1/2})-\sin(\phi_{i+1/2})|x_i}{\sum_{i=1}^N |\sin(\phi_{i-1/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 (array-like) – 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 area-weighted 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_{i-1/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 (array-like) – 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 recently-accessed arrays in memory, which will prioritize the most recently-accessed 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 area-weighted mean of a longitude array \(x\), such that:
\[\bar{x} = \frac{\sum_{i=1}^N |\theta_{i-1/2}-\theta_{i+1/2}|x_i}{\sum_{i=1}^N |\theta_{i-1/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 N-1 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 area-weighted 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_{i-1/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 (array-like) – Array or list of longitudes
dsinlat (float, optional) – The sine-latitude 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 NaN-safe 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 2-D 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 nearest-neighbor 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 non-standard names, specify them here.
lon (str, optional) – If the latitude and longitude arrays have non-standard 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 NaN-safe 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 tidally-locked variable to standard equatorial coordinates
Note that in our tidally-locked coordinate system, 0 degrees longitude is the substellar-south pole-antistellar meridian, and 90 degrees latitude is the substellar point, such that the evening hemisphere is 0-180 degrees longitude, the morning hemisphere is 180-360 degrees longitude, the north equatorial pole is at (0, 180), and easterly flow is counter-clockwise. Note that this differs from the coordinate system introduced in Koll & Abbot (2015) in that theirs is a left-handed coordinate system, with the south pole at (0, 180) and counter-clockwise easterly flow, which represents a south-facing observer inside the sphere, while ours is a right-handed coordinate system, representing a south-facing observer outside the sphere, which is the usual convention for spherical coordinate systems.
- Parameters:
variable (numpy.ndarray (2D, 3D, or 4D)) – N-D 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 tidally-locked lat-lon coordinates.
Transforms tidally-locked coordinates into the standard equatorial coordinate system. Note that in our tidally-locked coordinate system, 0 degrees longitude is the substellar-south pole-antistellar meridian, and 90 degrees latitude is the substellar point, such that the evening hemisphere is 0-180 degrees longitude, the morning hemisphere is 180-360 degrees longitude, the north equatorial pole is at (0, 180), and easterly flow is counter-clockwise. Note that this differs from the coordinate system introduced in Koll & Abbot (2015) in that theirs is a left-handed coordinate system, with the south pole at (0, 180) and counter-clockwise easterly flow, which represents a south-facing observer inside the sphere, while ours is a right-handed coordinate system, representing a south-facing observer outside the sphere, which is the usual convention for spherical coordinate systems.
- Parameters:
lon (numpy.ndarray) – Longitudes in tidally-locked coordinates [degrees]
lat (numpy.ndarray) – Latitudes in tidally-locked 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 tidally-locked 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:
tidally-locked 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 sub-dict 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 latitude-longitude grid used in ExoPlaSim, ‘spectral’, meaning spherical harmonics, ‘fourier’, meaning Fourier coefficients and latitudes, ‘synchronous’, meaning a Gaussian latitude-longitude 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 substellar-antistellar-polar meridian, which is 0 degrees, or the substellar-evening-antistellar-morning 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/TXT-type 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 N-1 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 non-dimension 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 plain-text CSV files.
- Returns:
If non-tarball 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 (array-like) – 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 latitude-longitude grid used in ExoPlaSim, ‘spectral’, meaning spherical harmonics, ‘fourier’, meaning Fourier coefficients and latitudes, ‘synchronous’, meaning a Gaussian latitude-longitude 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 substellar-antistellar-polar meridian, which is 0 degrees, or the substellar-evening-antistellar-morning 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 2-item 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 single-array .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.
CSV-type files will only contain 2D variable information, so the first N-1 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 non-dimension 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 CSV-type (*.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 sub-dict. 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 latitude-longitude grid used in ExoPlaSim, ‘spectral’, meaning spherical harmonics, ‘fourier’, meaning Fourier coefficients and latitudes, ‘synchronous’, meaning a Gaussian latitude-longitude 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 substellar-antistellar-polar meridian, which is 0 degrees, or the substellar-evening-antistellar-morning 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 array-like 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 nearest-neighbor 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 32-bit word has length 4, so the current position in words would be 4*n assuming 4-byte words, or 8*n if 64 bits and 8-byte 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:
array-like, array-like, 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#postprocessor-variable-codes>`_
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:
array-like, array-like
-
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 (array-like) – Data array extracted from an output file using
readrecord
. Can also be the product of a concatenated file assembled withreadvariable
.header (array-like) – 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 land-fraction. 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 (evenly-spaced)--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 (non-Earth 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, land-sea 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]¶ Command-line 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 (evenly-spaced)–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 lat-lon field to a .pgm image file (usually topo field)
- Parameters:
name (str) – The name with which to label this map
heightfield (numpy.ndarray) – The 2-D map to write to file.
-
exoplasim.randomcontinents.
writeSRA
(name, kcode, field, NLAT, NLON)[source]¶ Write a lat-lon 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 exoplasim-compliant formats, including resampling to the necessary resolutions.
Must give as input a spectrum file generated by the Phoenix stellar spectrum web simulator, https://phoenix.ens-lyon.fr/simulator-jsf22-26. Do not use as an imported function; only call directly as a command-line 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.ens-lyon.fr/simulator-jsf22-26.
- 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 (array-like) – An array-like object containing a monotonic list of wavelengths going from short to long
fluxes (array-like) – An array-like 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 T-dependent 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 synchronously-rotating planet, where the insolation pattern never changes. But for an Earth-like 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 observer-facing 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,lat-lon). 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 well-behaved 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 water-rich 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 well-behaved 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 mass-conserving 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 (array-like (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 cm-STP, 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 true-colour intensity using Oren-Nayar 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 Oren-Nayar 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 built-in color gamuts, see colormatch.colorgamuts.
gamma (bool or float, optional) – If True, use the piecewise gamma-function 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 partially-vegetated, 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 disk-averaged 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 color-matching functions and a wide-gamut RGB colorspace to convert XYZ-coordinate color intensities to RGB intensities.
- Parameters:
intensities (array-like) – Last index must have length 3–array of (x,y,Y) intensities
- Returns:
RGB color values.
- Return type:
array-like (N,3)
-
exoplasim.pRT.
makeintensities
(wvl, fluxes)[source]¶ Convert spectrum to (x,y,Y) intensities.
- Parameters:
wvl (array-like) – Wavelengths in microns
fluxes (array-like) – 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 Oren-Nayar.
- Parameters:
intensity (array-like or float) – Intensity to correct
lon (array-like or float) – Column(s) longitude in degrees
lat (array-like or float) – Column(s) latitude in degrees
sollon (float) – Substellar longitude
sollat (float) – Substellar latitude
zenith (array-like or float) – Solar zenith angle(s) in degrees
observer (tuple) – (lat,lon) tuple of sub-observer coordinates
albedo (array-like or float) – Scattering surface reflectivity (0–1)
sigma (array-like or float) – Scattering surface roughness. 0.0 is Lambertian, 0.97 is the maximum energy-conserving roughness. 0.25-0.3 is appropriate for many planetary bodies.
- Returns:
Corrected intensity of the same shape as the input intensity
- Return type:
array-like
-
exoplasim.pRT.
orennayarcorrection_col
(intensity, lon, lat, sollon, sollat, zenith, observer, albedo, sigma)[source]¶ Correct scattering intensity from Lambertian to full Oren-Nayar.
- Parameters:
intensity (array-like or float) – Intensity to correct
lon (array-like or float) – Column(s) longitude in degrees
lat (array-like or float) – Column(s) latitude in degrees
sollon (float) – Substellar longitude
sollat (float) – Substellar latitude
zenith (array-like or float) – Solar zenith angle(s) in degrees
observer (tuple) – (lat,lon) tuple of sub-observer coordinates
albedo (array-like or float) – Scattering surface reflectivity (0–1)
sigma (array-like or float) – Scattering surface roughness. 0.0 is Lambertian, 0.97 is the maximum energy-conserving roughness. 0.25-0.3 is appropriate for many planetary bodies.
- Returns:
Corrected intensity of the same shape as the input intensity
- Return type:
array-like
-
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 single-array .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.
CSV-type files will only contain 2D variable information, so the first N-1 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 non-dimension 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 CSV-type (*.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 cross-format 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 well-behaved 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 water-rich 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 well-behaved 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 (time-varying), and nfreq is the number of frequencies in the spectrum, array of lon-lat coordinates for each transit specturm, array of spatial weights for each column with the shape (ntimes,nterm) (for averaging), and the spatially-averaged transit spectrum, with shape (ntimes,nfreq). Transit radius is in km.
- Return type:
Atmosphere,numpy.ndarray,numpy.ndarray,numpy.darray,numpy.ndarray
-