flux

Thermal and Reflected light modeling tools.

This includes computations such as NEATM, FRM, and reflection models.

Modeling is broken into catagories of complexity, ranging from pure black body calculations, through to telescope specific models. Picking the appropriate model can save significant development time, but removes some of the control for the user.

An example of this is the NeatmParams class, which defines a joint NEATM and optical reflected light model. This can be broken up into distinct steps by the user, however it provides convenience functions which are automatically parallelized, leading to significant performance gains.

If you are interested in IR modeling, it is recommended to start with NeatmParams or FrmParams. If optical wavelengths are the goal, then starting with the hg_apparent_mag() or hg_apparent_flux() is probably appropriate.

There are a number of functions provided more for pedagogical reasons, typically it is recommended not to use these directly in most cases: -frm_flux() -neatm_flux() -lambertian_flux() -frm_facet_temps() -neatm_facet_temps()

class kete.flux.FrmParams(desig, band_wavelength, band_albedos, h_mag=None, diam=None, vis_albedo=None, g_param=0.15, c_hg=None, emissivity=0.9, zero_mags=None)

FRM Model parameters.

This holds the model parameters for FRM. By definition, providing any two of the following fully define the third:

H-magnitude
Diameter
Visible geometric albedo

For ease of use, this class requires only two of any of those values to be provided, and the third is computed automatically. If all 3 are provided it will validate that they are internally consistent, and raise an exception if not.

Parameters:

desig – Name of the object.
band_wavelength – List of effective wavelengths in nm.
band_albedos – List of albedoes of the object for each wavelength (0-1).
h_mag – H magnitude of the object in the HG system.
diam – Diameter of the object in km.
vis_albedo – Visible geometric albedo of the object.
g_param – G phase coefficient, defaults to 0.15.
c_hg – The C_hg constant used to define the relationship between diameter, albedo, and H mag. This uses the default value defined in the constants, and is not recommended to be changed.
emissivity – Emissivity of the object, defaults to 0.9.
zero_mags – Optional - If zero mags are provided then magnitudes may be computed.

band_albedos: List of albedoes of the object, one for each band.

band_wavelength: List of effective wavelengths in nm.

desig: Name of the object

diam: Diameter of the object in km.

emissivity: Emissivity of the object.

evaluate(sun2obj_vecs, sun2obs_vecs)

Evaluate the thermal model at the provided observer and object positions.

This returns a list of [ModelResults] for the computed fluxes/magnitudes. This is a multi-core operation.

Parameters:

sun2obj_vecs – A list of [Vector] like objects which define the position of the object with respect to the sun.
sun2obs_vecs – A list of [Vector] like objects which define the position of the observer with respect to the sun.

g_param: G Phase parameter.

h_mag: H Mag for the object in the HG system.

static load(filename): Load results from a binary file.

static load_list(filename): Load a list from a binary file.

static new_neos(desig, band_albedos, h_mag=None, diam=None, vis_albedo=None, g_param=0.15, c_hg=None, emissivity=0.9)

Create a new FrmParams with NEOS bands and zero magnitudes. This requires 2 albedos to be provided, one for each band.

Parameters:

desig – Name of the object.
band_albedos – List of albedoes of the object for each wavelength (0-1).
h_mag – H magnitude of the object in the HG system.
diam – Diameter of the object in km.
vis_albedo – Visible geometric albedo of the object.
g_param – G phase coefficient, defaults to 0.15.
c_hg – The C_hg constant used to define the relationship between diameter, albedo, and H mag. This uses the default value defined in the constants, and is not recommended to be changed.
emissivity – Emissivity of the object, defaults to 0.9.

static new_wise(desig, band_albedos, h_mag=None, diam=None, vis_albedo=None, g_param=0.15, c_hg=None, emissivity=0.9)

Create a new FrmParams with WISE bands and zero magnitudes for 300k objects. This requires all 4 albedos to be provided.

Parameters:

desig – Name of the object.
band_albedos – List of albedoes of the object for each wavelength (0-1).
h_mag – H magnitude of the object in the HG system.
diam – Diameter of the object in km.
vis_albedo – Visible geometric albedo of the object.
g_param – G phase coefficient, defaults to 0.15.
c_hg – The C_hg constant used to define the relationship between diameter, albedo, and H mag. This uses the default value defined in the constants, and is not recommended to be changed.
emissivity – Emissivity of the object, defaults to 0.9.

save(filename): Save results to a binary file.

static save_list(vec, filename): Save a list to a binary file.

vis_albedo: Albedo in V band.

zero_mags: List of the zero mags for each band if provided.

class kete.flux.ModelResults(fluxes, thermal_fluxes, hg_fluxes, v_band_magnitude, v_band_flux, magnitudes=None)

Reflected/Thermal model results.

Parameters:

fluxes – Total fluxes per band in units of Jy / Steradian.
thermal_fluxes – Black body specific fluxes per band in units of Jy / Steradian.
hg_fluxes – Reflected light specific fluxes per band in units of Jy / Steradian.
v_band_magnitude – Expected magnitude in the V-band using the HG model.
v_band_flux – Expected flux in the V-band using the HG model.
magnitudes – Magnitudes in the different bands if zero mags were available.

fluxes: Total fluxes per band in units of Jy / Steradian.

hg_fluxes: Reflected light specific fluxes per band in units of Jy / Steradian.

static load(filename): Load results from a binary file.

static load_list(filename): Load a list from a binary file.

magnitudes: Magnitudes in the different bands if zero mags were available.

save(filename): Save results to a binary file.

static save_list(vec, filename): Save a list to a binary file.

thermal_fluxes: Black body specific fluxes per band in units of Jy / Steradian.

v_band_flux: Expected flux in the V-band using the HG model.

v_band_magnitude: Expected magnitude in the V-band using the HG model.

class kete.flux.NeatmParams(desig, band_wavelength, band_albedos, h_mag=None, diam=None, vis_albedo=None, beaming=1.0, g_param=0.15, c_hg=None, emissivity=0.9, zero_mags=None)

NEATM Model parameters.

This holds the model parameters for NEATM. By definition, providing any two of the following fully define the third:

H-magnitude
Diameter
Visible geometric albedo

For ease of use, this class requires only two of any of those values to be provided, and the third is computed automatically. If all 3 are provided it will validate that they are internally consistent, and raise an exception if not.

Parameters:

desig – Name of the object.
band_wavelength – List of effective wavelengths in nm.
band_albedos – List of albedoes of the object for each wavelength (0-1).
h_mag – H magnitude of the object in the HG system.
diam – Diameter of the object in km.
vis_albedo – Visible geometric albedo of the object.
beaming – Beaming parameter, defaults to 1.0.
g_param – G phase coefficient, defaults to 0.15.
c_hg – The C_hg constant used to define the relationship between diameter, albedo, and H mag. This uses the default value defined in the constants, and is not recommended to be changed.
emissivity – Emissivity of the object, defaults to 0.9.
zero_mags – Optional - If zero mags are provided then magnitudes may be computed.

band_albedos: List of albedoes of the object, one for each band.

band_wavelength: List of effective wavelengths in nm.

beaming: Beaming parameter.

desig: Name of the object

diam: Diameter of the object in km.

emissivity: Emissivity of the object.

evaluate(sun2obj_vecs, sun2obs_vecs)

Evaluate the thermal model at the provided observer and object positions.

This returns a list of [ModelResults] for the computed fluxes/magnitudes. This is a multi-core operation.

Parameters:

sun2obj_vecs – A list of [Vector] like objects which define the position of the object with respect to the sun.
sun2obs_vecs – A list of [Vector] like objects which define the position of the observer with respect to the sun.

g_param: G Phase parameter.

h_mag: H Mag for the object in the HG system.

static load(filename): Load results from a binary file.

static load_list(filename): Load a list from a binary file.

static new_neos(desig, band_albedos, h_mag=None, diam=None, vis_albedo=None, beaming=1.0, g_param=0.15, c_hg=None, emissivity=0.9)

Create a new NeatmParams with NEOS bands and zero magnitudes. This requires 2 albedos to be provided, one for each band.

Parameters:

desig – Name of the object.
band_albedos – List of albedoes of the object for each wavelength (0-1).
h_mag – H magnitude of the object in the HG system.
diam – Diameter of the object in km.
vis_albedo – Visible geometric albedo of the object.
beaming – Beaming parameter, defaults to 1.0.
g_param – G phase coefficient, defaults to 0.15.
c_hg – The C_hg constant used to define the relationship between diameter, albedo, and H mag. This uses the default value defined in the constants, and is not recommended to be changed.
emissivity – Emissivity of the object, defaults to 0.9.

static new_wise(desig, band_albedos, h_mag=None, diam=None, vis_albedo=None, beaming=1.0, g_param=0.15, c_hg=None, emissivity=0.9)

Create a new NeatmParams with WISE bands and zero magnitudes for 300k objects. This requires all 4 albedos to be provided.

Parameters:

desig – Name of the object.
band_albedos – List of albedoes of the object for each wavelength (0-1).
h_mag – H magnitude of the object in the HG system.
diam – Diameter of the object in km.
vis_albedo – Visible geometric albedo of the object.
beaming – Beaming parameter, defaults to 1.0.
g_param – G phase coefficient, defaults to 0.15.
c_hg – The C_hg constant used to define the relationship between diameter, albedo, and H mag. This uses the default value defined in the constants, and is not recommended to be changed.
emissivity – Emissivity of the object, defaults to 0.9.

save(filename): Save results to a binary file.

static save_list(vec, filename): Save a list to a binary file.

vis_albedo: Albedo in V band.

zero_mags: List of the zero mags for each band if provided.

kete.flux.black_body_flux(temp, wavelength)

Compute the black body flux at the specified temperatures and wavelength.

Flux is in units Janskys / steradian per unit freq. This can be converted to being per unit wavelength by multiplying the result of this by c / wavelength**2.

This is limited by the size of float 32s, numbers exceeding 1e-300 will be rounded to 0. This should not raise any warnings, and should be relatively numerically stable and correct over most domains of interest.

Parameters:

temp – List of temperatures, in units of Kelvin.
wavelength – In units of nanometers.

Returns:

Janskys per steradian

Return type:

List

kete.flux.comet_apparent_mags(sun2obj, sun2obs, mk_1=None, mk_2=None, phase_corr=Ellipsis)

Given the M1/K1 and M2/K2 values, compute the apparent Comet visible magnitudes.

The model for apparent magnitudes are:

m1 + k1 * log10(sun2obj.r) + 5.0 * log10(obj2obs.r) + phase_mag_slope_1 * phase m2 + k2 * log10(sun2obj.r) + 5.0 * log10(obj2obs.r) + phase_mag_slope_2 * phase

Where m1/k1 are related to total magnitudes and m2/k2 are nucleus magnitudes.

This model is based off of these: https://ssd.jpl.nasa.gov/horizons/manual.html#obsquan (see section 9) https://en.wikipedia.org/wiki/Absolute_magnitude#Cometary_magnitudes

Note that the above model does not include a 2.5x term attached to the K1/2 terms which are present in the wikipedia definition, this matches the definitions used by JPL Horizons.

Note that this includes seperate phase magnitude slope for both the nucleus and total fluxes.

This does a best effort to compute both magnitudes, if any values are missing this will return None in the respective calculation.

Parameters:

sun2obj – A vector-like object containing the X/Y/Z coordinates pointing to the object from the sun in units of AU.
sun2obs – A vector-like object containing the X/Y/Z coordinates pointing from the sun to the observer in units of AU.
mk_1 – Tuple of (M_1, K_1), where M_1 is the total Absolute magnitude of the comet, and K_1 magnitude slope as a function of heliocentric distance.
mk_2 – Tuple of (M_2, K_2), where M_2 is the total Absolute magnitude of the nucleus, and K_2 nucleus magnitude slope as a function of heliocentric distance.
phase_corr – Magnitude variation of the comet as a function of observing phase, units are Mag/Deg of phase, this defaults to 0.0 for the total magnitude, and 0.035 Mag/Deg for the nucleus.

Returns:

(Total apparent magnitude, Magnitude of the nucleus)

Return type:

float

kete.flux.frm_facet_temps(facet_normals, subsolar_temp, obj2sun)

Calculate the temperatures of each facet assuming the FRM model.

This is a multi-core operation.

Parameters:

facet_normals – List of surface normal vectors.
subsolar_temp – Temperature at the sub-solar point in kelvin.
obj2sun – Vector from the object to the sun in AU.

kete.flux.frm_flux(sun2obj, sun2obs, v_albedo, g_param, diameter, wavelength, emissivity=0.9)

Calculate the flux from an object using the FRM thermal model in Jansky.

This is a slightly simplified FRM model, where the pole is assumed to be in the ecliptic Z direction.

See Thermal Model

Parameters:

sun2obj (Vector) – A vector-like object containing the X/Y/Z coordinates pointing from the sun to the object in units of AU.
sun2obs (Vector) – A vector-like object containing the X/Y/Z coordinates pointing from the sun to the observer in units of AU.
v_albedo (float) – The V geometric albedo of the object.
g_param (float) – The G parameter of the object
diameter (float) – The diameter of the object in km.
wavelength (float) – The wavelength of the object in nanometers.
emissivity (float) – The emissivity of the object, defaults to 0.9.

Returns:

Flux in units of Jy.

Return type:

float

kete.flux.hg_apparent_flux(sun2obj, sun2obs, g_param, wavelength, v_albedo, h_mag=None, diameter=None, c_hg=None)

Calculate the reflected flux from an object using the HG asteroid model.

This assumes that the object is an ideal disk facing the sun and applies the IAU correction curve to the reflected light, returning units of Jy per unit frequency.

This treats the sun as a flat black body disk, which is a good approximation as long as the object is several solar radii away.

Either h_mag or diameter must be provided, but only 1 is strictly required. The other will be computed if not provided.

Parameters:

sun2obj – A vector-like object containing the X/Y/Z coordinates pointing from the sun to the object in units of AU.
sun2obs – A vector-like object containing the X/Y/Z coordinates pointing from the sun to the observer in units of AU.
g_param – The G parameter of the object.
wavelength – The wavelength of the object in nanometers.
v_albedo – The geometric albedo of the object at the specified wavelength.
h_mag – H magnitude of the object in V band.
diameter – The diameter of the object in km.
c_hg – The relationship constant between H, D, and pV for the bandpass. Defaults to 1329.0.

Returns:

Flux in Jy per unit frequency.

Return type:

float

kete.flux.hg_apparent_mag(sun2obj, sun2obs, h_mag, g_param)

Compute the apparent magnitude of an object using the absolute magnitude H, G, and positional information.

The HG IAU model is not technically defined above 120 degrees phase, however this will continue to return values fit to the model until 160 degrees. Phases larger than 160 degrees will return nan.

Parameters:

sun2obj – A vector-like object containing the X/Y/Z coordinates pointing from the sun to the object in units of AU.
sun2obs – A vector-like object containing the X/Y/Z coordinates pointing from the sun to the observer in units of AU.
G – The G parameter of the object.
H – The absolute magnitude of the object.

Returns:

The apparent magnitude of the object.

Return type:

float

kete.flux.hg_phase_curve_correction(g_param, phase_angle)

This computes the phase curve correction in the IAU format.

Parameters:

g_param – The G parameter of the object.
phase_angle – The angular separation between the sun and observer as viewed from the object, units of degrees.

Returns:

The phase curve correction.

Return type:

float

kete.flux.lambertian_flux(facet_flux, facet_normals, obs2obj, diameter, emissivity)

Calculate the visible flux at the observer assuming a convex faceted object made up of a collection of lambertian surfaces.

Parameters:

facet_flux – Flux from each of the facets in Jy / Steradian per unit freq.
facet_normals – List of surface normal vectors.
obs2obj – Vector from the observer to the object in AU.
diameter – Diameter of the object in km.
emissivity – Emissivity of the lambertian surfaces (between 0 and 1, 0.9 is a good default).

kete.flux.neatm_facet_temps(facet_normals, subsolar_temp, obj2sun)

Calculate the temperatures of each facet assuming the NEATM model.

This is a multi-core operation.

Parameters:

facet_normals – List of surface normal vectors.
subsolar_temp – Temperature at the sub-solar point in kelvin.
obj2sun – Vector from the object to the sun in AU.

kete.flux.neatm_flux(sun2obj, sun2obs, v_albedo, g_param, beaming, diameter, wavelength, emissivity=0.9)

Calculate the flux in Janskys from an object using the NEATM thermal model.

See Thermal Model

Parameters:

sun2obj – A vector-like object containing the X/Y/Z coordinates pointing from the sun to the object in units of AU.
sun2obs – A vector-like object containing the X/Y/Z coordinates pointing from the sun to the observer in units of AU.
v_albedo – The V geometric albedo of the object.
g_param – The G parameter of the object
beaming – The beaming parameter.
diameter – The diameter of the object in km.
wavelength – The wavelength of the object in nanometers.
emissivity – The emissivity of the object, defaults to 0.9.

Returns:

Flux in units of Jy.

Return type:

float

kete.flux.solar_flux(dist, wavelength)

Return the Solar flux in Jy / Steradian from the 2000 ASTM Standard Extraterrestrial Spectrum Reference E-490-00: <https://www.nrel.gov/grid/solar-resource/spectra-astm-e490.html>

Returned values are units Janskys / steradian per unit freq.

Parameters:

dist – Distance the object is from the Sun in au.
wavelength – Wavelength in nm.

kete.flux.sub_solar_temperature(obj2sun, geom_albedo, g_param, beaming, emissivity=0.9)

Compute the subsolar surface temperature in kelvin.

Parameters:

obj2sun – Vector from the object to the sun in AU.
geom_albedo – Geometric albedo.
g_param – G Phase parameter in the HG system.
beaming – The beaming parameter of the object.
emissivity – Emissivity of the object, 0.9 by default.

shape

Definitions of geometric objects which are used by the thermal and reflected light models.

class kete.shape.Geometry(normals, areas, normalize_area=True)

Generic representation of the geometry of an object made up of planar sections with fixed area.

Parameters:

normals (ArrayLike) – A list of vectors which define the normals for each planar surface. These are automatically normalized to unit length. This can be a numpy array of shape (n, 3)
areas (ArrayLike) – A list of the surface areas associated with the normals, this must be the same length as the normals list.
normalize_area (bool) – Whether or not to normalize all of the areas so that the total is 1.

property areas: ndarray: The area of each of the faces of this geometry, this must be the same length as the normals.

property normals: ndarray: The normal vectors associated with the faces of this geometry. This must be the same length as the areas of this geometry.

class kete.shape.TriangleEllipsoid(n_div=6, x_scale=1, y_scale=1, z_scale=1)

A simple ellipsoid/sphere made up of triangle facets.

This is a subclass of TriangleFaceted which constructs an approximate Ellipsoid geometry out of triangle facets.

See https://arxiv.org/abs/1502.04816

Parameters:

n_div (int) – The number of divisions.
x_scale (float) – Scaling parameter along the x-axis, all x-values are multiplied by this.
y_scale (float) – Scaling parameter along the y-axis, all y-values are multiplied by this.
z_scale (float) – Scaling parameter along the z-axis, all z-values are multiplied by this.

Examples

(Source code, png, hires.png, pdf)

Here is a triangle ellipsoid with n_div=6.

property areas: ndarray: The area of each of the faces of this geometry, this must be the same length as the normals.

property facets: ndarray: A (n, 3, 3) array of all of the facet corners in this geometry.

property normals: ndarray: The normal vectors associated with the faces of this geometry. This must be the same length as the areas of this geometry.

class kete.shape.TriangleFaceted(facets, normalize_area=True)

Constructed object from a list of triangular facets.

Parameters:

facets (ArrayLike) – A list of facets, where a facet is a length 3 collection of 3 vectors, equivalently this can be a numpy array of shape (n, 3, 3). These 3 vectors must define a triangle which make up the facet.
normalize_area (bool) – This determines of the total surface area should be normalized to 1.

property areas: ndarray: The area of each of the faces of this geometry, this must be the same length as the normals.

property facets: ndarray: A (n, 3, 3) array of all of the facet corners in this geometry.

property normals: ndarray: The normal vectors associated with the faces of this geometry. This must be the same length as the areas of this geometry.