Crater

Crater#

The Crater class represents a single crater in the simulation. It is used to model the crater resulting from an impact, including its size, shape, depth, and other morphological features. It also defines the properties of the projectile, such as its size, velocity, material, and angle of impact.

Available Implementation#

The Crater class is the base class for all crater objects in the simulation. It contains the core properties and methods that are common to all crater types. It is a composite object that contains both fixed and variable properties of the crater, as well as a reference to the target body. Fixed and variable properties are stored internally as subclasses, but all properties are accessible directly from the crater object for ease of use.

class cratermaker.components.crater.Crater(crater=None, fixed_cls=<class 'cratermaker.components.crater.CraterFixed'>, variable_cls=<class 'cratermaker.components.crater.CraterVariable'>, **kwargs)[source]#

Bases: ComponentBase

as_dict(ignore_keys=[], **kwargs)[source]#: Expose delegated attributes for serialization.

classmethod maker(crater=None, scaling=None, target=None, projectile=None, diameter=None, radius=None, final_diameter=None, final_radius=None, transient_diameter=None, transient_radius=None, semimajor_axis=None, semiminor_axis=None, orientation=None, projectile_diameter=None, projectile_radius=None, projectile_mass=None, projectile_density=None, projectile_velocity=None, projectile_mean_velocity=None, projectile_vertical_velocity=None, projectile_angle=None, projectile_direction=None, projectile_location=None, location=None, longitude=None, latitude=None, time=None, name=None, measured_semimajor_axis=None, measured_semiminor_axis=None, measured_orientation=None, measured_diameter=None, measured_radius=None, measured_location=None, measured_rim_height=None, measured_floor_depth=None, degradation_state=None, production_time=None, production_ND=None, production_sequence=None, simdir=None, rng=None, rng_seed=None, rng_state=None, check_redundant_inputs=True, **kwargs)[source]#

Create a Crater object with the given parameters.

Parameters:

crater (Crater, optional) – A Crater object to copy parameters from.
scaling (str or Scaling, optional) – A string key or instance of a scaling model. If none provided, a default will be used
target (str or Target, optional) – A string key or instance of a target model. If none provided, a default will be used.
projectile (str or Projectile, optional) – A string key or instance of a projectile model. If none provided, a default will be used.
diameter (float, optional) – The final diameter of the crater in meters.
final_diameter (float, optional) – The final diameter of the crater in meters. This is an alias of “diameter”
radius (float, optional) – The final radius of the crater in meters.
final_radius (float, optional) – The final radius of the crater in meters. This is an alias of “radius”
transient_diameter (float, optional) – The transient diameter of the crater in meters.
transient_radius (float, optional) – The transient radius of the crater in meters.
semimajor_axis (float, optional) – The semimajor axis of the crater in meters. Same as radius if the crater is circular.
semiminor_axis (float, optional) – The semiminor axis of the crater in meters. Same as radius if the crater is circular.
orientation (float, optional) – The orientation of the crater in degrees if it is elliptical.
projectile_diameter (float, optional) – The diameter of the projectile in meters.
projectile_radius (float, optional) – The radius of the projectile in meters.
projectile_mass (float, optional) – The mass of the projectile in kilograms.
projectile_density (float, optional) – The density of the projectile in kg/m³. If not provided, it will be defined through the projectile population model provided.
projectile_velocity (float, optional) – The total impact velocity of the projectile in m/s.
projectile_mean_velocity (float, optional) – The mean velocity from which to sample a projectile velocity.
projectile_vertical_velocity (float, optional) – The vertical component of the velocity in m/s.
projectile_angle (float, optional) – The impact angle in degrees (0-90).
projectile_direction (float, optional) – The direction of the impact in degrees (0-360).
projectile_location (pair of float, optional) – The (longitude, latitude) location of the projectile impact. This is equivalent to location, which takes precedence
location (pair of floats, optional) – The (longitude, latitude) location of the crater on the target surface in degrees.
longitude (float, optional) – The longitude of the crater on the target surface in degrees. If used, you must also pass latitude and cannot pass location.
latitude (float, optional) – The latitude of the crater on the target surface in degrees. If used, you must also pass longitude and cannot pass location.
time (float, optional) – The time of the crater impact in Myr before present.
measured_semimajor_axis (float, optional) – The measured semimajor axis of the crater in meters.
measured_semiminor_axis (float, optional) – The measured semiminor axis of the crater in meters.
measured_orientation (float, optional) – The measured orientation of the crater in degrees.
measured_diameter (float, optional) – The measured diameter of the crater in meters.
measured_radius (float, optional) – The measured radius of the crater in meters.
measured_location (pair of floats, optional) – The measured (longitude, latitude) location of the crater.
measured_rim_height (float, optional) – The measured rim height of the crater in meters.
measured_floor_depth (float, optional) – The measured floor depth of the crater in meters.
degradation_state (float, optional) – The current degradation state of the crater in meters squared.
production_ND (tuple[float, float, float] | tuple[float, float], optional) – The production N(D) value for quasi-Monte Carlo emplacement. Can either be the form of a tuple, of [D, N, Nsigma] or [D, N], where D is the reference diameter in km and N is number of craters per 1 million sq. km, with an optional 1 sigma undertainty Nsigma
production_time (tuple[float, float] | float, optional) – The production time for quasi-Monte Carlo emplacement. Can either be in the form of a tuple of [t,tsigma] or a float of t, where t is the emplacement time in My with an optional 1 sigma uncertainty tsigma.
production_sequence (int | None = None,) – A positive integer value used to constrain the sequence of quasi-Monte Carlo craters. Craters with a sequence number can only form after craters with a lower sequence number.
simdir (str | Path) – The main project simulation directory. Default is the current working directory if None.
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.
check_redundant_inputs (bool, optional) – If True, check for redundant inputs such as providing both diameter and radius. Default is True.
**kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

Returns:

Crater – A frozen Crater dataclass with derived attributes.

Notes

Unless check_redundant_inputs is False, the following rules apply:
Exactly one of the following must be provided: diameter, radius, both of semimajor_axis and semiminor_axis, transient_diameter, transient_radius, projectile_diameter, projectile_radius, or projectile_mass.
Velocity may be specified in one of these ways:
projectile_mean_velocity alone (samples a velocity)
Any two of (projectile_velocity, projectile_vertical_velocity, projectile_angle). the third is inferred.
projectile is mutually exclusive with velocity-related inputs; if provided, it overrides velocity, angle, direction, and density unless explicitly set.
The scaling, and rng models are required for scaling and density inference, but are not stored in the returned Crater object.
If providing measured properties, either both measured_semimajor_axis and measured_semiminor_axis, or one of measured_diameter or measured_radius must be provided.
if check_redundant_inputs is True and any of the rules are violated, then it is assumed that the user wants a copy. In that case, some parameters will not be computed and only the user-input arguments will be used

Available models:

morphologycrater
basicmooncrater

to_geoseries(n=121, surface=None, split_antimeridian=True, use_measured_properties=True, **kwargs)[source]#

Geodesic ellipse on a sphere: for each bearing theta from the center, we shoot a geodesic with distance r(theta) = (a*b)/sqrt((b*ct)^2 + (a*st)^2), then rotate all bearings by the crater’s orientation.

Parameters:

n (int, optional) – Number of points to use for the polygon, by default 121 (every 3 degrees plus the end point).
surface (Surface | None, optional) – Surface object providing planetary radius and CRS.
split_antimeridian (bool, optional) – If True, split the polygon into a GeometryCollection if it crosses the antimeridian, by default True.
use_measured_properties (bool, optional) – If True, use the current measured crater properties (semimajor_axis, semiminor_axis, location, orientation) instead of the initial ones, by default True.
**kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

Returns:

A GeoSeries containing a Shapely Polygon in lon/lat degrees.

classmethod from_file(filename, **kwargs)[source]#

Load a list of craters from a file.

Parameters:

filename (str | Path) – The path to the file to load from.
**kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed.

Returns:

list[Crater] | None – A list of Crater objects loaded from the file, or None if no data.

classmethod from_csv_file(input_file)[source]#

Import crater data from a CSV file.

Parameters:: input_file (Path | str) – The path to the CSV file containing crater data.
Returns:: list[Crater] – A list of Crater objects imported from the CSV file.

classmethod from_scc_file(input_file)[source]#

Import crater data from a Spatial Crater Count file.

Parameters:: input_file (Path | str) – The path to the SCC file containing crater data.
Returns:: list[Crater] – A list of Crater objects imported from the SCC file.

classmethod from_xarray(dataset, interval=None)[source]#

Import crater data from an xarray Dataset.

Parameters:: dataset (xr.Dataset | dict) – The xarray Dataset containing crater data or a dictionary of xarray Datasets keyed by interval number.
Returns:: list[Crater] – A list of Crater objects imported from the xarray Dataset.

property final_diameter#: Final diameter of the crater in meters.

property final_radius#: Final radius of the crater in meters.

remove_complex_data(**kwargs)[source]#

Remove complex data types from the crater variable properties.

This is useful for storing a lightweight representation, as it removes complex data types that can be recomputed from the fixed properties and the morphology model when needed. The base Crater type does not have any complex data types, but is used by derived types that do, so this method is included here for consistency and to allow for future expansion of the base Crater type without breaking the API.

CraterFixed#

The CraterFixed class represents the properties of the crater that are fixed at when the crater object is instantiated. These properties include things such as the original values of morphological parameters and location. This class is not meant to be instantiated directly, but rather it is used internally by the Crater class to store fixed properties of the crater.

class cratermaker.components.crater.CraterFixed(id: 'np.uint32' = None, semimajor_axis: 'float | None' = None, semiminor_axis: 'float | None' = None, orientation: 'float | None' = None, transient_diameter: 'float | None' = None, projectile_diameter: 'float | None' = None, projectile_velocity: 'float | None' = None, projectile_angle: 'float | None' = None, projectile_mass: 'float | None' = None, location: 'PairOfFloats | None' = None, morphology_type: 'str | None' = None, time: 'float | None' = None)[source]#

Bases: object

id#: A unique identifyer for the crater, which can be used to track it across time steps in a simulation. This is automatically generated when a crater is emplaced in a simulation as a hash of its fixed attributes.

semimajor_axis#: The semimajor axis of the crater in meters. For a circular crater, this is equal to the semiminor axis and the radius.

semiminor_axis#: The semiminor axis of the crater in meters. For a circular crater, this is equal to the semimajor axis and the radius.

orientation#: Orientation of the crater in degrees, measured clockwise from north. For a circular crater, this value is not meaningful, but will be set to the same value as projectile_orientation.

transient_diameter#: The transient diameter of the crater in meters.

projectile_diameter#: The diameter of the projectile in meters.

projectile_velocity#: The velocity of the projectile in meters per second.

projectile_angle#: The impact angle of the projectile relative to the surfacein degrees.

projectile_mass#: The mass of the projectile in kg.

location#: The location of the crater center in (longitude, latitude) in degrees.

morphology_type#: The morphology type of the crater, i.e. “simple”, “complex”, etc.

time#: The time in My before present at which the crater was emplaced or observed.

radius#: The radius of the crater in meters. For a circular crater, this is equal to the semimajor and semiminor axes. For a non-circular crater, this is the geometric mean of the semimajor and semiminor axes.

diameter#: The diameter of the crater in meters. For a circular crater, this is equal to twice the semimajor and semiminor axes. For a non-circular crater, this is twice the geometric mean of the semimajor and semiminor axes.

transient_radius#: The transient radius of the crater in meters, which is half the transient diameter.

projectile_radius#: The radius of the projectile in meters, which is half the projectile diameter.

projectile_density#: The density of the projectile in kg/m³.

projectile_vertical_velocity#: The vertical component of the projectile velocity in meters per second.

projectile_direction#: The direction of the projectile in degrees, measured clockwise from north. This is the same as orientation.

CraterVariable#

The CraterVariable class represents the properties of the crater that can be altered after the crater object is instantiated. These properties include things such as measured values of morphological parameters, which can be updated as the crater evovles on the surface. This class is not meant to be instantiated directly, but rather it is used internally by the Crater class to store variable properties of the crater.

class cratermaker.components.crater.CraterVariable(measured_diameter=None, measured_radius=None, measured_semimajor_axis=None, measured_semiminor_axis=None, measured_orientation=None, measured_location=None, measured_rim_height=None, measured_floor_depth=None, degradation_state=None, production_time=None, production_ND=None, production_sequence=None, name=None, **kwargs)[source]#

Bases: object

as_dict()[source]#

Convert the variable attributes to a dictionary for serialization, excluding any attributes that are None.

If both measured_diameter and measured_semimajor_axis are provided and consistent, only include measured_diameter. If both measured_radius and measured_semimajor_axis are provided and consistent, only include measured_radius. This is to avoid redundancy in the output.

property name#: Optional name of the crater, which does not need to be unique.

property measured_diameter#: Final diameter of the crater in meters.

property measured_radius#

The measured radius of the crater in meters. For a circular crater, this is equal to the measured semimajor and semiminor axes.

For a non-circular crater, this is the geometric mean of the measured semimajor and measured semiminor axes. This is a variable attribute that can be updated as the crater degrades or as measurements are refined, and is independent of the fixed semimajor axis attribute.

property measured_semimajor_axis#

The measured semimajor axis of the crater in meters.

For a circular crater, this is equal to the measured semiminor axis and the measured radius. For a non-circular crater, this is the longest axis of the crater. This is a variable attribute that can be updated as the crater degrades or as measurements are refined, and is independent of the fixed semimajor axis attribute.

property measured_semiminor_axis#

The measured semiminor axis of the crater in meters.

For a circular crater, this is equal to the measured semimajor axis and the measured radius. This is a variable attribute that can be updated as the crater degrades or as measurements are refined, and is independent of the fixed semimajor axis attribute.

property measured_orientation#

The measured orientation of the crater in degrees, measured clockwise from north.

This is a variable attribute that can be updated as the crater degrades or as measurements are refined, and is independent of the fixed orientation attribute.

property measured_location#

property measured_rim_height#

property measured_floor_depth#

The measured floor depth below the local reference plane of the crater in meters.

This is a variable attribute that can be updated as the crater degrades or as measurements are refined, and is independent of any fixed attributes.

property degradation_state#

The degradation state of the crater in m², which is a measure of how much the crater has degraded diffusively from its original state.

This is a variable attribute that can be updated as the crater degrades or as measurements are refined, and is independent of any fixed attributes.

property production_time#: The range of ages of the crater in Myr before present, used by the quasi-monte carlo sampling method to emplace a user-defined crater within a time period.

property production_ND#: A tuple of diameter and cumulative number values, in the form of a (D, N), or (D, N, N_stdev) used by the quasi-monte carlo sampling method to emplace a user-defined crater within a number-diameter range.

property production_sequence#: The production sequence number of the crater, used by the quasi-monte carlo sampling method to emplace a user-defined crater in a relative sequence order with other quasi-monte carlo sampled craters.

Crater

Contents

Crater#

Available Implementation#

CraterFixed#

CraterVariable#