Production

Production#

Available Implementations#

Class

Argument name

Example Usage

NeukumProduction

“neukum”

production = Production.maker(“neukum”,version=”projectile”)

PowerLawProduction

“powerlaw”

production = Production.maker(“powerlaw”, slope=-4.0, N1_coef=1.0e-6)
class cratermaker.components.production.Production(quasimc_file=None, quasimc_craters=None, diameter_range=None, N_conversion_factor=None, D_conversion_factor=None, rng=None, rng_seed=None, rng_state=None, **kwargs)[source]#

Bases: ComponentBase

The base class for computing the production function for craters and projectiles.

classmethod maker(production=None, target=None, quasimc_file=None, quasimc_craters=None, diameter_range=None, N_conversion_factor=None, D_conversion_factor=None, rng=None, rng_seed=None, rng_state=None, **kwargs)[source]#

Initialize a Production model with the given name or instance.

Parameters:

  • production (str | Production | None, optional) – The production model to use. This can be either a string or a Production instance. If None, the default production model is “neukum” and the version is based on the target (if provided), either Moon, Mars, or Projectile for all other bodies. Default is “Moon”

  • target (Target | str | None, optional) – The target body for the impact. Can be a Target object or a string representing the target name.

  • quasimc_file (str | Path, optional) – Path to a file (CSV or NetCDF) containing the parameters used for craters emplaced using the quasi-Monte Carlo method. This file should contain at a minimum the diameter (or radius) of each crater, its location (lon, lat), and one of either production_time or production_D and production_N (D in km, N in units given by the N_conversion_factor attribute).

  • quasimc_craters (list[Crater], optional) – A list of Crater objects that are emplaced using the quasi-Monte Carlo method. This is an alternative to providing a quasimc_file. Only one of either quasimc_file or quasimc_craters should be provided.

  • diameter_range (PairOfFloats, optional) – The minimum and maximum crater diameter to sample from in meters. If not provided, the default is (0, inf), unless quasimc_file or quasimc_craters is provided, in which case the upper range will be set based on the smallest diameter in the quasi-Monte Carlo data.

  • N_conversion_factor (float, optional) – The conversion factor to apply to the N values in the quasi-Monte Carlo data to convert them to units of number per m². The default is 1e12, which represents number of craters per 10⁶ km²

  • D_conversion_factor (float, optional) – The conversion factor to apply to the D values in the quasi-Monte Carlo data to convert them to units of meters. The default is 1e3, which represents diameters in km.

  • rng (numpy.random.Generator | None) – A numpy random number generator. If None, a new generator is created using the rng_seed if it is provided.

  • rng_seed (Any type allowed by the rng_seed argument of numpy.random.Generator, optional) – The rng_seed for the RNG. If None, a new RNG is created.

  • rng_state (dict, optional) – The state of the random number generator. If None, a new state is created.

  • **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

Returns:

Production – An instance of the specified production model.

Raises:

  • KeyError – If the specified production model name is not found in the registry.

  • TypeError – If the specified production model is not a string or a subclass of Production.

  • ValueError – If there is an error initializing the production model.

Available models:

  • neukum

  • powerlaw

sample(time_start=None, time_end=None, diameter_number=None, diameter_number_end=None, diameter_range=None, area=None, return_age=True, **kwargs)[source]#

Sample diameters and ages from the production function.

This function can either sample from a given age range or from a given cumulative number/diameter pair (but not both).

Parameters:

  • time_start (FloatLike, optional) – Age in the past in units of My relative to the present, which is used compute the cumulative SFD.

  • time_end, FloatLike, optional – The ending age in units of My relative to the present, which is used to compute the cumulative SFD. The default is 0 (present day).

  • diameter_number (PairOfFloats, optional) – A pair of diameter and cumulative number values, in the form of a (D, N). If provided, the function convert this value to a corresponding age and use the production function for a given age.

  • diameter_number_end (PairOfFloats, optional) – A pair of diameter and cumulative number values, in the form of a (D, N). If provided, the function will convert this value to a corresponding reference age and use the production function for a given age.

  • diameter_range (PairOfFloats, optional) – The minimum and maximum crater diameter to sample from in meters. If not provided, the diameter_range value will be used.

  • area (FloatLike, optional) – The area in m² over which the production function is evaluated to generate the expected number, which is the production function over the input age/cumulative number range at the minimum diameter.

  • return_age (bool, optional) – If True, the function will return the sampled ages in addition to the diameters. The default is True.

  • **kwargs (Any) – Any additional keywords that are passed to the function method.

Returns:

  • numpy array – The sampled diameter values

  • numpy array or None – The sampled age values if return_age is True, otherwise None.

abstractmethod function(diameter=1.0, time_start=1.0, time_end=None, **kwargs)[source]#
age_from_D_N(diameter, cumulative_number_density, validate_inputs=True, **kwargs)[source]#

Return the age in My for a given number density of craters and diameter.

Parameters:

  • diameter (float-like or array-like) – diameter of the crater in m

  • cumulative_number_density (float-like or array-like) – number density of craters per m² surface area greater than the input diameter

  • validate_inputs (bool, optional) – If True, the function will validate the inputs. The default is True.

  • **kwargs (Any) – Any additional keywords that are passed to the function method.

Returns:

float_like or numpy array – The age in My for the given relative number density of craters.

D_from_N_age(cumulative_number_density, time_start, time_end=None, validate_inputs=True, **kwargs)[source]#

Return the diameter for a given number density of craters and age.

Parameters:

  • cumulative_number_density (float-like or array-like) – number density of craters per m² surface area greater than the input diameter

  • time_start (FloatLike or ArrayLike, default=1.0) – Age in the past in units of My relative to the present, which is used compute the cumulative SFD.

  • time_end, FloatLike or ArrayLike, optional – The ending age in units of My relative to the present, which is used to compute the cumulative SFD. The default is 0 (present day).

  • validate_inputs (bool, optional) – If True, the function will validate the inputs. The default is True.

  • **kwargs (Any) – Any additional keywords that are passed to the function method.

Returns:

float_like or numpy array – The diameter for the given number density and age.

abstractmethod chronology(time_start=1.0, time_end=0.0, validate_inputs=True, **kwargs)[source]#
abstractmethod csfd(diameter, **kwargs)[source]#
quasimc_merge(craters, time_start=None, time_end=None, N_D=None, N_D_end=None, **kwargs)[source]#

Merge a randomly-generated list of craters with the quasi-Monte Carlo craters over a given time interval.

read_quasimc_file(filename=None, **kwargs)[source]#

Reads in the quasi-Monte Carlo crater from file, processes the ages and sorts the crater list by age in order of decreasing age (increasing time) and computes production_time if present, production_ND if present, and will drop craters that have neither.

Parameters:

filename (Path | str | None, optional) – The path to the quasi-Monte Carlo file. If not provided, the Simulation must have a quasimc_file attribute set. This function will replace the stored quasimc_file attribute.

property generator_type#

The type of generator to use.

This can be either “crater” or “projectile”. This determines the nature of the production function, differentiating between ‘crater’ and ‘projectile’ types, which affect the calculations and interpretations of the production function.

property valid_time#

The range of ages over which the production function is valid. The range is given in My.

Returns:

tuple – The lower and upper bounds of the valid time range in My, or None if not applicable.

property quasimc_file#

File containing the quasi-Monte Carlo craters.

property quasimc_craters#

List of craters to be emplaced using quasi-Monte Carlo.

When assigned a list of Crater objects with production metadata (production_time, production_ND, and/or production_sequence), they will be processed to set their time values.

property diameter_range#

The lower and upper range of diameters that will be returned from sample().

property D_conversion_factor#

The conversion factor used to convert D in N(D) format into crater diameter in meters. The default value is 1e3, which corresponds to input diameter values in kilometers.

Only two options are allowed, 1 for units of m or 1000 for units of m. If None is provided, it will default to 1000 (km).

property D_unit#
property N_conversion_factor#

The conversion factor used to convert N in N(D) format into number of craters per m².

Only three options are allowed, 1.0 for units of ‘# per m²’, 1e6 for units of ‘# per km²’, or 1e12 for units of per 10⁶ km². The default value is 1e12.”

property N_unit#

Units of N in the N(D) format convention.

property N_D_units#

Units used in the N(D) format convention.

NeukumProduction#

See Production for inherited methods and attributes.

class cratermaker.components.production.neukum.NeukumProduction(version=None, rng=None, rng_seed=None, rng_state=None, **kwargs)[source]#

Bases: Production

An operations class for computing the the Neukum production function for the Moon and Mars.

Notes

The CSFD is computed using the model of Ivanov, Neukum, and Hartmann (2001) for the Moon and Mars, with minor changes. Notably, there is a typo in the chronology function (Eq. 5) of the original paper. The linear term in the paper is given as 8.38e-4. The value should be 10^(a0), and therefore the number given in the paper is based on the “Old” coefficients from Neukum (1983). The correct value is 10^(-3.0876) = 8.17e-4. We compute the value from the coefficients in our implementation of the chronology function.

The Mars production function is based on Ivanov (2001). The projectile production function is from Ivanov, Neukum, and Wagner (2001).

References

  • Neukum, G., Ivanov, B.A., Hartmann, W.K., 2001. Cratering Records in the Inner Solar System in Relation to the Lunar Reference System. Space Science Reviews, 96, 55-86. doi:10.1023/A:1011989004263

  • Ivanov, B.A., 2001. Mars/Moon Cratering Rate Ratio Estimates. Space Science Reviews, 96, 87-104. doi:10.1023/A:1011941121102

  • Ivanov, B.A., Neukum, G., Wagner, R., 2001. Size-Frequency Distributions of Planetary Impact Craters and Asteroids. In Collisional Processes in the Solar System, Springer Netherlands, Dordrecht, pp. 1-34. https://doi.org/10.1007/978-94-010-0712-2_1

  • Neukum, G., 1983. Meteorite bombardment and planetary surfaces dating. Habilitation Dissertation for Faculty Membership, University of Munich.

function(diameter=1.0, time_start=1.0, time_end=None, validate_inputs=True, **kwargs)[source]#

Return the cumulative size-frequency distribution of craters over a given age range and crater diameter.

Parameters:

  • diameter (FloatLike or numpy array) – Crater diameter(s) in units of meters to compute corresponding cumulative number density value.

  • time_start (FloatLike or ArrayLike, default=1.0) – Age in the past in units of My relative to the present, which is used compute the cumulative SFD.

  • time_end (FloatLike or ArrayLike, optional) – The ending age in units of My relative to the present, which is used to compute the cumulative SFD. The default is 0 (present day).

  • validate_inputs (bool, default=True) – If True, the function will check that the validity of age, time_end, and diameter arguments. If False, no check is performed, and the arguments are assumed to be valid. This can be used to speed up the function, particularly if it is called as part of a solver or optimization routine where the inputs are already known to be valid.

Returns:

FloatLike or numpy array of FloatLike – The cumulative number of craters per square meter greater than the input diameter that would be expected to form on a surface over the given age range.

chronology(time_start=1000.0, time_end=None, validate_inputs=True, **kwargs)[source]#

Returns the relative number of craters produced over a given age range.

This implements the chronology function given in Eq. 5 of Ivanov, Neukum, and Hartmann (2001) SSR v. 96 pp. 55-86, but takes in the age argument in the Cratermaker unit system of My instead of Gy.

Parameters:

  • age (ArrayLike, default=1000.0) – Age in the past relative to the present day to compute cumulative SFD in units of My.

  • time_end (ArrayLike, default=0.0) – The ending age in the past relative to the present day to compute cumulative SFD in units of My. The default is 0 (present day).

  • validate_inputs (bool, default=True) – If True, the function will check that the age is within the valid range of ages for this production function. If False, no check is performed.

Returns:

NDArray – The number of craters relative to the amount produced in the last 1 My between age and ange_end.

property valid_versions#

The valid versions of the production function.

Returns:

list – The valid versions of the production function.

property generator_type#

Get the generator type of the production function.

Returns:

str – The generator type of the production function.

property version#

Get the version of the production function.

Returns:

str – The version of the production function.

property sfd_tables#

Get the table of coefficients for the production function.

Returns:

dict – The table of coefficients for the production function.

property sfd_coef#

Get the table of coefficients for the production function.

Returns:

list – The table of SFD coefficients for the production function.

property Clin#

Get the linear coefficient for the production function.

Returns:

float – The linear coefficient for the production function.

property Cexp#

Get the exponential coefficient for the production function.

Returns:

float – The exponential coefficient for the production function.

property tau#

Get the time constant for the production function.

Returns:

float – The time constant for the production function.

property sfd_range#

The range of diameters over which the SFD is valid. The range is given in m.

Returns:

tuple – The lower and upper bounds of the SFD range in m.

property valid_time#

The range of ages over which the production function is valid. The range is given in My.

Returns:

tuple – The lower and upper bounds of the valid time range in My.

csfd(diameter)[source]#

Return the cumulative size frequency distribution of craters at a given age relative to age = 1 My ago per m².

Parameters:

diameter (FloatLike or ArrayLike) – units of meter

Returns:

FloatLike or numpy array – Cumulative number density of per square meter greater than the input diameter.

Usage example#

1 from cratermaker import Production
2 production = Production.maker("neukum", version="projectile")

PowerLawProduction#

See Production for inherited methods and attributes.

class cratermaker.components.production.powerlaw.PowerLawProduction(generator_type='crater', N1_coef=None, slope=None, rng=None, rng_seed=None, rng_state=None, **kwargs)[source]#

Bases: Production

An operations class for computing the production function for craters and projectiles.

This impliments a very simple power law production function that can be used as either a crater or projectile production function. The production function is defined as the cumulative number of craters greater than a given diameter per unit m² surface area.

function(diameter=1.0, time_start=1.0, time_end=None, validate_inputs=True, **kwargs)[source]#

Return the cumulative size-frequency distribution of craters over a given age range and crater diameter for a simple power law model.

Parameters:

  • diameter (FloatLike or ArrayLike) – Crater diameter(s) in units of meters to compute corresponding cumulative number density value.

  • time_start (FloatLike or ArrayLike, default=1.0) – Age in the past in units of My relative to the present, which is used compute the cumulative SFD.

  • time_end (FloatLike or ArrayLike, optional) – The ending age in units of My relative to the present, which is used to compute the cumulative SFD. The default is 0 (present day).

  • validate_inputs (bool, default=True) – If True, the function will check that the validity of time_start, time_end, and diameter arguments. If False, no check is performed, and the arguments are assumed to be valid. This can be used to speed up the function, particularly if it is called as part of a solver or optimization routine where the inputs are already known to be valid.

  • **kwargs (Any) – Any additional keywords. These are not used in this base class, but included here so that any extended class can share the same function signature.

Returns:

FloatLike or numpy array of FloatLike – The cumulative number of craters per square meter greater than the input diameter that would be expected to form on a surface over the given age range.

chronology(time_start=1000.0, time_end=None, validate_inputs=True, **kwargs)[source]#

The chronology function, which returns the number of craters relative to the amount produced in the last 1 My.

Parameters:

  • time_start (FloatLike or ArrayLike, default=1.0) – Age in the past relative to the present day to compute cumulative SFD in units of My.

  • time_end (FloatLike or ArrayLike, optional) – The ending age in units of My relative to the present, which is used to compute the cumulative SFD. The default is 0 (present day).

  • validate_inputs (bool, default) – If True, the function will check that the validity of age and time_end arguments. If False, no check is performed, and the arguments are assumed to be valid. This can be used to speed up the function, particularly if it is called as part of a solver or optimization routine where the inputs are already known to be valid.

  • **kwargs (Any) – Any additional keywords that are passed to the function method.

Returns:

NDArray – The number of craters relative to the amount produced in the last 1 My.

Notes

For a simple power law production function, the chronology function assumes a constant impact rate and so crater accumulation is linear with time. Therefore, the chronology function is simply the ratio of the cumulative SFD at the given age to the cumulative SFD at 1 My.

csfd(diameter, **kwargs)[source]#

The cumulative size frequency distribution of craters at a given age relative to age = 1 My ago per m².

Parameters:

diameter (FloatLike or ArrayLike) – units of meter

Returns:

FloatLike or numpy array – Cumulative number density of per square meter greater than the input diameter.

property N1_coef#

The N1 coefficient of the power law production function.

property slope#

The slope of the power law production function.

Usage example#

1 from cratermaker import Production
2 production = Production.maker("powerlaw", slope=-4.0, N1_coef=1.0e-6)