A simple scheme to incorporate moisture feedback is an extension of that introduced by . The scheme is grey in the infrared so that a single optical thickness, τ, is defined for the entirety of the long-wave part spectrum and includes a parameterization of long-wave absorption by carbon dioxide, which we derived from Santa Barbara DISORT Atmospheric Radiative Transfer 60 (SBDART) output . The optical depth is calculated as a function of specific humidity, q (kg kg-1), the mixing ratio of carbon dioxide, CO2 (ppm), and pressure, such that 5dτdσ=aμ+bq+clog⁡(CO2/360). In the equation above, σ=p/p0, i.e. pressure normalized by a constant (105 Pa); a, b, and c are constants; and μ, set to 1 as default, is a scaling parameter intended to represent absorption by well-mixed gases. used a=0.8678, b=1997.9, and c=0 with their coefficients based on fitting the above equation to the long-wave optical depths of . For experiments with an albedo closer to that of Earth than was used in their idealized study (≈ 0.3 vs. ≈ 0.38), we suggest values of a=0.1627, b=1997.9, and c=0.17. However, these are easily changed by the user. In the short wave, the optical depths of may still be used, or all short-wave radiation may be assumed absorbed at the surface in the simplest case.

This scheme provides a simple tool for experiments in which only a lowest-order description of water vapour radiative feedback is required. A limitation of the above grey scheme is that in reality the long-wave absorption spectra of water vapour and carbon dioxide are far from uniform, so that the scheme captures only the very basic structure of the long-wave radiative heating. The next step up in complexity is to use two bands in the infrared, as we now describe.

To provide an intermediate option between grey radiation and a more complete description of radiative transfer, a scheme with two infrared bands and one solar band, as described in , has been incorporated into our model with some adjustments.

Atmospheric radiation models nearly always treat solar radiation and infrared radiation separately. In keeping with common usage, we will refer to models that have one solar band and one infrared band as “grey”, as they are grey in the infrared. Consistent with that, the scheme with two long-wave bands and one solar band will be referred to as a “two-band”, or a “two-plus-one band” scheme.

The most accurate radiative scheme in the current suite of options uses the multiband correlated-k Rapid Radiative Transfer Model (RRTM), described in and . (The correlated-k method, with k being the absorption coefficient, is a means to efficiently calculate radiative transfer over a broad spectral range by collecting wave number intervals with similar spectral properties and by supposing that these spectral properties are correlated from one level to another. A relatively small set of absorption coefficients can then be chosen to be representative of the absorption coefficients for all frequencies, leading to an enormous speed-up over line-by-line calculations and much better accuracy than traditional band methods that more simplistically just group together similar wave numbers.) The implementation of this scheme largely follows that of in the MiMA model, an aquaplanet model with simple topography. Within Isca the RRTM scheme may also be configured with idealized or realistic continental outlines and topography, a diurnal and seasonal cycle, or solar inputs appropriate for other planets, as may all the radiation schemes in the framework. The RRTM scheme we use was primarily developed for Earth's atmosphere or variations of it, for which it is very accurate. It allows configurable levels of CO2 and ozone, and it enables the model to produce a stratosphere and polar vortex. In principle the scheme could be recalibrated to planetary atmospheres with different compositions and host stars with different emission spectra if the appropriate spectral files (k distributions) were available.

The upper boundary of Isca may be specified by the user, and a user-configurable sponge layer and gravity-wave parameterization are available, so that with RRTM a true “high-top” model is in principle available. However, in practice such things as the breaking of gravity waves at very high altitudes may lead to numerical difficulties and such a model may not perform satisfactorily out of the box, without some experimentation by the user.

Some sample results with the various radiation schemes are shown in Fig. , which shows the long-wave cooling rate as a function of latitude and height for a given distribution of temperature and moisture, shown in Fig. . (All of these schemes may be used offline, with a Python interface, although this is not currently part of the Isca repository.) The RRTM scheme gives very similar results to the SBDART scheme (not shown) and is the most accurate of our collection for Earth parameters. With the parameters chosen, the two-band scheme is more accurate than either of the two grey schemes, although it is possible that the grey schemes could be further tuned to match the RRTM results. However, we do not regard improved accuracy as the main advantage of the two-band scheme; rather, the presence of an infrared window is a qualitative improvement over a grey scheme when more extreme climates, or other planetary atmospheres, are to be explored.

Python software is provided to create a land–sea mask, which is an array of ones and zeros defining where land is, and where it is not, respectively. Such a mask is defined on the latitude–longitude grid of the model at the specified horizontal resolution. The Python software will output this array as a NetCDF file, which the model itself will take as an input file. Options within this software for different continent shapes include using realistic continental outlines taken from the ERA-Interim invariant dataset , the simplified continental outlines similar to those of Brayshaw et al. (2009) and Sauliere et al. (2012) with or without additions such as India and Australia, and simple rectangular continents defined using latitude and longitude ranges, all easily configurable by the user. Examples of integrations with idealized and realistic continental outlines are given in Figs. , , and .

Once a land–sea mask has been created, the Isca framework has options for using this mask to alter properties of the model's mixed-layer ocean. The properties that can be altered in regions of land are the depth of the mixed layer (i.e. the heat capacity of the surface in regions of land), the surface albedo, the “evaporative resistance” of the surface, and the roughness length seen by the boundary-layer scheme. Evaporative resistance parameters (β and α) are used in the bulk formula for surface evaporation flux, E, so that 10E=ρaC|va|β(αqs*-qa). Here ρa and qa are the atmospheric density and specific humidity in the lowest model layer, and qs* is the saturation specific humidity calculated using the surface temperature (see e.g. Eq. 11 in ). The parameters β and α are chosen by the user. Typically, one of them might be unity and the other lie between 0 and 1, and such values will reduce evaporation from a region of land, as would be evident in the real world. Using α=1 and β<1 has the advantage of not allowing E to change sign from what it would have been had α=1, and this formulation is normally chosen when using the bucket model, described below. We have tested both formulations in an Earth-like control case and found the differences to be small. When β=α=1, then the evaporation is equal to the “potential evaporation”, E0=ρaC|va|(qs*-qa).

Since the dynamical core uses sigma-pressure coordinates, implementing bottom topography is straightforward, as first described by and implemented by in a similar dynamical core. Within Isca the incorporation of topography simply involves specification of a topographic field η(λ,ϑ) – that is, height as a function of longitude and latitude. The topography may be either idealized – as, for example, implemented by – or be taken from cartography in a NetCDF file. The topography used in the left-hand panel of Fig.  uses a realistic topography taken from the ECMWF interim dataset , whereas Fig.  has no topography. In any case, topographic fields are easily constructed by the user and may be applied in other planetary configurations or even over the ocean. A Python script may be used to specify topography, just as in the continental case, which writes out a NetCDF file. Various topographic configurations are already available in this script, for example Gaussian mountains at specified locations, or topographies similar to those of , and others may be constructed by the user. A flag is available to set the topographic height to be zero over the ocean if desired – without it, a Gaussian mountain over land would lead to non-zero topography over the ocean.

The user should be aware of potential inaccuracies in using steep topography in sigma coordinates , such as might be encountered on Mars (although mitigated there by the low gravity), and of potential Gibbs effects (“ringing”) when using sharp topography in a spectral model e.g.. For these reasons the topography may have to be smoothed in some instances, for which functionality is provided in Isca's Fortran code.

As an alternative to using a prescribed evaporative resistance to describe the differences in surface latent heat flux over land and ocean, a bucket model similar to that of (also used in the idealized set-ups of , and ) is included in Isca. Over land, soil hydrology is taken to be described by a bucket, which can be filled by precipitation, or emptied by evaporation. At any time the bucket depth, W, is between 0, corresponding to an empty bucket, and its field capacity, WFC, corresponding to a full bucket. When the bucket is empty there can be no evaporation, and in general evaporation is proportional to the bucket depth as a fraction of the field capacity. Bucket depth may not exceed field capacity so that when the bucket is full any net moisture flux into the bucket is treated as run-off and does not increase the bucket depth. The default field capacity over land is set as 15 cm, but this is configurable.

The equations used to describe this behaviour over land are 11adWdt=P-βE0ifW<WFCorP≤βE0dWdt=0ifW=WFCandP>βE0, where β is the parameter in Eq. (), P is precipitation, E0 is the potential evaporation, given by Eq. () with β=α=1, and where, to give one example, 11bβ=1ifW≥0.75WFCβ=W0.75WFCifW<0.75WFC. The parameters in these formulae are easily configurable and the oceans effectively have an infinite bucket depth, with β=1 at all times. Some results using a bucket model in a somewhat extreme case with a very idealized and rather large, rectangular, tropical continent are shown in Fig. .

An annually repeating climatology of SSTs must first be created. This could be from observations, or from AMIP SST data, or from some other source. Python software is provided for doing this.

Isca also includes a very simple representation of sea and land ice, primarily designed for water ice on Earth. The representation is a passive representation, meaning the ice distribution is prescribed and does not depend on any changes in atmospheric or oceanic temperature. Regions of ice and non-ice are defined using an input dataset of ice concentration (values between 0 and 1), which can be time varying or constant in time. The model's representation of ice is then binary, with a region having either ice or no ice. The regions of ice are decided using an configurable ice-concentration threshold, with values above the threshold in the input dataset considered as ice, and those below the threshold considered as having no ice.

In regions of ice, the model's surface albedo is set to an ice-albedo value, which is also an input parameter. In regions of ice that are over ocean, the ocean Q flux is set to zero with other properties of the surface remaining unchanged, with regions of land having the original land surface heat capacity and regions of ocean having the original ocean heat capacity.

Including this representation of ice is particularly advantageous over the poles during the summer season, where the high ice albedo leads to much colder, and hence more realistic, surface temperatures than if the standard land or ocean albedo is used in these regions (not shown).

Giant planet models may be configured with Isca, provided that the thickness of the modelled atmosphere is small compared to the planetary radius. For example, one relatively simple giant planet model, available as a preconfigured test case in Isca, draws from the Jupiter model described in , from which it takes a grey radiation and dry convection scheme. The bottom boundary of this case (at 3 bars) has no mixed-layer surface but energy conservation is enforced, whereby the upward thermal radiative flux is set equal to the sum of the downward solar and thermal fluxes at the surface. Also at the surface, a spatially uniform heating is added in the bottom level of the atmosphere, which is used to represent heat emanating from the planet's interior. In the test case we turn off all sources and sinks of moisture, although adding moisture is a reasonably simple extension. Instead of a boundary-layer scheme, a Rayleigh drag is applied at the model's bottom boundary to represent dissipative processes in the interior. This drag extends over all latitudes in the test case but can also be applied only over a chosen range of latitudes.

We also provide a drag formulation that can be applied at different levels within the atmosphere, rather than just at the model's bottom boundary. This is motivated by the results of , who suggest that the effects of moist convection on Jupiter can be thought of as a Rayleigh drag near the water-cloud level (∼ 1 bar in pressure), rather than the Rayleigh drag often used at the bottom boundary of many GCMs.

The equation for this drag is 13Fdrag(ϑ,λ,σ)=-r(σ)u(ϑ,λ,σ), where ϑ and λ are latitude and longitude, respectively; σ=p/psurf is the standard terrain-following σ coordinate; and r is the drag coefficient. In our formulation, this coefficient takes the form 14k(σ)=1τdmax0,σ-σtσm-σtσt<σ<σm1τdmax0,σb-σσb-σmσm<σ<σb, with σb as the lowest level at which the drag is applied, σt is the top level at which the drag is applied, and σm is the level at which the drag is maximum. Using this drag formulation, and having the drag centred at 1 bar in pressure, the model produces overturning cells that only extend from the top of the model to the level of drag at 1 bar, rather than throughout the depth of the model. A 2-D map of the vorticity at 0.5 bar, with drag centred at 1 bar, is shown in Fig. . (This configuration differs from the preconfigured test case, which has uniform drag at 3 bars, and from , who only had drag polewards of 16∘.) This model is configured entirely with name list parameters or Python dictionaries from the Isca master model, without need for recompiling. Extensions and variations of this type of model may be (and have been) configured – the addition of moisture (with a moist convection scheme appropriate for a hydrogen atmosphere), setting the lower boundary to be at a much higher pressure, different drag formulations, and so forth, and our own investigations continue.

To illustrate some of the capabilities of Isca as an idealized model of terrestrial planets other than Earth, we show the results of simulations performed with a thermal-damping forcing, first reducing the planetary rotation rate Ω (relative to Earth, Ω=ΩE) by a factor of 20, then increasing the atmospheric depth (surface pressure ps). This corresponds to moving the model in the direction of Titan and Venus: Titan's rotation rate is about 1/16 that of Earth, its diameter is about 0.4 of Earth's, and its surface pressure is 1.5 times larger; Venus has a similar radius to Earth but its rotation rate is 243 times less and its surface pressure (92 bars) is almost 2 orders of magnitude larger. Although the model we use here is highly idealized, the results do exhibit some key features of the these atmospheres.

Figure  shows the time-averaged and longitudinally averaged zonal wind for a model Earth (panel a) and for planets rotating at 1/20 the rate of Earth with surface pressures ps=1, 7.9, and 92 bars. (The first case is essentially a Held–Suarez version of Earth and the second case is similar to one in .) In the three cases with reduced rotation the circulation between the zonal jets is a Hadley cell that nearly conserves momentum in its upper branch and extends further poleward than on Earth, as expected.

The temperature forcing has the same equilibrium state Teq(θ,p) (with no diurnal or seasonal variation) in all four cases and produces a tropopause at about p=200 hPa. In case (b), there is a weakly superrotating layer at this level. For the progressively deeper simulations (panels c and d) the same number of pressure scale heights were used (in order to limit wave-breaking; other than grid-scale ∇8 hyperviscosity, the only momentum damping deployed here is the near-surface Rayleigh damping) but the top of the simulated atmosphere was still above the tropopause level. In the deeper cases, the superrotating layer is strengthened to zonal wind speeds similar at the equator to those at the core of the high-latitude jets, and these are fastest in the deepest case. Similar experiments with a zonally symmetric model (not shown) do not exhibit equatorial superrotation, as expected since eddy motion is required to create an angular momentum maximum .

There is observational evidence from both Titan and Venus to suggest a wide Hadley cell and strong superrotation aloft. For example found in Venus Express data that the zonal winds on Venus at the cloud level were approximately 60–100 m s-1 (the higher figure roughly at the tropopause level) from the equator out to about 50–60∘, and then decreased to the pole as is also seen here. They also found the peak meridional winds to be at 55∘ S; this latitude is well poleward of the Hadley cell on Earth. However, it has proven notoriously difficult to quantitatively reproduce Venusian winds, even with comprehensive Venus models, and our investigation of the parameters that determine these winds, and with more nearly Venusian parameters, will be reported elsewhere.

Within Isca it is straightforward to change orbital parameters to map out some of the possible circulation regimes that could exist on planets outside our solar system, using either the simplified or full radiative transfer schemes, or thermal relaxation. Here we show an example using the latter to model the changes in circulation as a planet passes from being tidally locked – that is, the same face is always pointed to its host star – to having a diurnal cycle, which may be of varying length. The length of the diurnal cycle, Tsol, is given by the relationship between rotation and orbital rate 15Tsol=2πΓ-Ω, where Γ=2π/Porb is the orbit rate and Ω the rotation rate of the planet. The longitude of the substellar point – equivalent to the longitude of midday on Earth, λ*, is then 16λ*(t)=2πtTsol=(Γ-Ω)t. For a tidally locked planet, orbital and rotation rate are equal and the substellar point remains fixed in time.

We have configured the thermal relaxation parameters (of the three-dimensional primitive-equation dynamical core) to a longitudinally asymmetric heating profile that moves according to Eq. (), and the planetary rotation rate and the planetary orbital rate (around its sun) are then chosen to give tidally and non-tidally locked configurations. These configurations can be made with the Python front end. Example results are shown in Fig.  for a planet that is Earth-like in size, atmospheric density, and composition. The model is run to a statistically steady state in each case with a rotation rate, Ω=10-5 s-1, that is approximately 10 times slower than Earth. The equator to pole temperature gradient of ΔT=60 K means that the external thermal Rossby number of the system is large, RoT=(RΔT)/(2Ωa)2≃100 (where R is the ideal gas constant). The tidally locked configuration shows a pattern resembling a Matsuno–Gill solution (also seen in , and ), with Rossby lobes westward and poleward of the heating, and with a maximum temperature (the hotspot) at the substellar point. Interestingly, in the non-tidally locked case the hotspot is not co-located with the substellar point and may lead or lag, as was discussed using shallow water dynamics by .

Isca is not limited to using a thermal relaxation scheme for such exoplanets; the array of parameterizations available allows for increasing levels of complexity depending on the data available and the user's preference. Isca could be configured to study a specific star–planet system using a grey or multiband radiation scheme, parameterized for the observed stellar output and atmospheric composition of the star and planet, respectively, and with topography, a continental land mass, and an ocean.

We provide various post-processing capabilities, mainly in Python, although the user would of course be free to design their own. Diagnostics available within Isca itself include Python software to interpolate model output to a higher resolution and then restart the model at higher resolution, and an interpolator to produce output on pressure levels.

Current users of Isca have constructed eddy fluxes of heat and momentum, a ray-tracing package to construct group velocities and plot ray trajectories for Rossby waves, and, of course, the software required to read the NetCDF output from the models and construct the plots in this paper, often making use of the xarray toolkit . The post-processing software is not packaged within Isca itself but some packages may be available on individual user repositories, and a community repository may be set up in future.

Although the framework is not intended to be used as a black box, we do provide a number of test cases that will run out of the box using the Python front end and with minimal configuration by the user. These include (i) the Held–Suarez test case; (ii) a dry model case using astronomically and radiatively determined thermal relaxation temperature fields, with seasons; (iii) a moist aquaplanet with grey radiation, with or without seasons; (iv) a moist aquaplanet with RRTM radiation and specified ozone, as in the MiMA model; (v) a case with a simple continent using bucket hydrology and RRTM radiation; (vi) cases with variable CO2 concentrations using either the grey or RRTM radiation schemes; (vii) a giant planet, similar to Jupiter; and (viii) cases with realistic continents with either Q fluxes or prescribed SSTs. Axisymmetric versions of some of these cases are, where sensible, also available.

We also provide a trip test, whereby following some new software implementation (e.g. a new commit on the Git repository) a suite of model tests, corresponding to many of the cases above, can automatically be performed to make sure that the new software has not introduced any unwanted behaviour and that runs are bitwise identical with previous model versions where appropriate.