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, compute_time=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.

  • compute_time (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 Production.function().

Returns:

  • numpy array – The sampled diameter values

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

compute_time(diameters, time_start, time_end=0.0, **kwargs)[source]#

Compute the ages of craters with given diameters based on the production function.

Parameters:

  • diameters (ArrayLike) – The diameters of the craters in meters.

  • time_start (float) – The starting age in My relative to the present, which is used to compute the cumulative SFD.

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

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

Returns:

numpy array – The computed ages for the given diameters, sorted in order of decreasing age.

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 Production.function().

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 Production.function().

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.

It will extract any craters from quasimc_craters that have time values that overlap those of the arguments. Then it will successively check the to see if any in the “craters” list are larger than the largest in

Parameters:

  • craters (list[Crater]) – The list of Crater objects to merge with the quasi-Monte Carlo craters.

  • time_start (float, optional) – The starting time in units of My relative to the present in which to extract the quasi-Monte Carlo craters.

  • time_end (float, optional) – The ending time in units of My relative to the present in which to extract the quasi-Monte Carlo craters.

  • N_D (PairOfFloats, optional) – A pair of D, N values that represent the N(D) format for the cumulative number density at the start of the sample, which is used to extract the quasi-Monte Carlo craters. The units given by N_D_units and can be adjusted by setting D_conversion_factor and N_conversion_factor.

  • N_D_end (PairOfFloats, optional) – A pair of D, N values that represent the N(D) format for the cumulative number density at the end of the sample, which is used to extract the quasi-Monte Carlo craters. The units given by N_D_units and can be adjusted by setting D_conversion_factor and N_conversion_factor.

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

Returns:

list[Crater] – The merged list of Crater objects, sorted in order of decreasing age.

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.

When assigned, the file will be read and processed to set the quasimc_craters list. The file must be in a format that can be read by the Crater.from_file() method, and the craters must have production metadata (production_time, production_ND, and/or production_sequence) to be included in the quasimc_craters list. When accessed, it will return the Path to the 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 value. Any craters without production metadata will be dropped. When accessed, if any of the craters have a None value for time, they will be reprocessed to set their time value. This allows for the quasimc_craters to be dynamically updated.

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.

property Crater#

The Crater class used for crater generation.

This is set by the Simulation object when initializing a crater.

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)