1 Introduction

Our understanding of extra-solar planetary systems has grown significantly since the first exoplanet was discovered in 1995 [1]. One major aspect of this field is the analysis, exploration, and modelling of planetary atmospheres; all of which require a careful treatment of opacities. For example, atmospheric spectroscopy makes use of wavelength-dependent opacities to determine the chemical constituents of the observable part of exoplanet atmospheres. Projects such as ExoMolFootnote 1 [2], HITRANFootnote 2 [3], HITEMPFootnote 3 [4], which are dedicated to generating line-lists for spectroscopy, have contributed to our understanding of the atmospheric properties of other worlds [5,6,7,8,9,10,11,12,13]. In contrast, when theoretically modelling an exoplanetary atmosphere, opacities are used often to estimate the global temperature profile and the location of the radiative-convective boundary. This approach can use wavelength-dependent or wavelength-averaged opacities, with the former being more realistic than the latter. Although the aforementioned projects focus primarily on line-lists, they can be converted into opacity tables [14] that are more straightforward to operate with. ExoMol [15] and DACEFootnote 4 (Data and Analysis Center for Exoplanets) [16], for example, provide such conversions. Whereas wavelength-dependent opacities can be used in theoretical models, they require computationally-intensive simulations [9, 17,18,19]. It is therefore common to rely on Rosseland and Planck mean opacities (shortened to RM for the former, PM for the latter, and RPM when referring to both) that depend only on the temperature and pressure of the system. The use of RPMs has various benefits that include (1) their wavelength independence makes them simpler and faster to use, (2) they can be implemented in grey and semi-grey models to estimate the temperature structure of astrophysical and planetary environments, and (3) such modelling provides exact solutions.

Whereas we do not use grey and semi-grey approaches in this paper, it is pertinent to discuss them because they use RPMs. Grey and semi-grey models are approximate analytic solutions for radiative transfer in gaseous environments that use one (infrared) and two (infrared and visible) wavelength-averaged opacities, respectively. Grey and semi-grey models were popularised by Sir Arthur Eddington [20] in atmospheric sciences, and then expanded upon by various other authors [21,22,23,24,25,26,27,28,29,30,31,32,33]. A comprehensive analysis of grey and semi-grey models has previously been done in the literature [34], so it will not be explored in this study. With the recent launch of the JWST [35], and several upcoming astronomical missions like Ariel [36, 37] and Twinkle [38], there is a strong motivation for further exploring extra-solar planetary atmospheres. We recognise that grey and semi-grey approaches may also be used in planetary formation models [39,40,41] and engineering [42,43,44].

RPM data are not commonly produced despite the numerous advantages of grey and semi-grey approaches. This has motivated some researchers to assume constant values [32], or adopt simple analytic approximations [45]. In light of this problem, we present RAPOC, a Python program that converts wavelength-dependent opacities into RPMs.

Caveat – RAPOC is not a replacement for more rigorous radiative transfer approaches[9, 17,18,19]. It is, instead, built to provide pressure and temperature-dependent RPMs in a spectral range of choice so that grey and semi-grey models can incorporate a more realistic opacity treatment. This may increase the efficacy of such approaches, assuming that the pressure-temperature models used are appropriate approximations of reality. The authors recommend the use of more rigorous approaches instead of grey and semi-grey approximations when appropriate.

2 What is RAPOC?

RAPOC (Rosseland and Planck Opacity converter) is a fast and user-friendly Python 3 program that converts wavelength-dependent opacities into RPMs as a function of temperature and pressure for the wavelength range of choice. RPMs are given usually as a function of density and temperature (not pressure) [46, 47] because opacities are defined as kνκνρανn, where kν is the volume opacity (not further referenced in this study), κν is the mass opacity, αν is the extinction coefficient, ρ is the density, and n is the number density. ExoMol and DACE provide opacities as a function of temperature, pressure and wavelength, but not density; this is because their opacities are computed from line lists that are pressure-broadened.

More information on the input data can be found in section 2.3. RAPOC is publicly available on PypiFootnote 5, so it can be installed using the pip command

$$\$\qquad \mathrm {pip}\qquad \mathrm {install} \qquad \mathrm {rapoc}$$

or it can be compiled directly from the source, and downloaded from the GitHub repositoryFootnote 6 with

$$\$\qquad \mathbf {cd} \qquad \mathrm {Rapoc}$$
$$\$\qquad \mathrm {pip} \qquad \mathrm {install}\qquad.$$

All data generated in this paper used RAPOC version 1.0.5. This version, and all future versions, are available on the GitHub repository. For the complete and extensive RAPOC guide, refer to the software documentationFootnote 7.

2.1 Rosseland mean opacity

The Rosseland mean opacity (RM) is defined as [48]

$$\frac{1}{\kappa_{r}} = \frac{{\int}_{0}^{\infty} \kappa_{\nu}^{-1} u(\nu, T) d\nu}{{\int}_{0}^{\infty} u(\nu, T) d\nu},$$

where κν is the opacity provided by the input data at a given frequency ν, and u(ν,T) is the Planck black body derivative with respect to the temperature T. Because opacity data is not available across the entire electromagnetic spectrum, a shorter range is selected (i.e., multigroup opacities). With RAPOC, the user selects the frequency range of interest (ν1,ν2) to compute the mean opacity. Equation (1) can therefore be written as

$$\frac{1}{\kappa_{r}} \simeq \frac{{\int}_{\nu_{1}}^{\nu_{2}} \kappa_{\nu}^{-1} u(\nu, T) d\nu}{{\int}_{\nu_{1}}^{\nu_{2}} u(\nu, T) d\nu}.$$

If the wavelength-dependent opacity κv were zero at a given wavelength, (1) would be numerically undefined, causing an error. We therefore include a fail-safe correction where the zero is replaced by an arbitrarily small value, which keeps the code functional.

2.2 Planck mean opacity

The Planck mean opacity (PM) is defined as [48]

$$\kappa_{p} = \frac{{\int}_{0}^{\infty} \kappa_{\nu} B_{\nu}(T) d\nu}{{\int}_{0}^{\infty} B_{\nu}(T) d\nu},$$

where Bν(T) is the Planck black body law computed at temperature T. For the same reasons given previously, (3) is rewritten as

$$\kappa_{p} \simeq \frac{{\int}_{\nu_{1}}^{\nu_{2}} \kappa_{\nu} B_{\nu}(T) d\nu}{{\int}_{\nu_{1}}^{\nu_{2}} B_{\nu}(T) d\nu}.$$

2.3 Inputs

The first step in the code is to load the opacity data to initialise the Model class. This data can be provided as a file or in a custom-made Python dictionary format. The data must contain an opacity table with a corresponding list of pressures, temperatures, and wavenumbers (or wavelengths or frequencies) so that the opacities can be sampled.

2.3.1 Input data file

As of the writing, RAPOC accepts only ExoMol cross-sections in the TauREx format [49], and DACE opacities [16] as inputsFootnote 8.

ExoMol cross-section (TauRex format)

Raw opacity data is available for a large sample of molecules on the ExoMol websiteFootnote 9 [15, 50,51,52,53]. ExoMol data is structured as a grid of pressures, temperatures, wavenumbers, and cross-sections. By using the units module of the Astropy package [54], RAPOC attaches units to the data so that conversions are straightforward. Pressure is expressed in Pa and temperature in K by default; the wavenumber grid (expressed in 1/cm) is converted into wavelengths (μm), and frequencies (Hz). All previously mentioned information is stored in the Model class. Finally, the cross-sections contained in the ExoMol file are loaded. These are given in units of cm2/molecule, so to convert them into opacities, the mass of the molecule is retrieved using the molmass Python packageFootnote 10 and then divided through by the absorption table. After unit conversions, the opacities expressed in m2/kg are obtained. The above mentioned steps lead to a three-dimensional Numpy array [55] table of opacities with indexes corresponding to the pressure, temperature, and wavenumber grids, respectively. These are stored in the Model class under the attribute opacities.

DACE opacities

The DACE database collects line-lists produced by projects like ExoMol, HITRAN, and HITEMP, and converts them into opacities using the HELIOS-K opacity calculator [56]. The opacity data can be downloaded from the DACE database in a directory for each molecule containing the binary files. Each of these files contains the opacity as a function of the wavenumber, pressure, and temperature. DACE opacities are in units of cm2/g. RAPOC accepts the directory address as input and parses the contained files to build a three-dimensional Numpy array of opacities ordered for pressure, temperature, and wavenumber. All units are then converted into SI units and, subsequently, all of the aforementioned information is stored in the Model class.

2.3.2 Input Python dictionary

As mentioned previously, instead of an input file, the user may use a Python dictionary as the required input. The dictionary content must be of the same type as the one described for the input file because RAPOC accepts only data of a specific format. The dictionary must therefore contain the following five entries: (1) mol – a string for the molecule name, (2) pressure – an array for the pressure grid data, (3) temperature – an array for the temperature grid data, (4) wavenumber – an array for the wavenumber grid data, and (5) opacities – a three-dimensional array of the opacities (in units of area over mass) ordered by pressures, temperatures and wavenumbers. Optionally, the dictionary can contain the molecular mass, under (6) mol_mass key. RAPOC will compute this quantity automatically if this key is not present. Table 1 is a schematic representation of the dictionary structure. The RAPOC documentation contains a full description of the code.

Table 1 Input dictionary structure. A custom made Python dictionary can be used as a RAPOC input if it contains the indicated keywords

2.4 Rayleigh scattering

RAPOC includes a module for producing Rayleigh scattering RPMs for the atomic species given in Table 3 that is found in Appendix A. The Rayleigh scattering wavelength-dependent opacity is given by [57, 58],

$$k_{Ray}(\lambda) = \frac{128 \pi^{5} }{3 \mu \lambda^{4}} \cdot \alpha^{2},$$

where μ is the atomic mass expressed in SI units and α is the static average electric dipole polarisability of the gaseous species being considered, which is given in Table 3. The resulting kRay(λ) values are expressed in m2/kg and processed in the RPM modules to compute their respective mean opacities. Although the Rayleigh scattering opacity is independent of temperature, RPMs are not because of the black-body equation (or its derivative), as shown in (1) and 3. Pressure is not, however, required, so RAPOC will proceed with the calculation irrespective of whether a pressure value is given.

2.5 Estimation algorithms

The RAPOC code offers two estimation methods. For the first method, it finds the closest pressure and temperature to the input P and T in the data grid, after which it extracts the opacity data, and computes the desired mean opacity in the frequency range (or wavelength or wavenumber) of choice (i.e. ν1,ν2). Equations (2) and (4) are used to calculate the RMs or PMs respectively.

The second method consists of an interpolation of the estimated RPM values. RAPOC first produces a map by computing the model mean opacity (RM or PM with (1) or (3), respectively) at the indicated frequency band (ν1,ν2) for every pressure and temperature available in the data. To make the code faster RAPOC will not reproduce the previously generated map, unless the user changes the investigated frequency bands in a successive iteration. This map can be used to interpolate the model opacity values for given pressures and temperatures so long as they are within the bounds of the data grids. The aim of this code is to compute RPMs from given input data in a reliable and efficient manner, so extrapolation methods are not implemented in RAPOC. Hence, inserting an input pressure or temperature outside the input data range will result in an error. The interpolation is handled by the Scipy griddata module [59] using the linear mode described in the documentation. RAPOC also has a loglinear mode because the input pressure data may range over several orders of magnitude. This mode is similar to the linear mode except for the pressure being in a logarithmic form when the interpolation is made. We stress that the Scipy griddata algorithms should be used carefully as the quality of the interpolation is dependent on the local environment as well as the mode requested, so unphysical estimations may occur. Both estimation algorithms allow the user to compute the RPMs for a single input pressure and temperature or a grid, by giving a list of pressures and temperatures as inputs.

2.6 Outputs

Examples of possible outputs are shown in Table 2 for ExoMol water [52] and carbon dioxide [60] data, using the linear method. Figure 1 shows the RPM values estimated by RAPOC when compared to the input opacity as a function of wavelength, temperature, and pressure. Using RAPOC, one can generate a map of RMs and PMs for each combination of pressure and temperature available in the input data; examples of these maps are shown in Figs. 2 and 3. The two figures demonstrate that opacities do not usually have a monotonic behaviour in their respective pressure and temperature grids. By comparing Figs. 2 with 3, one sees that the estimated opacities are strongly dependent on the wavelength range considered.

Table 2 RPMs estimated by RAPOC for different temperatures and pressures in the 1-50 μm wavelength range for water and methane using ExoMol data. This estimation has been performed using the linear method
Fig. 1
figure 1

The mean opacities computed by RAPOC for four different cases. In each panel the grey line represents the input data opacities (ExoMol) with their corresponding pressures and temperatures in the given wavelength range. The blue and red lines are the computed RMs and PMs, respectively. These have been estimated with the closest method. In the top row, the opacities of water are shown, whereas the bottom row is for methane. The right column shows the results for P = 0.001 bar and T = 500 K, while the left row shows the equivalent for P = 1 bar and T = 1000 K. In all of the panels the wavelength range is 1 - 50 μm

Fig. 2
figure 2

Opacity map produced with RAPOC for H2O[52] (top row) and CO2[60] (bottom row) over the 1-50 μm range using ExoMol input data. RMs are reported on the left column whereas PMs are reported on the right column

Fig. 3
figure 3

Opacities map produced with RAPOC for H2O[52] over the 0.38-1 μm range from ExoMol input data. RMs are reported on the left whereas PMs are reported on the right

3 Discussion

3.1 Other Rosseland & Planck Opacity Sources

There are various resources for RPMs in the literature, though most focus on primordial gas mixtures with different metallicities [47, 48, 61,62,63,64,65,66]. Whereas the values of mixtures are useful for modelling planetary formation or stellar interiors, they are not as applicable to planetary atmospheres. We therefore mention only papers providing RPMs for individual molecules because they allow for a straightforward comparison with the RPM values provided by RAPOC. Most of the individual molecule RPM values present in the literature are estimated directly from line-lists [45, 67]. RAPOC instead uses precomputed opacities for single molecules to estimate their wavelength-averaged values, allowing for faster computations, and a straightforward integration into other codes. RAPOC therefore relies on precomputed data, such as by ExoMol and DACE data, instead of line lists. The user must manually account for the contributions of the individual species calculated by RAPOC if the opacities of a gas mixture are required. In the following, we compare the estimates obtained by RAPOC with others found in the literature.

We compare our RPM opacity estimations for water vapor with those of Hottel [68], Abu-Romia & Tien [69], and Kurosaki et al. [45]. Hottel estimated the IR Planck mean opacities from emissivity data, whereas Abu-Romia & Tien found IR RPMs from spectral data using selected bands in the 2.7 − 20 μm range, which contribute appreciably to the emitted energy. Kurosaki et al., however, produces a monotonic power-law fit (their Eqs. A.5–8) for estimating water RPMs in the visible and thermal wavelengths using HITRAN data. The power-law approximation presented in Kurosaki et al. has been tuned for two wavelength ranges: visible (0.4− 0.7 μm) and thermal (0.7−100 μm). For a comparison with RAPOC, we estimate RPMs with 0.4−0.7μm and 0.7−50 μm wavelength ranges for the visible and thermal bands respectively (see Fig. 4). We only show Kurosaki et al. for the visible range because Abu-Romia & Tien and Hottel only provide results for the IR range. We are aware that for simple molecules such as H2 that are weakly absorbing in the infrared and visible wavelengths, the collisional absorption may be crudely approximately by a power law as a function of pressure and temperature. However, as soon as a hydrogen gas is slightly enriched by other molecules, the power-law approximation begins to fail [65, 66]. In addition, for molecules like H2O and CO2, there are other sources of opacity such as electronic transitions, molecular rotations, and vibrations, meaning that the opacity is not at all monotonic. The model by Kurosaki et al. is therefore inappropriate for predicts opacities, explaining why its values differ by up to five orders of magnitude from those of RAPOC. Figure 4 shows Kurosaki et al. predicting opacity values that are significantly greater than the wavelength-dependent values of ExoMol.

Fig. 4
figure 4

Comparison between Kurosaki et al. [45], Abu-Romia & Tien [69], Hottel [68] and RAPOC. The shaded lines in both plots represent the raw data loaded from ExoMol’s water opacities [52]. The blue lines are Rosseland Mean Opacities with the filled lines being from Kurosaki et al., the dash-dotted line from Abu-Romia & Tien, and the dashed lines from RAPOC. The red lines are Planck Mean Opacities with the filled lines being from Kurosaki et al., the dash-dotted line from Abu-Romia & Tien, the dash-dot-dotted line from Hottel, and the dashed lines from RAPOC. The black dotted line is the median value of the raw wavelength dependent opacities. The left panel is for the visible wavelength range (0.3 to 0.7 μm) and right panel is for the IR wavelength range (0.7 to 50 μm). Both panels use the same pressure (1.01325 bar) and temperature (1500 K)

As mentioned previously, Abu-Romia & Tien and Hottel results are applicable only to the IR range. The data reported in Abu-Romia & Tien [69] are displayed in figures with temperature on the x-axis (in units of Rankine) and opacity (in inverse feet) in the y-axis. We convert their estimates by dividing their opacities by the local gas density, which is estimated using the ideal gas equation

$$\rho = \frac{M P}{R T},$$

where M is the molar mass of the gas (\(M_{H_2O} = 18.01528 \, g/mol\) for water), P is the pressure, R is the ideal gas constant, and T is the temperature. Figure 4 shows that RAPOC’s Planck Mean Opacity estimate is compatible with the value reported in Abu-Romia & Tien and Hottel. The Rosseland Mean Opacity given by Abu-Romia & Tien is, however, several orders of magnitudes larger than the value estimated by Kurosaki et al. and RAPOC.

Regarding CO2, we compare the Planck opacities calculated by RAPOC with those given in Abu-Romia & Tien [69] and Hottel [68]; the Rosseland opacities are compared to those of Badescu [67]. The comparison for the PM is shown in Fig. 5, where the Planck opacities are given for three different temperatures. The opacities from Abu-Romia & Tien [69] were extracted from their graphs, as described previously, but by using the molar mass of carbon dioxide \(M_{CO_2} = 44.01 \, g/mol\). As shown in Fig 5, the RAPOC Planck opacities are consistent with those of Abu-Romia & Tien and Hottel.

Fig. 5
figure 5

Comparison between Abu-Romia & Tien [69], Hottel [68] and RAPOC. The shaded lines in all plots represent the raw data loaded from ExoMol’s carbon dioxide opacities [60]. The blue lines are Rosseland Mean Opacities with the dash-dotted lines being from Abu-Romia & Tien, and the dashed lines from RAPOC . The red lines are Planck Mean Opacities with the dash-dot-dotted lines being from Hottel, the dash-dotted lines from Abu-Romia & Tien, and the dashed being from RAPOC. The black dotted line is the median value of the raw wavelength dependent opacities. The three panels refer to different gas temperatures: right is for T = 1500 K, centre is for T = 2000 K, and right is for T = 2500 K. All panels use the same pressure (1.01325 bar)

For the Rosseland mean opacities, Table 6 of Badescu [67] is considered. In their calculation, a wavelength range of 0.5 μm to 100 μm was used, which is beyond the limit provided by ExoMol data [60]. Hence, a wavelength range of 0.5 μm to 50 μm will be adopted when making the comparison. The results are shown in the first row of Fig. 6. The figure shows that Badescu’s estimates are closer to the median value of the wavelength dependent opacities from ExoMol than what RAPOC calculates. The bottom row of the same figure reports the same estimates performed on the 5−10 μm wavelength range. A major advantage of the RAPOC code is that the wavelength range can be defined, whereas using Badescu’s values are given for a set wavelength range.

Fig. 6
figure 6

Comparison between Badescu [67] and RAPOC estimates. The shaded lines in all plots represent the raw data loaded from ExoMol’s carbon dioxide opacities [60]. The blue lines are Rosseland Mean Opacities with the filled lines from Badescu and the dashed lines from RAPOC. The red dashed lines are RAPOC’s Planck Mean opacities, and the black dotted lines are the median value of the raw wavelength dependent opacities. The left column is for low pressure (567⋅10− 3 bar) and the right column is for high pressure (11.467 bar); both columns use the same temperature (300 K). The wavelength range is different in the two rows as the top row uses 0.5 to 50 μm range, while the bottom row uses 5 to 10 μm

For water and carbon dioxide, there are significant differences between the RPMs given by RAPOC and those available in the literature; the only exception being the Planck mean opacities that are consistent with those of Abu-Romia & Tien [69] and Hottel [68]. These differences are the result of the different wavelength ranges investigated, and the adoption of simple analytic approximations, such as the power-law fit of Kurosaki et al. [45]. The major advantage of RAPOC is that it provides a flexible and systematic avenue for calculating RPMs with widely available input data. This flexibility couples with RAPOC’s ability to better represent the weighted mean opacity of a gaseous species at a given spectral window, or across a large range than the other approaches in the literature. Despite these advantages, RAPOC is dependent on the input data (excluding the Rayleigh scattering opacities), so it cannot extrapolate outside the given wavelength, temperature, and pressure ranges.

3.2 Limitations with Rosseland and planck mean opacities

The use of RPMs is limited and situational. For instance, in optically-thin environments, RPMs may overestimate the opacities present as photons could traverse through spectral windows, which might be very different from a few strong opacity regions. Furthermore, RM and PM have different functional forms corresponding to the different averages they are providing. The RM opacity uses the derivative of the Planck distribution as the weighting function, which it then uses to find the harmonic mean of the opacity. Consequently, RMs are extremely sensitive to the opacity minima and can provide erroneous values if a molecule is fully transparent at a given wavelength. Conversely, PM opacity uses the Planck function as the weighting function and then finds the arithmetic mean, so it is strongly affected by the more opaque regions of the spectrum. Due to their different averaging approaches, RM and PM opacities can differ by over two orders of magnitude which, depending on thermodynamic properties of the system, could lead to substantially different temperature profiles.

4 Summary and conclusion

In this paper we present the RAPOC code that can convert wavelength-dependent opacity data into Rosseland and Planck mean opacities (RPMs) in an efficient manner. Our code is fully written in Python and publicly available on GitHub and Pypi. RAPOC uses ExoMol and DACE data, but user-defined data can also be used as an input so long as it is in a readable format. By incorporating the pressure and temperature dependence of RPMs, RAPOC provides a more complex treatment of the mean opacities than what is sometimes used in the literature, notably, assuming constant values or adopting simple analytic formulations. RPMs have several benefits, such as allowing for the use of grey or semi-grey models when analysing gaseous environments, which are simpler and have exact solutions. We note that RAPOC should not be used as an alternative to more thorough approaches, such as those using wavelength-dependent opacities. However, for simpler models, RAPOC provides a prescription for evaluating wavelength-dependent opacities, which can be used for exploring a larger parameter space, as well as benchmark testing.