diff --git a/README.md b/README.md index 7f24b2a..88c137d 100644 --- a/README.md +++ b/README.md @@ -7,24 +7,99 @@ Performance Portable Opacity and Emissivity library for simulation codes ## API -singularity-opac provides a uniform API for all opacity models. The following functions are provided -(here, `\sigma` is the frequency- and angle-dependent cross section in units of `cm^2`): +singularity-opac provides a uniform API for all opacity models, in two forms: frequency-dependent, and frequency-averaged (Plank or Rosseland means), and separately for absorption and scattering opacities. + +For frequency-dependent absorption opacities, the following functions are provided +(here, $\sigma$ is the frequency- and angle-dependent cross section in units of ${\rm cm}^2$): +| Function | Expression | Description | Units | +| --------------------- | ---------- | --------------------- | ------- | +| AbsorptionCoefficient | $n \sigma$ | Absorption coefficient | ${\rm cm}^{-1}$ | +| AngleAveragedAbsorptionCoefficient | $\frac{1}{4 \pi}\int n \sigma d\Omega$ | Absorption coefficient averaged over solid angle | ${\rm cm}^{-1}$ | +| EmissivityPerNuOmega | $j_{\nu} = \frac{dE}{d^3x dt d\Omega d\nu}$ | Frequency- and angle-dependent emissivity | ${\rm erg}{\rm cm}^{-3}{\rm s}^{-1}{\rm Hz}^{-1}{\rm Sr}^{-1}$ | +| EmissivityPerNu | $\int j_{\nu} d\Omega$ | Frequency-dependent emissivity | ${\rm erg}{\rm cm}^{-3}{\rm s}^{-1}{\rm Hz}^{-1}$ | +| Emissivity | $\int j_{\nu} d\nu d\Omega$ | Total emissivity | ${\rm erg}{\rm cm}^{-3}{\rm s}^{-1}$ | +| NumberEmissivity | $\int \frac{1}{h \nu} j_{\nu} d\Omega d\nu$ | Total number emissivity | ${\rm cm}^{-3}{\rm s}^{-1}$ | +| ThermalDistributionOfTNu | $B_{\nu} = \frac{dE}{dA dt d\Omega d\nu}$ | Specific intensity of thermal distribution | ${\rm erg}{\rm cm}^{-2}{\rm s}^{-1}{\rm Sr}^{-1}{\rm Hz}^{-1}$ | +| DThermalDistributionOfTNuDT | $dB_{\nu}/dT$ | Temperature derivative of specific intensity of thermal distribution | ${\rm erg}{\rm cm}^{-2}{\rm s}^{-1}{\rm Sr}^{-1}{\rm Hz}^{-1}{\rm K}^{-1}$ | +| ThermalDistributionOfT | $B = \int B_{\nu} d\Omega d\nu$ | Frequency- and angle-integrated intensity of thermal distribution | ${\rm erg}{\rm cm}^{-2}{\rm s}^{-1}$ | +| ThermalNumberDistributionOfT | $B = \int \frac{1}{h \nu} B_{\nu} d\Omega d\nu$ | Frequency- and angle-integrated intensity of thermal distribution | ${\rm erg}{\rm cm}^{-2}{\rm s}^{-1}$ | +| EnergyDensityFromTemperature | $E_{\rm R}$ | Radiation energy density | ${\rm erg}{\rm cm}^{-3}$ | +| TemperatureFromEnergyDensity | $T_{\rm R}$ | Radiation temperature | ${\rm K}$ | +| NumberDensityFromTemperature | $n_{\rm R}$ | Radiation number density | ${\rm cm}^{-3}$ | + +with the following function signatures: + + AbsorptionCoefficient(density, temperature, frequency) + AngleAveragedAbsorptionCoefficient(density, temperature, frequency) + EmissivityPerNuOmega(density, temperature, frequency) + EmissivityPerNu(density, temperature, frequency) + Emissivity(density, temperature) + NumberEmissivity(density, temperature) + ThermalDistributionOfTNu(temperature, frequency) + DThermalDistribtuionOfTNuDT(temperature, frequency) + ThermalDistributionOfT(temperature) + ThermalNumberDistributionOfT(temperature) + EnergyDensityFromTemperature(temperature) + TemperatureFromEnergyDensity(radiation energy density) + NumberDensityFromTemperature(temperature) + +For mean absorption opacities, the following functions are provided: +| Function | Expression | Description | Units | +| --------------------- | ---------- | --------------------- | ------- | +| PlankMeanAbsorptionCoefficient | $n \sigma$ | Absorption coefficient | ${\rm cm}^{-1}$ | +| RosselandMeanAbsorptionCoefficient | $n \sigma$ | Absorption coefficient | ${\rm cm}^{-1}$ | +| AbsorptionCoefficient | $n \sigma$ | Absorption coefficient | ${\rm cm}^{-1}$ | +| Emissivity | $\int j_{\nu} d\nu d\Omega$ | Total emissivity | ${\rm erg}{\rm cm}^{-3}{\rm s}^{-1}$ | + +with the following function signatures: + + PlanckMeanAbsorptionCoefficient(density, temperature) + RosselandMeanAbsorptionCoefficient(density, temperature) + AbsorptionCoefficient(density, temperature, gmode [Planck, Rosseland]) + Emissivity(density, temperature) + +For frequency-dependent scattering opacities, the following functions are provided +| Function | Expression | Description | Units | +| --------------------- | ---------- | --------------------- | ------- | +| TotalCrossSection | $\sigma$ | Scattering cross section | ${\rm cm}^{2}$ | +| DifferentialCrossSection | $d\sigma / d \Omega $ | Differential scattering cross section | ${\rm cm}^{2}{\rm Sr}^{-1}$ | +| TotalScatteringCoefficient | $n \sigma $ | Scattering coefficient | ${\rm cm}^{-1}$ | + +with the following function signatures: + + TotalCrossSection(density, temperature, frequency) + DifferentialCrossSection(density, temperature, frequency, cos(theta)) + TotalScatteringCoefficient(density, temperature, frequency) + +For mean scattering opacities, the following functions are provided: | Function | Expression | Description | Units | | --------------------- | ---------- | --------------------- | ------- | -| AbsorptionCoefficient | `n \sigma` | Absorption coefficient | `cm^{-1}` | -| AngleAveragedAbsorptionCoefficient | `\frac{1}{4 \pi}\int n \sigma d\Omega` | Absorption coefficient averaged over solid angle | `cm^{-1}` | -| EmissivityPerNuOmega | `j_{\nu} = \frac{dE}{d^3x dt d\Omega d\nu}` | Frequency- and angle-dependent emissivity | `erg cm^{-3} s^{-1} Sr^{-1} Hz^{-1}` | -| EmissivityPerNu | `\int j_{\nu} d\Omega` | Frequency-dependent emissivity | `erg cm^{-3} s^{-1} Hz^{-1}` | -| Emissivity | `\int j_{\nu} d\nu d\Omega` | Total emissivity | `erg cm^{-3} s^{-1}` | -| NumberEmissivity | `\int \frac{1}{h \nu} j_{\nu} d\Omega d\nu` | Total number emissivity | `cm^{-3} s^{-1}` | -| ThermalDistributionOfTNu | `B_{\nu} = \frac{dE}{dA dt d\Omega d\nu}` | Specific intensity of thermal distribution | `erg cm^{-2} s^{-1} Sr^{-1} Hz^{-1}` | -| DThermalDistributionOfTNuDT | `dB_{\nu}/dT` | Temperature derivative of specific intensity of thermal distribution | `erg cm^{-2} s^{-1} Sr^{-1} Hz^{-1} K^{-1}` | -| ThermalDistributionOfT | `B = \int B_{\nu} d\Omega d\nu` | Frequency- and angle-integrated intensity of thermal distribution | `erg cm^{-2} s^{-1}` | -| ThermalNumberDistributionOfT | `B = \int \frac{1}{h \nu} B_{\nu} d\Omega d\nu` | Frequency- and angle-integrated intensity of thermal distribution | `erg cm^{-2} s^{-1}` | +| PlanckMeanScatteringCoefficient | $n \sigma$ | Planck mean scattering coefficient | ${\rm cm}^{-1}$ | +| RosselandMeanScatteringCoefficient | $n \sigma$ | Rosseland mean scattering coefficient | ${\rm cm}^{-1}$ | + +with the following function signatures: + + PlanckMeanScatteringCoefficient(density, temperature) + RosselandMeanScatteringCoefficient(density, temperature) Note that the thermal radiation energy density `u = 1/c ThermalDistributionOfT` and the thermal radiation number density `n = 1/c ThermalNumberDistributionOfT`. -Internally singularity-opac always uses CGS units, as in the above table. However, arbitrary units are supported through the units modifier. +Opacity variant constructors are specific to the opacity model being requested; consult the source code for +individual opacities. + +Internally singularity-opac always uses CGS units, as in the above table. However, arbitrary units are supported through the units modifier, which accepts +function argument inputs in the arbitrary unit system, and returns the result from the function in those same arbitrary units. For example, a gray absorption opacity in non-cgs units specified by `time_unit`, `mass_unit`, `length_unit`, and `temp_unit` conversion factors from code to CGS units (e.g. `mass_cgs = mass_unit * mass_code`) +is created as + + photons::Opacity noncgs_opacity = photons::NonCGSUnits( + photons::Gray(kappa), time_unit, mass_unit, length_unit, temp_unit); + +Note that neutrino opacity functions also include electron fraction and RadiationType species arguments. + +Frequency-dependent emissition and absorption functions do not currently support angle dependence. + +A struct of runtime physical constants is provided for optional consistency with internal operations by the +`GetRuntimePhysicalConstants()` method. ## To Build