Reference

Model(atdb, coheat; abundances=:xdef, multiplier=Dict(), exclude=(3, 4, 5), cfrac=0.0)

The gas of a run: the elements of the atomic database file atdb (atdb.fits) with the abundance table abundances (a name of composition, or a table of the elements 1 to 30), their multipliers (Dict(Z => factor), XSTAR's habund, heabund, ...), without the elements excluded (Li, Be and B, which the atomic data of XSTAR does not have), and the processes of the gas that do not depend on the levels (standard_processes) with the Compton table coheat (coheat.dat) and the covering fraction cfrac. Model(records, compton; ...) takes the loaded database and the Compton table. slab(model; ...) runs it and tables(model, run) makes its results into arrays. The fields are mixture, processes and ion_labels.

slab(mixture, processes; density, column, logξ, luminosity, α=-1.0, spectrum=(E, L) -> powerlaw(E, α, L), ncn2=999, kw...)
slab(mixture, processes; pressure, column, logξ, luminosity, ...)
slab(mixture, processes; density, radexp, ...)
slab(mixture, processes; density=DensityTable(path), column, luminosity, ...)

A slab of gas of the density (cm⁻³) at the source distance, constant or density (r/r₀)^radexp for radexp ≠ 0 (XSTAR's radexp), or a DensityTable (or the path of its file: XSTAR's radexp < -99, whose zones are at the distances of the table, the first at r[1] and logξ not needed), or the constant pressure (dyn cm⁻², ConstantPressure, XSTAR's lcpres=1: the density of each zone is P/(k T) at its temperature, logξ is then the logarithm of the ionization parameter of the pressure Ξ) and hydrogen column column (cm⁻²) illuminated by the power-law source powerlaw(E, α, luminosity) (erg s⁻¹) on XSTAR's energy grid of ncn2 points (or the spectrum spectrum(E, luminosity), e.g. (E, L) -> blackbody(E, 0.5, L)), at the distance where the ionization parameter is 10^logξ (source_distance): the run of XSTAR with spectrum=pow trad=α that iterate solves (its keywords T and xee of the first zone, equilibrium, emult, taumax, steps (nsteps), vturb, lines, ... go to it). Returns what iterate does and the energies E, the incident spectrum incident, the distance r and the transmitted spectrum of XSTAR's output, incident × exp(-dpthcont).

tables(model, run; min_fraction=1e-15)

The results of slab(model; ...) as Results, four tables (their fields), each a named tuple of columns (vectors; units below):

• zones: one row for each zone (the state at its inner edge): zone, radius (cm), depth (cm, of the inner edge from the first), thickness (cm), ion_parameter (L/(n r²)), x_e, n_h and n_e (cm⁻³), pressure (dyn cm⁻²), temperature (10⁴ K), heating and cooling (erg cm⁻³ s⁻¹), heat_error (relative) and the fraction of every ion, named by its label (h_i, he_ii, ..., with the bare nuclei);
• spectrum: for each energy, energy (eV), incident, transmitted (with the continuum opacity: the transmitted column of XSTAR's xout_cont1), transmitted_lines (with the lines and free-free too, as the spectrum is attenuated along the slab: the transmitted column of xout_spect1), emit_inward and emit_outward (the diffuse emission of the continuum, summed over the zones: xout_cont1), diffuse_inward and diffuse_outward (the same with the opacity of the lines) and lines_inward and lines_outward (the emission of the lines, binned: binemis; binned=false skips it), all in erg s⁻¹ erg⁻¹. The emission of xout_spect1 is diffuse + lines;
• lines: the lines (rate type 4) with more than min_fraction of the luminosity of the source or a depth: ion, lower, upper (labels of the levels), wavelength (Å), emit_inward and emit_outward (erg s⁻¹), depth_inward and depth_outward (at the centre of the line);
• edges: the same for the recombination continua (rate type 7), with the threshold energy (eV) in place of the wavelength.

inward is the first direction of the escape probabilities (XSTAR's emit_inward). Arrays only: write(path, results) writes them to one file.

ConstantPressure(P)

The hydrogen density at the constant pressure P (dyn cm⁻²), as a function of the temperature T (10⁴ K): P/(1.38×10⁻¹² T) (XSTAR's lcpres=1, in which the pressure is that of the hydrogen, n_H k T).

DensityTable(r, n)
DensityTable(path)

The hydrogen density n (cm⁻³) at the distances r (cm, not decreasing) from the source, XSTAR's density file (radexp < -99, density.dat): a line of r n for each zone. path is such a file (the numbers separated by blanks or commas). The zones of iterate are at the distances of the table (the first is at r[1], the others as far apart as the table says), with its densities: gas_density(d, T, r) interpolates linearly in between.

composition(name=:xdef)

The abundances relative to hydrogen of the elements H (1) to Zn (30) of an abundance table of XSTAR (abundtbl): :xdef (the default), :angr (Anders & Grevesse 1989), :aspl (Asplund et al. 2009), :feld (Feldman 1992), :aneb (Anders & Ebihara 1982), :grsa (Grevesse & Sauval 1998), :wilm (Wilms et al. 2000, with 0 for the elements it does not have), :lodd (Lodders 2003) and :lgpp, :lgps (Lodders et al. 2009).

powerlaw(E, α, luminosity)

The spectrum E^α on the energy grid E (eV) with the luminosity luminosity (erg s⁻¹) between 13.6 eV and 13.6 keV, in erg s⁻¹ erg⁻¹ (XSTAR's ispec4 followed by ispecgg, the pow spectrum with trad = α): E^α above 0.01 eV and 10⁻²⁴ below, normalized to the luminosity in the bins nbin(13.6 eV) to nbin(13.6 keV) and then again in the bins of the energies in the range.

blackbody(E, T, luminosity)

The spectrum of a black body of the temperature T (10⁷ K, XSTAR's trad of spectrum=bbody) with the luminosity luminosity (erg s⁻¹) between 13.6 eV and 13.6 keV (starf and ispecgg): E³/(e^x - 1) with x = E/kT and 1/kT = 1.16×10⁻³/T eV⁻¹, its limit E³/x below x = 10⁻³, and the 'tail' 1/E above x = 150 (for the luminosity 1: starf is called with it and ispecgg sets the luminosity). The bins at exactly x = 150 are 0.

thermal(E, T, luminosity)

The spectrum e^{-E/kT} of thermal bremsstrahlung (spectrum=brems, ispec) with kT = 861.707 T eV, T being the temperature in 10⁷ K, and the luminosity luminosity (erg s⁻¹) between 13.6 eV and 13.6 keV.

tabulated(E, table_E, table_F, luminosity; units=:energy)

The spectrum of a table (spectrum=file, ispecg) on the grid E (eV): the table table_F at the energies table_E (ascending, in the units units: :energy (erg s⁻¹ erg⁻¹), :photons (multiplied by the energy, as rread1 does) or :log10) is interpolated linearly in the logarithms of both, 0 outside it, and normalized to the luminosity (erg s⁻¹) between 13.6 eV and 13.6 keV and then by ispecgg.

Atom(label, i1-i8, mass, Eion)

AtomicLevel

A level of an ion in the atomic database (XSTAR data type 6): its quantum numbers (n, spin_mult, L), the atomic number Z, the indices of the level and its ion, the energy E (eV), the statistical weight g, the effective quantum number n_eff and the ionization energy E_inf of the level (eV).

AtomicLine

A radiative line of the atomic database (XSTAR data type 4): the transition between a lower and an upper level, the wavelength λ, the oscillator strength f and the Einstein A (s⁻¹).

Levels

The atomic data the rates need besides their own coefficients: the levels of every ion (energies, weights and quantum numbers, as AtomicLevels keyed by (ion, level)), the number of levels of each ion (nlevels: the highest index, the continuum level) and the atomic mass of the element of each ion (weight). It behaves as the dictionary of levels. load builds one and passes it to the constructor of every rate that needs it (the field levels).

levels(records; masses=Dict())

The Levels of a loaded database (or any collection of records): the AtomicLevel records, the Fe UTA levels (AtomicLevelFe, which hold only the energy and the weight, added as AtomicLevels with zero quantum numbers unless the level is already there), and the atomic masses of the ions from the Atom and Ion records. masses (ion => mass) adds to or replaces those.

counts(levels)

Dictionary ion => number of levels (the highest level index, the continuum level) from a levels.

nlevels(levels, ion)

The number of levels of ion in a Levels: its highest level index, the continuum level.

weight(levels, ion)

The atomic mass (amu) of the element of ion in a Levels.

load(io::IO)
load(Compton, io::IO)
load(Compton, path)

The records of the atomic database of XSTAR (atdb.fits) read from the stream io: the levels, lines, photoionization cross sections and the other rate types, as the vector of records that Model builds the gas from. With Compton as the first argument it reads the table of the Compton heating and cooling (coheat.dat) instead, from a stream or a file.

Radiation(E, F)

Photon energy grid E (eV, geometrically spaced; XSTAR's epi) and the incident spectrum F on it (XSTAR's bremsa, erg s⁻¹ cm⁻² erg⁻¹). The photoionization rates integrate cross sections over it. Fint (XSTAR's bremsint) is the flux integrated from each bin to the top of the grid, in erg.

F is 4π times the mean intensity J of the radiation field at the point (the rates depend on the radiation only through J, whatever the geometry that produced it): see Radiation(E; J), mean_intensity and point_source. The energy grid is shared, not copied, when E is a Vector, so the radiation of every cell of a grid can use the same E.

Opacity([R=Float64,] n)

Continuum opacity arrays on a grid of n energies that the photoionization rates add to when given as opacity=: total (XSTAR opakc, cm⁻¹), continuum (opakcont, lines excluded) and emissivity (rccemis, 2 × n, recombination continuum emissivities in and out). R is the element type: use the type of the temperature when differentiating the rates with ForwardDiff.

Constants

The physical constants and the derived combinations the rates use, in the units of the rates (cgs, eV, Å, K). Constants() (or Constants(PhysicalConstants.CODATA2018), ...) evaluates them from a CODATA set of PhysicalConstants.jl, Constants(K; kT_eV=...) copies K with some fields changed, ucalc() has the rounded values written in XSTAR's source.

ucalc rounds the same constant differently in different routines (its k is 8.617e-5, 0.861707e-4 and 1.38066e-16 in places), so some physical constants have more than one field, one per use; they are equal for CODATA. Fields:

• ergsev erg per eV, with ergsev_bremsint (the spectrum integral) and ergsev_decay (type 71) variants.
• kB_cgs (erg K⁻¹), kB_szirc, kB_eV (eV K⁻¹), kB_keV (keV K⁻¹) and kT_eV (k × 10⁴ K, in eV): Boltzmann's constant.
• Ry_eV (hcR∞), Ry_eV_single (ucalc's single-precision literal), Ry_eV_coarse (the 13.6 eV that ucalc writes in several places for the hydrogen ionization energy and the Rydberg), Ry_erg and Ry_erg_szirc.
• hc_eVÅ (eV Å) with hc_eVÅ_single, hc_over_k (Å K) and T_floor_coeff (K Å; the collision rates use a temperature of at least T_floor_coeff/λ, i.e. ΔE/50k).
• Ry_K, Ry_K_erc, Ry_K_cb (the Rydberg over k, in K), eV_K (eV/k in K), inv_kB (K erg⁻¹).
• invcm_per_eV (cm⁻¹ of 1 eV), Rinf_invcm (cm⁻¹).
• fourpi, eightpi and pi_pexs: 4π and 8π (the normalization of the spectrum in the photoionization integrals) and π (the resonance profiles of type 85). These are mathematical constants, not CODATA, but ucalc rounds them (12.56, 25.3 and 3.14159).
• Coefficients that are combinations of constants in XSTAR's source: bb_coeff (1/(h³c²), eV⁻³ s⁻¹ cm⁻²), fo_saha (saha_coeff × 8π with T in 10⁴ K), saha_coeff_cb and saha_ci (the same factor in the ionization of types 57 and 95, the latter for T in 10⁴ K), A_to_f (1/(8π² re c) in Ų s⁻¹), `milnecoeff(4π/((2π m_e)^{3/2} c²) × Mb, cgs),gordonA(the hydrogenic dipole rate, (2π/3) α³ c R∞ s⁻¹ with the reduced mass of hydrogen),psalfa(m_e/2k),pspd(the Debye length coefficient (k/(4π α ħ c))^{1/2}),RyKsz(Ry/k in the Simpson-Zhang excitation)szratecoeffandupscoeff(the Maxwellian rate coefficient with T in K, in two uses),RyKsat(Ry/k in the satellite fit of type 73),RyperK(k in Rydberg per K, the scaled temperature of types 60 and 62) andeVKls` (eV/k in the fits of types 66 and 69).
• single_expint: round the coefficients of the exponential-integral fit (expint) to single precision, as ucalc does (it assigns single-precision literals to its double-precision variables). The effect is ~1e-7 but the fits of types 66 and 69 amplify it by y²/2, up to 1e-4. false for CODATA. and thermal_bohr (π a₀² (8k/(π mₑ))^{1/2}, cm³ s⁻¹ K^{-1/2}).
• proton_mass in electron masses, light_speed (cm s⁻¹), line_xsec (π e²/(me c), cm² Hz), `thermalspeed(cm s⁻¹ of an atom of 1 amu at 10⁴ K),collisionratecoeff(Maxwellian Υ rate coefficient for T in 10⁴ K, cm³ s⁻¹),sahacoeff(cm³ K^{3/2}),sigmathomson(cm², the Compton heating and cooling)electronresteV(m_e c², eV), and the free-free coefficientsffabsorptioncoeff(4 e⁶ h² /(3 mₑ c) (2π/(3 k mₑ))^{1/2}, the absorptionffabsorptioncoeff/(√T E³)per electron and per ion for the energyEin eV andTin 10⁴ K, Gaunt factor 1) andffemissioncoeff(32π e⁶/(3 mₑ c³ h) (2π/(3 k mₑ))^{1/2}, the emissivity per ergffemissioncoeff e^{-E/kT}/√T), withe² = α ħ c`.

constants()

The set of constants the rates are using (CODATA 2022 unless changed).

constants(f, K::Constants)

Call f() with K as the constants of the rates, restoring the previous set afterwards.

constants!(K::Constants)

Make K the constants of all the rates, e.g. constants!(Constants(PhysicalConstants.CODATA2018)). Returns K. This is global state: use constants for a temporary change.

ucalc()

The values XSTAR's ucalc uses, rounded and not always consistent with each other. Reproduces its numbers to about 1e-6; see constants.

AbstractContinuum

A process of the gas, with the coefficients (functions of the photon energies E (eV) or of a Radiation, and the temperature T in 10⁴ K)

α(process, E, T)       # absorption
σ(process, E, T)       # scattering
j(process, E, T)       # emission

per unit of the density density(process, nₑ) of what absorbs, emits or scatters; the opacity (cm⁻¹) is opacity(process, E, T, nₑ), the density times α + σ. A process is an AbstractAbsorption (free-free), an AbstractScattering (Thomson and Compton) or emits (bremsstrahlung); the scatterers are the part of the opacity that is in the continuum opacity opakcont as well as the total. The heating and cooling (erg cm⁻³ s⁻¹) in the radiation field at the electron density nₑ derive from the coefficients: heating(process, radiation, T, nₑ), cooling(...) and heating_cooling(...) for both. What a process does not have is 0.

• FreeFree(): absorption α per electron and per ion (cm⁵; density nₑ nᵢ, nᵢ = 1.4 nₑ): heats the gas and has an opacity (freef);
• Bremsstrahlung(): the emission j of the free-free process, per electron and per ion: cools the gas (bremem, integrated by heatf);
• Thomson(cfrac=0.0): scattering σ = σ_T (1 - cfrac) (cm², per electron) for the covering fraction cfrac: an opacity only;
• Compton(Te, Eph, Es): Compton scattering with the energy it exchanges between the radiation and the electrons, from the table of XSTAR's coheat.dat (load(Compton, path)): heating and cooling (comp2, cmpfnc).

standard_processes(compton; cfrac) makes the four of a run of XSTAR.

AbstractRate

All specific rates are subtypes of AbstractRate.

Every rate implements the same interface:

rate(coef::AbstractRate, cell::Cell; index=false)

Every keyword has a default: the rates that need atomic data besides their own coefficients (level energies and weights, the number of levels of the ion, the atomic mass of its element) read it from the levels field of the coefficient, a Levels that load passes to the constructor of each record (a coefficient made by hand takes it as its last argument), and the photoionization rates see no radiation (NO_RADIATION) unless given a radiation= field.

and returns a NamedTuple (; init, final, frate, irate), where init and final are the levels connected by the transition, frate is the forward rate and irate the inverse rate (0 when the rate has no inverse). With index=true only the connectivity is wanted and the rates are returned as 0.

Compton(Te, Eph, Es)

Compton scattering with the table of the Compton heating (XSTAR's coheat.dat, read by load(Compton, path_or_io)): Es[i, j] at the electron temperature Te[i] (in electron rest masses) and the photon energy Eph[j] (in electron rest masses).

• σ(compton, Eph::Real, Te::Real) is XSTAR's cmpfnc: the Compton function at the photon energy Eph and the electron temperature Te (both in electron rest masses), interpolated linearly in the table (its limit 4 Te - Eph below an energy of compton_Eph_min);
• σ(compton, E, T) is the scattering cross section, σ_T, and heating(compton, E, T) and cooling(compton, E, T) those of the energy exchanged per electron, σ_T E/mc² and σ_T (cmpfnc + E/mc²), whose integrals over the radiation are the Compton heating and cooling;
• integral(compton, radiation, T) is XSTAR's comp2: (cmp1, cmp2), the heating being cmp1 nₑ and the cooling kT cmp2 nₑ (eV, times erg per eV).

The scattering opacity is that of Thomson: density(compton, nₑ) is 0.

Continuum(mixture, processes; nrank=rank_per_bin, lfast=photoionization_lfast, vturb=default_turbulence)

The continuum opacity of the gas of mixture (cm⁻¹), as calc_emis_all makes it. Its opacity,

opacity(continuum, balance, T, ntot, radiation, edges; emissivities=nothing, escape=nothing, cfrac=0.0)

of the zone whose balance (from ionization_balance) is at the temperature T (10⁴ K) and hydrogen density ntot, on the energy grid of radiation: the opacity of each of the processes (standard_processes: Thomson scattering and free-free absorption, the processes times their densities; the scatterers (AbstractScattering) are in continuum as well as in total) and the photoionization opacity of the records. edges are the edge opacities of the records (record_opacities), which rank them: as rlbin does, only the nrank strongest edges of each energy bin (by the edge energy of rank_energy) enter, and every record of rate type 42. With the emissivities of the lines (line_emissivities) the lines are put in the bins too, as linopac does (add_line!): the nrank strongest lines of each bin, by their emissivity, enter. The recombination continua are emitted in the two directions with the escape probabilities of the depths of their edges (escape_probabilities; without them they are optically thin) and the damped photoionization with cfrac.

Returns (; total, continuum, emissivity, bremsstrahlung, edges): the two arrays of the opacity, emissivity (rccemis, 2 × n, per steradian: the recombination continua of the records called), bremsstrahlung (brcems: the emissivity of the processes, in all directions) and the number of records called.

Elements(rates, levels, ions)
Elements(records, levels, Z)

The structure of the level balance of an element: what does not depend on the gas, on the radiation or on the position, and so is built once and shared by all cells of a grid. ions are the ion indices of the element from the neutral up and rates[k] the records of ions[k] (see ion_rates); the second form takes them from the database records (element_ions, ion_rates) for the element of atomic number Z.

The ions are stacked as in XSTAR: the last level of an ion (its continuum) is the first level of the next, so the unknowns are the nlevels - 1 levels of each ion and the bare nucleus last (N in all), and a photoionization that leaves the next ion in an excited level has a final beyond the last level of its ion. For each record the layout holds the matrix entries it feeds (lo and up, the global indices of its lower and upper level, 0 if it does not enter) and whether it keeps its forward rate (zero_forward), found from the connectivity of the record (index=true) and the energies of the levels.

Ion(label, Zp, Z, N, E)

Luminosities(mixture)

The luminosity that the lines (rate type 4) and the recombination edges (rate type 7) of every record of every element add to the spectrum along the slab (XSTAR's elum and elumab, the emit_inward and emit_outward of xout_lines1.fits and xout_rrc1.fits, in units of 10³⁸ erg s⁻¹), as vectors of pairs aligned with mixture.elements[k].rates. add_luminosities! adds the zones.

Mixture(records, levels; abundances=nothing, multiplier=Dict())

The elements of the database records (an Elements for each Atom record) with their abundances relative to hydrogen, the abundance of the record (or abundances[Z], a table of the elements 1 to 30 such as composition(:angr)) times multiplier[Z] (1 if missing; XSTAR's habund, heabund, ...). Elements whose abundance is below minimum_abundance (0 for instance) are left out, as in XSTAR. levels is levels(records).

OpticalDepths(mixture)

The optical depths of the lines (rate types 4 and 9, at their centres, XSTAR's tau0) and of the recombination edges (rate type 7, tauc) of every record of every element of mixture, in the inward (inward, XSTAR's first direction) and the outward direction, in vectors aligned with mixture.elements[k].rates. They start at 0 and add_zone! accumulates them.

Parent(ion, level)

The parent ion (the N-1 electron ion left behind by photoionization or autoionization, or recombined from) and the level it is left in. ion is 0 when the data do not give the parent ion (ChargeExHe, PhotoionizeDamp, AutoionizeSat).

PowerLawDensity(n0, r0, exponent)

The hydrogen density n0 (r/r0)^exponent at the distance r of the source (XSTAR's radexp, for the constant density option): gas_density(d, T, r); without r it is n0.

Results

The tables of a run (tables): the fields zones, spectrum, lines and edges are named tuples of columns. write(path, results) writes them to one FITS file.

Transition(lower, upper)

Lower and upper level indices of a bound-bound transition within one ion.

Transmitted(L)

The spectrum that passes through the zones of a slab and the diffuse emission that they add: XSTAR's zrems. L is the spectrum (erg s⁻¹ erg⁻¹) of the source of the zones, which the zones attenuate and the emission adds to; inward and outward (XSTAR's zrems(2) and zrems(3): the emission in the direction of the first and second escape probability of each zone, summed over the zones) and inward_continuum and outward_continuum (zrems(4) and zrems(5), which are the emission columns of the output of XSTAR) have the same units and start at 0. The attenuation and the emission of a zone are added by transmit.

iterate(mixture, ntot, processes, E, L; r, column, emult=0.75, taumax=5.0, ectt=1.0, steps=2, kw...)

The zones of a slab of the hydrogen column density column (cm⁻²) and the constant density ntot (cm⁻³) starting at the distance r (cm) of the source, with the thickness of the zones chosen as XSTAR's step does, and each solved as in iterate (to which kw goes). The first zone has no thickness. The thickness of each of the others is the smallest of r/steps, the column that is left and emult/κ for the bins above ectt eV whose depth dpthc before the zone is not above taumax and whose spectrum is above 10⁻¹² (in 10³⁸ erg s⁻¹ erg⁻¹), with κ the opacity of the zone before (lines included). The zones go on while the column of those so far is below column. Returns what iterate does.

iterate(mixture, ntot, processes, E, L, zones; T=100.0, equilibrium=false, xee=1.0, cfrac=0.0, attenuate=true, diffuse=true, lines=true, vturb=default_turbulence, kw...)

The zones of a slab, one after the other, for a point source of the spectrum L (erg s⁻¹ erg⁻¹, 10³⁸ erg/s × the XSTAR file) on the energy grid E: zones is a vector of (r, Δr), the distance of the zone from the source and its thickness (cm) (or a function of the results, dpthc and Transmitted so far that gives the next, iterate), each solved at its own radius with the radiation of the incident spectrum attenuated by the continuum depth of the zones before it, exp(-dpthc) (XSTAR's trnfrc) and mapped (map_spectrum), and with the escape probabilities of the lines and recombination edges that the optical depths of those zones give. With equilibrium=true the temperature of each is the thermal equilibrium (thermal_equilibrium, from T and the xee of the previous zone), otherwise T is kept and the electron fraction iterated (ionization_balance). attenuate=false leaves the spectrum as it is; lines=false leaves the lines out of the continuum opacity (add_line!), luminous=false does not add up the luminosities of the lines and edges (Luminosities), with the turbulent speed vturb (km/s). passes (odd, XSTAR's npass) repeats the march over the same zones: the even passes go from the outer edge inwards at the temperatures of the zones to give the optical depths of the lines and edges beyond each zone, which the odd passes use as the outward depths of the escape probabilities. processes is a collection of AbstractContinuum processes (standard_processes(compton)) whose heating, cooling and opacity are those of the zones; cfrac is the covering fraction of the escape probabilities (give Thomson the same). Further keywords go to those functions.

After each zone the opacities are added to the depths (stpcut): the lines and edges to the OpticalDepths, the continuum opacity (Continuum of the processes, the strongest photoionization edges and lines of each bin) to dpthc, and the part of it that is continuum (not the lines or free-free: XSTAR's opakcont) to dpthcont, which is the depth in the transmitted spectrum of XSTAR's output.

Returns the named tuples of the zones (the result of thermal_equilibrium or ionization_balance with heating_cooling, and the fields r, Δr, radiation, escape, opacity), final (XSTAR's final calculation: the zone of no thickness at the end of the slab, at the temperature and electron fraction of the last, without opacity), the final OpticalDepths and the continuum depths dpthc and dpthcont. The diffuse emission is not added to the radiation.

write(path, results::Results; meta=(;), overwrite=true)

Writes the results of tables(model, run) to one FITS file: an empty primary HDU whose header has the meta (a named tuple of keyword values, e.g. the parameters of the run) and a binary table extension for each of ZONES, SPECTRUM, LINES and EDGES, with the units of the columns.

add_line!(opacity, radiation, coef, centre, emissivity, T; vturb=default_turbulence, lfast=2)

Puts the line of the record coef in the bins with add_line!, as ucalc does for a line of type 50 (the other records do nothing): centre is the opacity at the line centre (oplin, cm⁻¹) and emissivity the pair of emissivities (rcem1, rcem2). The natural width is the Einstein A times 4.136×10⁻¹⁵ eV s, or, for a line whose upper level is a K-vacancy level with a record of rate type 41, the width of that record (widths of auger_widths: deleafnd).

add_line!(opacity, radiation, optpp, rcem1, rcem2, elin, vturb, T, mass, delea; lfast=2)

Puts the line of wavelength elin (Å) and centre opacity optpp (cm⁻¹, opacity of the rate of the line times the density of its lower level) into the bins of radiation.E in the opacity (Opacity: total), as XSTAR's linopac does. vturb is the turbulent speed (km/s), T the temperature (10⁴ K), mass the mass of the ion (amu) and delea the natural width (eV). The profile is the Voigt function of the thermal and turbulent widths and the damping parameter delea/(width 4π), calculated on a grid ncut times finer than the bin of the line centre and averaged in each bin (lfast ≤ 2); with lfast > 2 all the opacity goes in the bin of the centre, in total as optpp × width over the width of the bin, and the emissivities rcem1 and rcem2 (erg s⁻¹ cm⁻³) in emissivity (they are not used for the full profile).

add_luminosities!(luminosities, line_emissivities, edge_emissivities, r, Δr)

Adds a zone at the distance r and of thickness Δr (cm) to the Luminosities, as heatt does: a line adds rcem Δr 4π r² in each direction, an edge adds half of cemab Δr 4π r² to each (its two emissivities summed), in units of 10³⁸ erg s⁻¹.

add_two_photon!(opacity, radiation, coef, abund2, ptmp)

Puts the continuum of the two-photon decay coef (a TwoPhotonDecay, or an AtomicLine2 of rate type 9) in the recombination emissivity of opacity, as ucalc does (ind = 50, nrdesc = 9): the energy A hν of the decay of the upper level, with the density abund2, is spread over the bins below the energy hν of the transition with the shape E² (hν - E), ptmp[1] of it in the first direction and ptmp[2] in the second (per steradian: the emissivity is abund2 A hν shape ptmp / (4π ∫ shape dE); the integral starts from 0 at the first bin as ucalc does it). The records with a level out of the table or a wavelength (or rate) below 0.01 add nothing.

add_zone!(depths, opacities, Δr; direction=:inward)

Adds the opacities of a zone (record_opacities) times its thickness Δr (cm) to the optical depths in the given direction, XSTAR's stpcut.

anl1(ni, nf, lf, iq)

Spontaneous dipole rates (alm, alp) (s⁻¹) from (ni, lf-1) and (ni, lf+1) to (nf, lf) for an ion of charge iq, from Gordon's formula.

auger_rates(mixture)

The rates (A_auto(k, parent), A_rad(k)) (s⁻¹, the third and fourth reals) of the first record of rate type 41 of each K-vacancy level (ion, level): auger_widths has the first, binemis takes both.

auger_widths(mixture)

The widths A_auto(k, parent) (s⁻¹, the third real of the record) of the K-vacancy levels of the records of rate type 41 (IronKAuger) of the elements of mixture, as a dictionary (ion, level) => width which deleafnd consults for the natural width of a line whose upper level is one of them (the first record of the level, as it does).

broaden(E, lines, T, vturb)

The emission of lines on the energy grid E (eV), as XSTAR's binemis makes it: lines is a collection of (wavelength, mass, inward, outward, delea, egam) (Å, amu, the two luminosities in erg s⁻¹, the Auger width in s⁻¹ and the radiative width egam that sets the damping), T the temperature (10⁴ K) and vturb the turbulent speed (km s⁻¹; the larger of it and the thermal speed is used). Each line has a Voigt profile, calculated on a grid ncut times finer than the bin of the line and averaged in the bins of E, per erg. Returns (inward, outward), in erg s⁻¹ erg⁻¹.

broaden(model, run; vturb=run.vturb, min_fraction=1e-15, nrank=rank_per_bin)

The emission of the lines of a run (slab) binned on its energy grid (broaden(E, lines, T, vturb)), at the temperature of the last zone: the nrank lines with the largest luminosity in each bin (rank!) among those with more than min_fraction of the luminosity of the source. Returns (inward, outward) in erg s⁻¹ erg⁻¹.

chianti_upsilon(kind, ΔE, C, p, T)

Effective collision strength Υ from the 5-point reduced fit p for transition type kind (1–4), transition energy ΔE (Ry), abscissa scale C and temperature T (K), after Burgess & Tully (1992).

chianti_upsilon(kind, ΔE, C, x, Υ, T)

Effective collision strength from an n-point reduced fit (XSTAR upsiln) for transition type kind (1–6): Υ are the reduced values at the nodes x in [0, 1], ΔE the transition energy (Ry), C the scale and T the temperature (K).

construct(T, rate, label, ivec, rvec, levels)

The record of rate type T (an entry of ratemap) from the integers ivec and reals rvec of the database, with the Levels levels if the type needs it (needs_levels).

edge_emissivities(mixture, balance, T, ntot; radiation=NO_RADIATION, escape=nothing, lfast=photoionization_lfast, cfrac=0.0)

The emission of the recombination continua (the records of rate type 7, edge_rate_type) of every element in the zone as the pairs (cemab1, cemab2) (erg s⁻¹ cm⁻³ in the two directions) of calc_emisab_ion, in vectors aligned with the records: the energy |ans3| that the population of the upper level radiates in the recombination, split by the escape probabilities escape (pescv of the depths of the edges, escape_probabilities; without it the edges are optically thin). The other records have 0.

eint(t)

The exponential integrals (E₁, E₂, E₃)(t) as XSTAR's eint.

electrons(mixture, fractions)

The number of electrons per hydrogen nucleus of the gas with the ion fractions of each element (each from the neutral up and the bare nucleus last, see ion_fractions): XSTAR's enelec. Every ion of charge q has q electrons free and the bare nucleus Z; the abundance weights the elements.

element_heating(elements, cell, populations; radiation=NO_RADIATION, escape=nothing, lfast=photoionization_lfast, cfrac=0.0, memo=nothing)

The heating and cooling of the element of elements with the level populations in cell, per unit abundance (erg cm⁻³ s⁻¹ for an abundance of 1 relative to hydrogen: the density of an ion is cell.ntot times its population), as (heating, cooling, heating2, cooling2). They are the sums over the records of the energy of the photons (heating, cooling) and of the electrons (heating2, cooling2) that each exchanges at the levels of its transition, XSTAR's msolvelud: the energy of a record at a level is energy × population, a heating if it is negative, a cooling if positive.

element_ions(records, Z)

The ion indices of the element of atomic number Z, from the neutral to the last bound stage (its Ion records, in order of ionization stage).

element_matrix!(A, layout, cell; radiation=NO_RADIATION, lfast=photoionization_lfast, escape=nothing)
element_matrix(layout, cell; sparse=false, kw...)

The rate matrix A (s⁻¹, dx/dt = A x) of the element of layout for the gas in cell, written into A or newly allocated (sparse=true: a sparse matrix, see sparse_matrix; the dense matrix of a large element, such as iron's 5718 unknowns, takes 260 MB); the unknowns are described at Elements. Each record that enters the matrix puts the two rates of ucalc, ans1 (lower to upper level) and ans2 (upper to lower), into the four entries A[up, lo] += ans1 A[up, up] -= ans2 A[lo, up] += ans2 A[lo, lo] -= ans1.

• radiation is the radiation seen by the photoionization rates and the lines: a Radiation (the mean intensity J at the cell, whatever the geometry that gave it; none by default).
• lfast is the speed switch of the photoionization integrals (2: photoionization and recombination, no opacities, as XSTAR's calc_hmc_element).
• escape gives the escape probabilities (ptmp1, ptmp2) of the lines and the recombination continua: a function of the record or a vector with a pair for each record of layout.rates; the rates' default (no line trapping) when nothing. XSTAR obtains them from the optical depths along its ray; another geometry supplies its own.

element_populations(layout, cells; radiation=NO_RADIATION, kw...)

The level populations (see level_populations) of the element of layout in each of the cells, as an N × length(cells) matrix (one column per cell; the cells may be any array, the columns follow its linear indices). The cells do not depend on each other and are solved on the threads of Julia. The matrices are sparse (sparse=true) for the elements of sparse_from unknowns or more. radiation and escape (see element_matrix!) are fixed values for all the cells, or functions of the index of the cell that return that cell's value, so that each cell has its own radiation field and line trapping.

erc(n, m, T, ic, a)

Hydrogenic electron-impact excitation and de-excitation rates (se, sd) (cm³ s⁻¹) between principal quantum numbers n < m for an ion of charge ic at T (K); a is the summed spontaneous rate used by the impact-parameter fit.

escape_probabilities(mixture, depths; cfrac=0.0)

The escape probabilities (ptmp1, ptmp2) of every record of every element, as the vectors that escape= takes (one vector of pairs per element, in the order of mixture.Z): for a line (rate types 4 and 9) pescl of its two optical depths with the covering fraction cfrac, for a recombination edge (rate type 7) pescv of those of its edge, and 1/2 each for the others. XSTAR takes the depths of the zones that the radiation has crossed already (calc_hmc_ion).

expint(x)

x e^x E₁(x) (XSTAR's expint output em1): the Abramowitz & Stegun polynomial fits for x > 1 and the series for x ≤ 1.

gas_density(ntot, T, r)

The same at the distance r (cm) from the source: only PowerLawDensity depends on it.

gas_density(ntot, T)

The hydrogen density (cm⁻³) of the gas at the temperature T (10⁴ K): ntot if it is a number (constant density), or ntot(T) if it is a function, such as ConstantPressure(P).

impactn(n, m, T, ic, amn)

Symmetric collision quantity cmm for the electron-impact transition n → m of a hydrogenic ion of charge ic, by Seaton's impact-parameter method with the strong-coupling cross sections only.

interpolate_cross_section(ε, σ, e)

Cross section at the energy e (Ry above the threshold) of the table σ(ε) (XSTAR's find53): linear between the points, a power law in the last interval, and zero outside the table.

interpolate_super_table(logne, logT, table, T, den; guard=0.0)

Linear interpolation of table[it, in] in log₁₀ T and log₁₀ n at the temperature T (K) and the density den, as XSTAR's calt71 and calt77 do: the density is limited to the table, the temperature to one dex outside it (the end segments are extrapolated), and guard is added to the grid spacings (calt77 uses 1e-36).

ion_fractions(x, layout)

The fractions of the ions of layout and of the bare nucleus last, from the level populations x of element_matrix.

ion_rates(records, ion)

The rate records of records (a loaded database) that belong to ion ion and enter its level balance.

ionization_balance(mixture, T, ntot; radiation=NO_RADIATION, escape=nothing, xee=1.0, iterate=true,
                   neutral=0.0, lfast=photoionization_lfast, tolerance=electron_tolerance)

The level populations of all the elements of mixture at the temperature T (10⁴ K) and the hydrogen density ntot (cm⁻³), in the radiation field radiation. The electron density is ntot xee, and xee is iterated until it is the number of electrons per hydrogen nucleus that the balance gives, to the relative tolerance, in XSTAR's way (dsec): the solution is bracketed by steps of a factor 1.2 from the starting value xee, then found by false position. With iterate=false the balance is made at xee (the reference run of XSTAR does that, with xee = 1). neutral is the density of neutral hydrogen (cm⁻³) that the charge exchange rates see at the first evaluation, the following ones take it from the populations of the hydrogen ground state; escape and lfast are as for element_matrix!.

Returns a named tuple with the electron fraction xee and density nₑ, the electrons per hydrogen nucleus, the neutral hydrogen density nₕ, the populations and the ion fractions of each element (in the order of mixture.Z), the number of evaluations iterations and whether it converged.

irc(n, T, rc, rno)

Collisional ionization coefficient from level n of an ion of effective charge rc for the highest bound level rno at the temperature T (K) (XSTAR's irc). For rc ≠ 1 it is szirc.

level_populations(A)

The populations x (fractions of the element, Σ x = 1) that solve A x = 0: the last equation is replaced by the normalisation, as in XSTAR. Levels that no rate connects (|A| below unconnected_tolerance in their row and column) are dropped, as XSTAR's msolvelud does, and have population 0.

line_emissivities(mixture, balance, T, ntot; radiation=NO_RADIATION, escape=nothing, lfast=photoionization_lfast, vturb=default_turbulence, cfrac=0.0)

The emissivity of the lines (the records of type 4, line_data_type) of every element in the zone, as the pairs (rcem1, rcem2) (erg s⁻¹ cm⁻³ outward and inward) of calc_emisab_ion, in vectors aligned with the records: the energy that the population of the upper level of the record radiates in the decay, -abund₂ ans3 split by the escape probabilities escape (escape_probabilities; the lines are optically thin without it). The other records have 0.

lte_populations(levels, ion, cell)

The populations of the levels of ion (the continuum last) in local thermodynamic equilibrium at the temperature and electron density of cell: XSTAR's levwk.

map_spectrum(radiation, E=radiation.E)

The spectrum of radiation on the energy grid E as XSTAR's bremsmap maps it before the balance of a zone: each bin of E takes the flux of the bin of radiation that is nearest to it (nbin). That function does not go above the bin n - max(2, n ÷ 50) of the grid (the top 2% of the bins are not used), so for the same grid the flux of every higher bin is that of the last one below: a flat tail where a power law falls. The Compton heating, which the high energies dominate, depends on it (+50% for an E⁻¹ spectrum on XSTAR's grid).

mean_intensity(rad)

The mean intensity J = F/4π of rad.

milne_recombination(T, ε, σ, E_th)

Recombination coefficient (cm³ s⁻¹) from the Milne relation for the cross-section table σ(ε) (ε in Ry above the threshold E_th, in Ry) at the temperature T in K (XSTAR's milne). The sum over the table stops once it changes by less than 1%.

nbin(rad, e)

Index of the grid energy nearest to e (XSTAR's nbinc): the grid is assumed equally spaced in log E.

needs_levels(T)

Whether the rate type T has a field levels, the Levels it reads its level data from.

next_bin(rad, E_th, nb1, T, lfast)

Step nskp to the next sampled bin of the photoionization integrals and the last bin nphint to use (XSTAR's enxt).

pescl(tau)

The probability that a photon of a line escapes in one direction when the optical depth to the edge of the slab in that direction is tau (XSTAR's pescl; 1/2 for a thin line, with the complete redistribution of a Doppler core and the damping wings added for tau ≥ 1).

pescv(tau)

The probability that a photon of a recombination continuum escapes in one direction when the optical depth of the edge is tau (XSTAR's pescv: exp(-tau)/2, not below 10⁻¹²/2).

pexs(nmin, zc, eion, far, gam, scal, E)

Photoabsorption cross section (cm², before the 1e-18) of a series of resonances converging on the K edge, on the energies E (Ry), after Palmeri et al. (XSTAR's pexs): nmin the lowest resonance, zc the effective charge, eion the edge energy (Ry), far the oscillator-strength scale, gam the resonance width and scal a scale factor. Returns nothing if nmin ≥ 30.

phextrap(ε, σ, E_th, ncn2)
phextrap!(ε, σ, E_th, ncn2)

Extends a cross-section table (ε in Ry above the threshold E_th eV, σ in cm²) with points falling as E⁻³ up to 2e5 eV, as XSTAR does. The last tabulated point is replaced by the first extrapolated one (or dropped if there is none). phextrap! does it in the two vectors, which must be Float64, and phextrap returns new ones.

photoionization_integrals(rad, E_th, ε, σ, T, rnist, ptmp; abund=(0, 0), ntot=0, lfast=1, opacity=nothing, buffer=nothing)

Photoionization rate pirt, recombination rate rrrt, and the energy-weighted piht, rrcl (erg s⁻¹, measured from zero) and piht2, rrcl2 (measured from the threshold), by integrating the cross section table (ε in Ry above the threshold E_th in eV, σ in cm²) over the radiation field (XSTAR's phint53). T is in 10⁴ K, rnist the Saha factor and ptmp the two escape probabilities (in the reverse and forward direction). The recombination terms need lfast ≥ 2. buffer, a Vector{Float64}, is used for the work array of the integral when the cross sections are Float64s (it grows as needed), instead of a new one. If opacity is given, the continuum opacity and recombination emissivity are added to it. Also returns opakab, the opacity of the first bins above the threshold.

photoionization_integrals_fo(rad, E_th, σ, T, swrat, xnx; abund=(0, 0), ntot=0, lfast=1, opacity=nothing)

Photoionization and recombination integrals for a cross section σ (cm²) given on the energy grid of rad (XSTAR's phintfo): pirt, rrrt, piht, rrcl, piht2, rrcl2 as in photoionization_integrals, and the opacity opakab of the first bins. swrat is the ratio of the statistical weights of the two levels and xnx the electron density. The recombination terms always run (the convergence test of the original never stops the loop).

photoionization_integrals_hunt(rad, E_th, ε, σ, T, swrat, xnx)

Photoionization and recombination integrals of a cross-section table σ(ε) (cm², ε in Ry above the threshold E_th in eV) over the spectrum of rad (XSTAR's phint53hunt): the grid is sampled every 2ᵏ bins and refined by halving the step until the rates change by less than 1%. Returns pirt, rrrt, piht, rrcl, piht2, rrcl2 as photoionization_integrals_fo. Bins already computed in an earlier pass are reused, except for the recombination weight measured from the threshold (rrcl2), which keeps the value of the last bin computed in the pass, as in the original.

photoionize_level(coef, cell; radiation=NO_RADIATION, ptmp=(0.5, 0.5), abund=(0, 0), lfast=1, opacity=nothing, extrapolate=false, shifted=false, parent=true, rates_only=false)

Photoionization of a level of an ion by integrating the cross-section table of coef (fields level, ion, parent, E_grid in Ry above the threshold and σ in Mb) over radiation (XSTAR ucalc types 49 and 53). The level data, with the number of levels of the ion (the last is the continuum, the ground state of the next ion), comes from the coefficient (its levels field); ptmp is the two escape probabilities and abund the populations of the initial and final levels (for the opacity). lfast ≥ 2 also integrates the recombination terms. If opacity is an Opacity the continuum opacity and recombination emissivity are added to it. extrapolate extends the table with an E⁻³ tail (types 49 and 88) and shifted adds the excitation energy of an excited parent level to the threshold (type 53). With parent=false the final level is always the continuum (type 88), and rates_only=true keeps only the photoionization rate and the opacity, zeroing the rest as ucalc type 88 does (the opacity and emissivity arrays are still filled).

Returns init (the level) and final (nlev + parent level − 1), frate the photoionization rate and irate the radiative recombination rate (s⁻¹), fenergy/ienergy the heating and recombination cooling (erg s⁻¹), fenergy2 and ienergy2 the same measured from the energies of the two levels, and opacity the opacity of the first bins above the threshold. For parent levels above the ground state, ucalc reads the energy of the final level from stale memory; here it is the continuum energy plus the energy of the parent level.

photoionize_superlevel(coef, cell, tabulate; radiation=NO_RADIATION, correct_energy=false, index=false)

Photoionization and recombination of a superlevel (XSTAR ucalc types 70 and 99). The cross section σ(ε) is the table of the record scaled so that the Milne relation reproduces the tabulated recombination coefficient at the density and temperature of cell; tabulate(T, ntot, E_th) returns that coefficient rec (cm³ s⁻¹), ε (Ry above the threshold) and σ (Mb), for the temperature T in K, the density ntot, and the threshold E_th in Ry. The cross section is then integrated over radiation with photoionization_integrals_hunt, and the photoionization rate and the heating are scaled by the ratio of the tabulated and integrated recombination rates. The recombination cooling is not scaled (as in ucalc). With correct_energy the energies measured from the levels are scaled too (type 99).

Returns init (the level, limited to the last real level nlev − 1), final (nlev + parent level − 1), frate and irate (s⁻¹), fenergy, ienergy, fenergy2, ienergy2 (erg s⁻¹) and opacity (zero, the arrays are not filled). When the recombination integral is negligible ucalc returns no rates but leaves the integrals piht2 and rrcl2 in its energy outputs; that is kept.

point_source(E, L, r)

The radiation at the distance r (cm) from a point source of the spectrum L (erg s⁻¹ erg⁻¹) on the grid E, in a medium without absorption: the 1-D geometry of XSTAR, F = L/(4π r²) with the fourpi of the constants in use (4π, or the 12.56 that XSTAR's trnfrc writes: a flux 0.05% smaller than for 4π). Other geometries supply their own J.

rank!(list, entry, nrank)

Puts entry = (strength, k, j) in the list of the strongest entries of an energy bin, as XSTAR's rlbin does: the list is in order of decreasing strength and holds nrank entries at most. An entry whose place would be the last one (nrank) is not inserted, as in rlbin, which returns before it stores it; the entries below it move down and the last one drops out.

rate(coef::AtomicLine2, cell; mass=weight(coef.levels, coef.ion), vturb=1.0, pesc=1.0, radiation=nothing, cfrac=0.0, index=false)

Radiative decay and photoexcitation of an atomic line (XSTAR ucalc type 50). The level data and the number of levels of the ion (the continuum level is excluded) come from the coefficient (its levels field), and so by default does the atomic mass (amu) of the element. vturb is the turbulent velocity (km/s), pesc the sum of the two escape probabilities (1 when optically thin), radiation the incident spectrum (none by default) and cfrac the covering fraction.

Returns init (upper) and final (lower) levels in energy order, the decay rate frate = A·pesc (s⁻¹, floored at 1e-20 ntot), the photoexcitation rate irate from radiation at the line energy (zero without radiation, for lines without a wavelength, and reduced by 1 - cfrac), the energies fenergy and ienergy they carry (erg s⁻¹ per ion, from the energy difference of the two levels) and the line-centre opacity (zero for lines without a wavelength). Records with no wavelength (λ = 0) and records with a level missing from the level table give no rates. The line opacity that XSTAR adds to its continuum arrays (linopac) is not included.

rate(coef::AutoionizeFe25Sat, cell; index=false)

Autoionization of an Fe XXIV satellite level (XSTAR ucalc type 75) with the rate of satellite_capture (no weight): irate is that rate times the electron density and frate is 0. init is the level (at least 1) and final the level of the parent ion counted from the continuum (nlev + parent level − 1, at least 1).

rate(coef::AutoionizeSat, cell; index=false)

Autoionization of a satellite level (XSTAR ucalc type 72) from the rate 3.3e-11 (13.6 eV/kT)^{3/2} e^{-E/kT} (A/10¹³) g (calc_72). As ucalc has it, irate is that rate times the electron density and frate is irate nₑ times the Saha factor of the ground to the continuum level weights and e^{E/T} with the energy in eV divided by the temperature in K (which is ≈ 1; the units look wrong in the source and are reproduced). init is the level and final the continuum level of the record. The level table needs the ground (1) and the continuum (nlev) levels.

rate(coef::ChargeExHe, cell; index=false, nlev=0)

He charge exchange (XSTAR ucalc type 9). The rate goes into irate (frate is 0): 1e-9 a min(T,1000)^b (1 + c e^{dT}) 0.1 nₕ, divided by 6 for records with two levels. init and final are the levels (final counts from the first level of the recombined ion, nlev, the number of levels of the ion).

rate(coef::ChargeExHp, cell; nlev=0, index=false)

Charge exchange of an ion with H⁺ (XSTAR ucalc type 10): frate = nHp 10⁻⁹ a T^b (1 + c e^{dT}) e^{-ΔE/kT} with T in 10⁴ K and nHp = cell.ntot - cell.nₕ the density of H⁺ (XSTAR's xh1: the hydrogen that is not neutral). irate is 0. init is the level of the record and final the continuum level nlev. The range of the fit is not applied, nor is the sum 1 + c e^{dT} limited at 0 (unlike type 2).

rate(coef::CollisionAPED, cell; index=false)

Collisional excitation and de-excitation between two levels from a table of the effective collision strength Υ(T) (XSTAR ucalc type 92, calc_maxwell_rates). Only the kinds 100 + n that the database has are supported: Υ is interpolated in log-log in T_grid (the first n points, no extrapolation, zero outside T_min..T_max or the grid) and the rates are frate = 8.629e-6 Υ e^{-χ}/(√T g_l), irate = 8.629e-6 Υ/(√T g_u) with χ = ΔE/kT and the electron density; fenergy and ienergy are the rates times ΔE. The first level of the record is the lower one whatever the energies. Other kinds throw an error.

rate(coef::CollisionFe19, cell; index=false)

Collisional excitation and de-excitation of Fe XIX from a constant effective collision strength Υ (XSTAR ucalc type 81): irate = nₑ C Υ/(√T g_u) and frate = irate g_u e^{-ΔE/kT}/g_l (T in 10⁴ K, C the Maxwellian coefficient), fenergy and ienergy the rates times ΔE. init is the lower and final the upper level by energy (the stored order is not reliable); both must be in 1:nlev of the ion. The level data comes from the Levels of the coefficient (its levels field). Negative Υ is taken as 0.

rate(coef::CollisionHeFine, cell; index=false)

Collisional excitation and de-excitation of a He-like ion from the fine-structure fits (XSTAR ucalc type 66, calt66): the first coefficient is the energy (eV) of the transition, used for the Boltzmann factor, the temperature floor ΔE/50k and the energy of the rates instead of the energy difference of the levels, which only order them. Υ is the first term of type 69's fit (and two more if there are more than 6 coefficients, a form the database does not have) and is not clamped at 0; otherwise like rate(::CollisionLS, ...).

rate(coef::CollisionHelike, cell; index=false)

Collisional excitation and de-excitation of a He-like ion from a quadratic fit of the effective collision strength in log₁₀(T/Z³) (XSTAR ucalc type 68, calt68), clamped at 0, with a temperature of at least ΔE/50k; otherwise like rate(::CollisionLS, ...).

rate(coef::CollisionHelikeSat, cell; index=false)

Collisional excitation and de-excitation involving a satellite level of a He-like ion from a fit to the effective collision strength (XSTAR ucalc type 73, calt73). The first coefficient is used both as an energy in Rydberg (in the fit) and as a wavelength in Å (for the temperature floor ΔE/50k, the Boltzmann factor and the energy of the rates), as ucalc does. irate is the de-excitation rate, frate = irate g_u e^{-ΔE/kT}/g_l, fenergy and ienergy the rates times that energy; init is the lower and final the upper level by energy, both in 1:nlev.

rate(coef::CollisionHlike1, cell; index=false)

Collisional excitation and de-excitation of an H-like ion from a polynomial fit of the effective collision strength in the scaled temperature kT/Ry (XSTAR ucalc type 60, calt6062): Υ = Σ cᵢ τ^{i-1} with the coefficients from the third real on, τ limited to 1 and Υ extrapolated beyond it by 1 + ln τ₁/(ln τ₁ + 1). irate is the de-excitation rate nₑ C Υ/(√T g_u) and frate = irate g_u e^{-ΔE/kT}/g_l (T in 10⁴ K), fenergy and ienergy the rates times ΔE. init is the lower and final the upper level by energy, both in 1:nlev; the temperature of the fit is at least ΔE/50k. Weights have 1e-16 added.

rate(coef::CollisionHlike2, cell; index=false)

As rate(::CollisionHlike1, ...) (XSTAR ucalc type 62 runs the same code) with the second form of the fit: the polynomial stops three coefficients before the end and c[m-2] ln(c[m-1] τ) e^{-c[m] τ} is added.

rate(coef::CollisionIonize, cell; index=false)

Collisional ionization of an ion and its inverse, three-body recombination (XSTAR ucalc type 95), from the effective collision strength ρ(x) of the record, interpolated linearly in the scaled temperature x = 1 - ln 2/ln(kT/E_th + 2). frate and irate include the electron density; init is the ground level (ucalc takes the statistical weight and the level of the ground state whatever the level of the record) and final the continuum, nlev (records of rate type 15 give level 1 again). fenergy and ienergy are the rates times the threshold energy. For temperatures below the first point of the table ucalc interpolates with the first interval's left end read from T0 and the last x_grid; reproduced.

rate(coef::CollisionLS, cell; index=false)

Collisional excitation and de-excitation of a He-like ion from the fit of Kato and Nakazaki to the effective collision strength (XSTAR ucalc type 69, calt69). The first coefficient is the energy (eV) of the fit, which scales the temperature, and the next five (or eight, with a non-resonant part) the coefficients; Υ is clamped at 0 and the temperature is not floored. irate is the de-excitation rate nₑ C Υ/(√T g_u), frate = irate g_u e^{-ΔE/kT}/g_l (T in 10⁴ K) and fenergy, ienergy the rates times the energy difference of the levels; init is the lower and final the upper level by energy, both in 1:nlev.

rate(coef::CollisionProb, cell; index=false)

Collisional transition rates between two levels of a hydrogenic ion (XSTAR ucalc type 63), for nl → n'l' with |Δl| = 1. The levels come from the coefficient's level table (its levels field). init and final are the two levels in stored order, frate is the rate init → final and irate the reverse (s⁻¹, including the factor nₑ). Both are 0 when the levels do not have |Δl| = 1, when ΔE/kT > 50, or if a level is missing from the level table.

For n = n' the rate is the l-changing rate of Pengelly & Seaton (velimp) with the detailed-balance partner. For n ≠ n' it is the electron-impact rate erc distributed over l with Gordon's radiative rates (anl1). XSTAR applies the large (de-excitation) rate of this branch to the upward direction (the source comments "check if ans1 and ans2 are correct or inverted"); this is reproduced as is.

rate(coef::CollisionSuper, cell; index=false)

Collisional transitions between a superlevel and a spectroscopic level (XSTAR ucalc type 77). irate is the de-excitation rate 10^C interpolated in log₁₀ T and log₁₀ n from the table (the temperature floored at 2.88e6/λ K from the level energies), frate the excitation rate from its Boltzmann factor at the wavelength λ of the record and the weight 2(2l + 1) where l follows from numbering the first level of the record by shells. fenergy and ienergy are the rates times the energy difference of the levels. Both levels must be in 1:nlev, differ, and be at least 1 eV apart.

rate(coef::DielecRecomb1, cell; index=false)

Dielectronic recombination to the ground level of the next ion from the formula of Aldrovandi and Péquignot (XSTAR ucalc type 7): frate = nₑ A e^{-T0/T}(1 + B e^{-T1/T}) T^{-3/2} with T in 10⁴ K, T0 and T1 in the same units and A in cm³ s⁻¹ K^{3/2}.

rate(coef::DielecRecomb2, cell; index=false)

Dielectronic recombination to the ground level of the next ion from the sum of four terms of Arnaud and Raymond (XSTAR ucalc type 8): frate = nₑ T^{-3/2} Σᵢ Cᵢ e^{-Eᵢ/kT} with T in 10⁴ K and the energies in eV. The database has no records of this type: it is checked only against ucalc with synthetic records (test/reference/ucalc/synthetic.jl).

rate(coef::DielecRecombH, cell; index=false)

Dielectronic recombination to the ground level of the next ion from the fit of Storey (XSTAR ucalc type 22): frate = nₑ 10⁻¹² (a/T + b + T(c + T d)) T^{-3/2} e^{-e/T} with T in 10⁴ K, floored at 0 and zero above 6×10⁴ K.

rate(coef::EffectiveCharge, cell; index=false)

Collisional ionization of a level and its inverse, three-body recombination (XSTAR ucalc type 57), from the hydrogenic fits of irc/szirc with the effective charge set by the ionization potential of the level. frate is the ionization rate, irate the recombination rate (both including the electron density), init the level and final the continuum (nlev). fenergy and ienergy are the rates times the ionization potential, negated (ucalc's ans6 and ans5). The ground level, and a level with a non-positive potential, give nothing. The stored Zeff is not used.

rate(coef::ElectronCollision, cell; index=false)

Electron-impact excitation and de-excitation from the CHIANTI fits (XSTAR ucalc type 51). The levels come from the coefficient's level table (its levels field). init is the lower and final the upper level (ordered by energy), frate the excitation and irate the de-excitation rate (s⁻¹), related by detailed balance with the transition energy ΔE of the record. The fit temperature is floored at ΔE/50k. Records carry 5 knots (splinem) or 9 knots on x = 0, 1/8, …, 1 (upsiln); others are skipped. Both rates are 0 if a level is missing from the level table or ΔE ≤ 0.

Υ is clamped at 0, which ucalc does not do: for 4 records the 5-point spline dips slightly below zero (rates of about -1e-7 in XSTAR). XSTAR's matrix assembly decides which level is lower with a ratio test on the level energies that can swap them for nearly degenerate levels; that quirk is not reproduced.

rate(coef::ElectronImpact1, cell; index=false)

Electron-impact excitation and de-excitation (XSTAR ucalc type 56). The levels come from the coefficient's level table (its levels field). The levels are ordered by energy, init is the lower and final the upper level, frate the excitation rate and irate the de-excitation rate (s⁻¹), related by detailed balance. Υ is interpolated linearly in log T; outside the table the nearest segment is extrapolated (as ucalc does, since its hunt clamps the index) and the result clamped at 0. Both rates are 0 if a level is missing from the level table or the two energies coincide.

rate(coef::ElectronImpact2, cell; index=false)

Electron-impact excitation and de-excitation from the CHIANTI 2016 fits (XSTAR ucalc type 98), like ElectronCollision but with an n-point spline through the nodes of the record. The levels come from the coefficient's level table (its levels field). init is the lower and final the upper level (ordered by energy), frate the excitation and irate the de-excitation rate (s⁻¹), related by detailed balance at the record's transition energy. The fit temperature is floored at ΔE/50k. Both rates are 0 if a level is missing from the level table or ΔE ≤ 0.

rate(coef::IronKAuger, cell; index=false)

Auger decay of a K-vacancy level of iron (XSTAR ucalc type 86): frate is the Auger width A_widths[1] (s⁻¹), independent of the cell, from init (the vacancy level) to final (nlev + the level of the parent ion − 1); irate is 0. ucalc does not look at the levels, so none are needed.

rate(coef::ParPhotoIonize1, cell; levels, radiation, nlev, ptmp=(0.5, 0.5), abund=(0, 0), lfast=1, opacity=nothing)

Photoionization of a level (XSTAR ucalc type 49) from a cross-section table that is extended with an E⁻³ tail; see photoionize_level for the arguments and the result.

rate(coef::ParPhotoIonize2, cell; levels, radiation, nlev, ptmp=(0.5, 0.5), abund=(0, 0), lfast=1, opacity=nothing)

Photoionization from TOPbase's resonance-averaged cross sections (XSTAR ucalc type 53): as ParPhotoIonize1 but without the E⁻³ tail, and the threshold includes the excitation energy of an excited parent level. See photoionize_level.

rate(coef::ParPhotoIonize3, cell; abund=(0, 0), opacity=nothing)

Photoionization from the analytic fit of Verner et al. (XSTAR ucalc type 59), evaluated on the energy grid of radiation and integrated with photoionization_integrals_fo (the recombination terms are zero for rate type 1 and for excited levels, as in ucalc). The levels and their number come from the coefficient's level table (its levels field). Returns init and final (nlev + parent level − 1), frate and irate, the energies fenergy, ienergy, fenergy2, ienergy2 and the opacity. Nothing is returned if the parent ion is more than one step away, the threshold is outside the grid, or the integrated spectrum above it is negligible. Only the 6-real form of the record is supported. ptmp and lfast are accepted for uniformity with the other photoionization rates but not used.

rate(coef::PhotoRecombX, cell; index=false)

Photoionization and recombination of a superlevel from the tabulated recombination coefficients and cross section (XSTAR ucalc type 99), see photoionize_superlevel. The energies measured from the levels are corrected with the energy of the levels. The other keywords of the photoionization rates are accepted and ignored.

rate(coef::PhotoionizeDamp, cell; levels, radiation, nlev, ptmp=(0.5, 0.5), abund=(0, 0), lfast=1, opacity=nothing)

Photoionization with the damped-excess cross sections (XSTAR ucalc type 88): as ParPhotoIonize1 but always to the continuum, and only the photoionization rate frate and the opacity are returned (the recombination and energy terms are zero, as in ucalc). See photoionize_level.

rate(coef::PhotoionizeDelta, cell; nlev)

Delta-function photoionization added to the cross sections to match dielectronic recombination rates (XSTAR ucalc type 74, calt74). frate sums the spectrum of radiation at the line energies weighted by the line strengths, irate is the matching recombination sum at the temperature of cell, scaled by the statistical weights of the level and of the continuum level nlev. final is nlev. Both are 0 if the spectrum does not reach the highest line.

rate(coef::PhotoionizeFeKedge, cell; abund=(0, 0), opacity=nothing)

Photoionization of Fe near the K edge from a series of resonances (XSTAR ucalc type 85), integrated with photoionization_integrals_fo from 0.8 of the edge energy. Returns the photoionization rate frate and the heating fenergy, fenergy2; the recombination terms and the opacity are zero as in ucalc (the opacity and emissivity arrays are still filled). final is the level 1. ucalc computes the charge of the resonance series as the ion index minus 114, a leftover of an earlier ion numbering, which is reproduced.

rate(coef::PhotoionizeSuper, cell; neutral=false, index=false)

Photoionization and recombination of a superlevel from the tabulated recombination coefficients and cross section (XSTAR ucalc type 70, "old type 70"), see photoionize_superlevel. The level data comes from the coefficient (its levels field) and radiation is the spectrum (none by default). neutral=true limits the density to 10⁸ cm⁻³ in the interpolation, as ucalc does for the first ion of an element. The other keywords of the photoionization rates are accepted and ignored.

rate(coef::RadiativeAPED, cell; kw...)

Radiative decay and photoexcitation of an APED line (XSTAR ucalc type 91). ucalc treats it as type 50 (it jumps to the same code, the wavelength, the stored 0 and A being in the same places), so the result and the keywords are those of rate(::AtomicLine2, ...).

rate(coef::RadiativeFeDecay, cell; vturb=1.0, pesc=1.0, radiation=nothing, index=false)

Radiative decay and photoexcitation of an Fe UTA line (XSTAR ucalc type 82), like rate(::AtomicLine2, ...) but: the decay rate is A_rad times pesc (no floor), the oscillator strength is the stored gf, the line energy is that of the wavelength (not of the levels), the photoexcitation is not reduced by a covering fraction and no line is excluded for its wavelength. frate is the decay and irate the photoexcitation from radiation at the line energy (zero without it); init is the higher and final the lower level. ienergy is the photoexcitation rate times the line energy and fenergy is 0 (ucalc returns only that one); opacity is the line-centre opacity. The level energies only order the two levels. The line opacity added to the continuum arrays (linopac) is not included. The level table needs the Fe UTA levels, which levels includes.

rate(coef::RadiativeProb, cell; index=false)

Hydrogenic radiative decay (XSTAR ucalc type 54) between the two levels of the record, from Gordon's formula (anl1): irate is the decay rate A (s⁻¹) from the upper to the lower level, from (n, l+1) or (n, l-1) depending on the orbital quantum numbers, and frate is 0. The stored A is not used. Nothing is returned if the two levels have the same n. ienergy is the rate times ΔE/kT and the erg per eV, which is what ucalc puts in its energy output (it multiplies by the dimensionless ΔE/kT, not by ΔE); fenergy is 0.

rate(coef::RadiativeSuper, cell; vturb=1.0, ptmp=(0.5, 0.5), index=false)

Radiative decay between a superlevel and a spectroscopic level (XSTAR ucalc type 71). The Einstein A is interpolated in log₁₀ T and log₁₀ n from the table of the record (the temperature may exceed the table by one dex) and multiplied by the sum ptmp of the escape probabilities, with a cap of 10¹⁰ s⁻¹ for ions 96 and 97. As in ucalc, the weights come from the first level of the record (transition.lower, init) and the decay is returned as irate (frate is 0). ienergy is the decay times the energy of the line (from its wavelength above 0.1 Å, from the levels otherwise) and opacity the line-centre opacity for the atomic mass (amu, from the level table by default) and the turbulent velocity vturb (km/s), both zero for lines longer than 10⁹ Å. Needs levels init and final between 1 and nlev.

rate(coef::TotDielecRecomb, cell; index=false)

Total dielectronic recombination to the ground level of the next ion (XSTAR ucalc type 39), the sum frate = nₑ T^{-3/2} Σᵢ Cᵢ e^{-Tᵢ/T} of the terms of Badnell's fit, with T in 10⁴ K and the Tᵢ in K.

rate(coef::TotRadRecomb, cell; index=false)

Total radiative recombination (XSTAR ucalc type 38, Badnell's fit). The characteristic temperatures T0, T1, T2 are in K while cell.T is in 10⁴ K.

rate(coef::TwoPhotonDecay, cell; index=false)

Two-photon decay of a level (XSTAR ucalc type 76): irate is the stored A (s⁻¹), frate is 0, init the higher and final the lower level by energy (both in 1:nlev), and ienergy is A times the energy difference of the levels. ucalc also adds the two-photon continuum, a spectrum E²(E_max − E) normalized to A, to its emissivity array; that is not included.

rate_matrix(rates, levels, ion, cell; kw...)

The rate matrix of the levels 1:nlevels(levels, ion) of a single ion (element_matrix of its layout).

record_opacities(mixture, balance, T, ntot; radiation=NO_RADIATION, lfast=photoionization_lfast, vturb=default_turbulence)

The centre opacities of the lines and the edge opacities of the recombination continua of every record of every element in the zone whose balance (from ionization_balance) is at the temperature T (10⁴ K) and hydrogen density ntot, in vectors aligned with the records: XSTAR's oplin and opakab, as calc_emisab_ion makes them. A line has the cross section at its centre times the density ntot × abundance × population of its lower level; an edge the opacity of photoionization_integrals for the populations (times the abundance) of the two levels of its transition. vturb is the turbulent speed (km/s) of the lines.

source_distance(luminosity, ξ, n)

The distance (cm) from a source of the luminosity (erg s⁻¹) at which the ionization parameter ξ = L/(n r²) is ξ for the density n (cm⁻³).

source_distance_pressure(luminosity, Ξ, P)

The distance (cm) from a source of the luminosity (erg s⁻¹) at which the ionization parameter of the pressure Ξ = L/(4π c P r²) is Ξ for the pressure P (dyn cm⁻²): XSTAR's r for lcpres=1.

sparse_matrix(layout, [T=Float64])

A sparse matrix with the pattern of the rate matrix of layout (the entries of its records and the diagonal) and zero values, for element_matrix!.

splinem(p, x)

5-point spline through the knots p[1] = y(0), p[2] = y(1/4), p[3] = y(1/2), p[4] = y(3/4), p[5] = y(1), evaluated for x in (0, 1).

standard_processes(compton; cfrac=0.0)

The processes of XSTAR: Compton scattering (compton), FreeFree() absorption, Bremsstrahlung() and Thomson(cfrac) scattering.

superlevel_cross_section(coef::PhotoRecombX, T, den, E_th)

Recombination coefficient rec and the cross-section table scaled to it (XSTAR's calt99, in single precision): log₁₀ α is interpolated linearly in log₁₀ T and in log₁₀ n between the two densities that bracket den; at the lowest density, outside the table and at the highest density the lowest density column is used. log₁₀ T is limited to the table. Floating-point input is rounded to single precision as in ucalc; other number types (dual numbers) are kept, so the rate can be differentiated. The table is scaled so that the Milne relation at T (K) with the threshold E_th (Ry) gives rec. Returns rec, E_grid and σ (Mb).

superlevel_cross_section(coef::PhotoionizeSuper, T, den, E_th)

Recombination coefficient rec and the cross-section table scaled to it (XSTAR's calt70): rec is interpolated in log₁₀ T and log₁₀ n (linearly in T, quadratically in n between three densities), the table is scaled so that the Milne relation at T (K) with the threshold E_th (Ry) gives rec, capped at 10⁶ Mb, and its tail below 10⁻⁶ of the first point is dropped. As in ucalc, the second tabulated log₁₀ density is limited to 8 and the density to the last tabulated one. Returns rec, E_grid and σ.

szirc(n, T, rz, rno)

Collisional ionization coefficient from level n for the effective charge rz and highest bound level rno at the temperature T (K), by Sampson and Zhang's fit (XSTAR's szirc).

thermal_equilibrium(mixture, ntot, processes; radiation=NO_RADIATION, escape=nothing, T=1.0, xee=1.0, T_min=default_T_min,
                    tolerance=imbalance_tolerance, iterations=temperature_iterations)

The temperature at which the heating and cooling of the gas balance, and the ionization balance there, for the hydrogen density ntot and the radiation field radiation, starting from the temperature T (10⁴ K) and the electron fraction xee and iterating as XSTAR's dsec does: at each temperature the electron fraction is iterated (ionization_balance) and the heating and cooling summed (heating_cooling); the temperature is changed by factors of 1.2 (of 1.44 when the relative imbalance exceeds 0.9) until it brackets the solution, then found by false position, with the stale end halved, until the relative imbalance |2 (heating - cooling)/(heating + cooling)| is below tolerance (or the temperature stops changing, or iterations temperatures were tried). T_min (10⁴ K) is the lowest temperature.

Returns the named tuple of heating_cooling for the last temperature with the added fields T, xee, nₑ, nₕ, populations, fractions (those of ionization_balance), evaluations (the temperatures tried), converged, and trace, the temperatures tried with their imbalance.

transmit(spectrum::Transmitted, radiation, continuum, r, Δr; cfrac=0.0)

The Transmitted after a zone at the distance r of the source and thickness Δr (cm), as XSTAR's heatt updates zrems: radiation is the field at the zone (point_source of spectrum.L) and continuum the result of opacity(::Continuum, …) (the opacity total and continuum, the emissivity of the recombination continua and the bremsstrahlung). In each bin the optical depth of the zone τ = κ Δr gives the factor fac = (1 - e^{-τ})/τ (1 below 0.01) and

L = max(0, L - (F κ - 4π (ε₁ + ε₂)) fac Δr 4π r²),   inward += 4π ε₁ fac Δr 4π r²,   outward += 4π ε₂ fac Δr 4π r²

with ε₁ = rccemis₁ + brems (1 - cfrac)/2 and ε₂ = rccemis₂ + brems (1 + cfrac)/2; the last two use the factor of the continuum opacity for inward_continuum and outward_continuum. XSTAR adds the bremsstrahlung, which is in all directions, to the emission per steradian of the recombination continua, so it is 4π too large in L and the sums.

velimp(n, l, T, ic, z1, rm, ne, sum)

Rate (s⁻¹) for the l-changing collision nl → nl-1 of a hydrogenic atom of ionic charge ic with ions of charge z1 and mass rm (electron masses), after Pengelly & Seaton (1964), for temperature T (K), electron density ne and total spontaneous decay rate sum of the level.

voigt(v, a)

The Voigt function H(a, v) of the line profile with the Doppler width as the unit of v and the damping parameter a, XSTAR's voigte (the approximation of Hui, Armstrong and Wray in the pieces that depend on a and v; exp(-v²) for a = 0).

xstar_energy_grid(ncn2=9999)

XSTAR's photon energy grid (its ener), in eV: ncn2 - max(2, ncn2/50) points spaced geometrically from 0.1 to 4×10⁵ eV, then max(2, ncn2/50) more from there to 10⁶ eV.