Morphology

The Morphology class is an operations class for computing the morphology of a crater based on its size and target properties. It encapsulates the logic for altering the topography of the surface based on the crater properties.

Available Implementations

Class	Argument name	Example Usage
BasicMoonMorphology	“basicmoon”	morphology = Morphology.maker(“basicmoon”)

class cratermaker.components.morphology.Morphology(surface=None, production=None, counting=None, scaling=None, do_subpixel_degradation=True, do_slope_collapse=True, do_counting=None, **kwargs)

Bases: ComponentBase

classmethod maker(morphology=None, surface=None, production=None, counting=None, scaling=None, do_subpixel_degradation=True, do_slope_collapse=True, **kwargs)

Initialize a Morphology model with the given name or instance.

Parameters:

• morphology (str or Morphology or None) – The name of the morphology model to use, or an instance of Morphology. If None, the default “basicmoon” is used.

• surface (str or Surface, optional) – The name of a Surface object, or an instance of Surface, to be associated the morphology model.

• production (str or Production, optional) – The name of a Production object, or an instance of Production, to be associated with the morphology model. This is used for subpixel degradation in the emplace method. It is otherwise ignored.

• counting (str or Counting, optional) – The name of a Counting object, or an instance of Counting, to be associated with the morphology model. This is used to record crater counts during emplacement. If None, no counting will be performed.

• scaling (str or Scaling or None, optional) – The projectile->crater size scaling model to use from the components library. The default is “montecarlo”.

• do_subpixel_degradation (bool, optional) – If True, subpixel degradation will be performed during the emplacement of craters. Default is True.

• do_slope_collapse (bool, optional) – If True, slope collapse will be performed during the emplacement of craters. Default is True.

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

Returns:

Morphology – An instance of the specified Morphology model (e.g. BasicMoonMorphology).

Raises:

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

• TypeError – If the specified morphology model is not a string or a subclass of Morphology.

Available models:

• basicmoon

• realisticmoon

emplace(craters=None, **kwargs)

Convenience method to immediately emplace a crater onto the surface.

Initializes and uses the queue system behind the scenes.

Parameters:

• craters (Crater or list of Crater objects, optional) – The Crater object(s) to be emplaced. If provided, this will be used directly. Otherwise, a single crater will be generated based on the keyword arguments.

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

Returns:

list of Crater or None – The crater(s) that were emplaced. If no craters were provided and a crater could not be generated based on the keyword arguments, an empty list is returned.

Notes

The keyword arguments provided are passed down to Crater.maker(). Refer to its documentation for a detailed description of valid keyword arguments.

Examples

from cratermaker import Morphology, Crater

morphology = Morphology.maker()

# Create a crater with specific diameter
morphology.emplace(diameter=10.0e3)

# Create a crater based on a projectile with given mass and projectile_velocity
morphology.emplace(projectile_mass=1e15, projectile_velocity=20e3)

# Create a crater with a specific transient diameter and location
morphology.emplace(transient_diameter=50e3, location=(43.43, -86.92))

# Create multiple craters
craters = [Crater.maker(diameter=20.0e3), Crater.maker(diameter=20.0e3)]
morphology.emplace(craters)

form_crater(crater, **kwargs)

Form the interior of the crater by altering the elevation variable of the surface mesh.

Parameters:

• crater (Crater) – The crater object to be formed.

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

form_ejecta(crater, **kwargs)

Form the ejecta blanket of the crater by altering the elevation variable of the surface mesh.

Parameters:

• crater (Crater) – The crater object whose ejecta is to be formed.

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

Returns:

tuple[NDArray[np.float64], NDArray[np.float64]] – The computed ejecta thickness and intensity at the face and node elevations. |

abstractmethod crater_shape(crater, region, **kwarg)

abstractmethod ejecta_shape(crater, region, **kwarg)

abstractmethod rmax(crater, minimum_thickness, feature='ejecta')

abstractmethod static overlap_function(crater)

property surface

The Surface object associated with this morphology model.

property production

The Production object associated with this morphology model.

property counting

The Counting object associated with this morphology model.

property do_subpixel_degradation

Whether to perform subpixel degradation during crater emplacement.

property do_slope_collapse

Whether to perform slope collapse during crater emplacement.

property do_counting

Whether to perform crater counting during crater emplacement.

property scaling

The Scaling object that defines the crater scaling relationships model. Set during initialization.

property Crater

class CraterQueueManager(overlap_fn)

Bases: object

A manager for craters awaiting emplacement. Craters are processed in order (FIFO) but batches of non-overlapping craters can be processed simultaneously.

Parameters:

overlap_fn (Callable[[Crater], tuple[set[int], set[int]]]) – A function that takes a crater and returns a tuple of (node indices, face indices) affected.

push(crater)

Add a crater to the end of the queue.

Parameters:

crater (Crater) – The crater to be added to the queue.

Raises:

TypeError – If the provided crater is not an instance of Crater.

peek_next_batch()

Return a list of the next batch of craters that do not overlap with each other or the current active region.

Returns:

list of Crater – The next batch of craters that can be processed simultaneously without overlap.

pop_batch(batch)

Remove a processed batch of craters from the queue.

Parameters:

batch (list of Crater) – The batch of craters to be removed from the queue.

Raises:

ValueError – If any crater in the batch is not found in the queue.

property is_empty

Return True if the queue is empty, False otherwise.

class cratermaker.components.morphology.MorphologyCrater(crater=None, fixed_cls=<class 'cratermaker.components.crater.CraterFixed'>, variable_cls=<class 'cratermaker.components.morphology.MorphologyCraterVariable'>, **kwargs)

Bases: Crater

classmethod maker(crater=None, morphology=None, location=None, relative_location=None, check_redundant_inputs=True, **kwargs)

Initialize a MorphologyCrater object either from an existing Crater object or from parameters.

This generates a specialized Crater object with morphology parameters.

Parameters:

• crater (Crater, optional) – The crater object to be converted into a BasicMoonCrater. If None, then a new crater is created using the provided parameters.

• morphology (Morphology, optional) – The morphology model to use for generating morphology parameters.

• location (pair of floats, optional) – The (longitude, latitude) location of the crater.

• relative_location (dict) – Set the crater’s location based on the distance and bearing from a reference location. The dictionary is required to have the keys: “distance” and “bearing” with values of distance (in meters) and bearing (in degrees) from the reference point. A third key, “reference_location” should be in the form of a tuple of floats representing the longitude and latitude pair that defines the reference location. The “reference_location” is optional if the morphology.surface contains a local_location attribute (such as in the case of a HiResLocal surface type and its derivatives) which will be used if the key is missing or set to None, otherwise it is required. Both location and relative_location cannot be set unless check_redundant_inputs is set to False.

• check_redundant_inputs (bool, optional) – If True, check for redundant inputs such as providing both diameter and radius. Default is True.

• kwargs (Any) – The keyword arguments provided are passed down to MorphologyCrater.maker(). Refer to its documentation for a detailed description of valid keyword arguments.

as_dict(ignore_keys=(), skip_complex_data=False, **kwargs)

Return a dictionary representation of the crater properties, including morphology-specific variable properties.

Parameters:

• ignore_keys (list[str] or tuple[str], optional) – A list or tuple of property names to ignore when creating the dictionary representation. Default is an empty tuple unless skip_complex_data is True, in which case it will be extended to include (“morphology”, “affected_face_indices”, “affected_node_indices”, “ejecta_region”, “ejecta_region”, “crater_region”).

• skip_complex_data (bool, optional) – If True, skip complex data types when creating the dictionary representation. This is useful when serializing the object for saving to a file, as it removes complex data types that may not be serializable. Default is False.

remove_complex_data()

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 morphology model is not removed, so that the complex data can be recomputed if needed.

property face_index

The index of the face on the surface mesh where the crater is centered.

property ejecta_rmax

The maximum radius of the ejecta region for this crater, as determined by the morphology model and is based on the distance that the ejecta thickness falls below the value of the smallest_length attribute of the morphology’s associated Surface object.

property ejecta_region

The LocalSurface view extracted around the crater center that encompasses the ejecta blanket, as determined by the morphology model.

This is extracted from the morphology’s associated Surface object based on the location of the crater and the ejecta_rmax distance. If the ejecta region cannot be extracted (e.g. if it is smaller than a single face of the mesh) this property will be set to None and the crater will be marked as not emplaceable.

property crater_region

The LocalSurface view extracted around the crater center that encompasses a buffered region around the cratered rim.

This is extracted from the morphology’s associated Surface object based on the location of the crater and a radius that extends by a _RIM_BUFFER_FACTOR constant times the crater radius. If the crater region cannot be extracted (e.g. if it is smaller than a single face of the mesh) this property will be set to None and the crater will be marked as not emplaceable.

property affected_face_indices

The set of face indices on the surface mesh that are affected by this crater, which is determined based on the crater region.

This is used by the morphology’s queue manager to determine if craters overlap and can be emplaced simultaneously.

property affected_node_indices

The set of node indices on the surface mesh that are affected by this crater, which is determined based on the crater region.

This is used by the morphology’s queue manager to determine if craters overlap and can be emplaced simultaneously.

property emplaceable

Whether this crater is large enough to be emplaced on the surface mesh, which is determined based on whether the crater region could be successfully extracted.

property measured_rim_height

The measured rim height of the crater, which is determined based on the morphology model’s crater shape and the surface elevation data in the crater region.

property measured_floor_depth

The measured floor depth of the crater, which is determined based on the morphology model’s crater shape and the surface elevation data in the crater region.

property measured_depth_to_diameter

The measured depth to diameter ratio of the crater.

This is computed from measured_rim_height-measured_floor_depth

class cratermaker.components.morphology.MorphologyCraterVariable(morphology=None, **kwargs)

Bases: CraterVariable

as_dict()

Return a dictionary representation of the crater variable properties.

property morphology

The morphology model associated with this crater variable object.

property emplaceable

Whether this crater is large enough to be emplaced on the surface mesh, which is determined based on whether the crater region could be successfully extracted.

property face_index

The index of the face on the surface mesh where the crater is centered.

property ejecta_rmax

The maximum radius of the ejecta region for this crater, as determined by the morphology model and is based on the distance that the ejecta thickness falls below the value of the smallest_length attribute of the morphology’s associated Surface object.

property affected_face_indices

The set of face indices on the surface mesh that are affected by this crater, which is determined based on the crater region and is used by the morphology’s queue manager to determine if craters overlap and can be emplaced simultaneously.

property affected_node_indices

The set of node indices on the surface mesh that are affected by this crater, which is determined based on the crater region and is used by the morphology’s queue manager to determine if craters overlap and can be emplaced simultaneously.

property ejecta_region

The LocalSurface view extracted around the crater center that encompasses the ejecta blanket, as determined by the morphology model.

property crater_region

The LocalSurface view extracted around the crater center that encompasses a buffered region around the cratered rim, as determined by the morphology model.

BasicMoonMorphology

See Morphology for inherited methods and attributes.

class cratermaker.components.morphology.basicmoon.BasicMoonMorphology(surface=None, ejecta_truncation=None, dorays=False, rng=None, rng_seed=None, rng_state=None, **kwargs)

Bases: Morphology

An operations class for computing the morphology of a crater and applying it to a surface mesh.

emplace(craters=None, **kwargs)

Convenience method to immediately emplace a crater onto the surface.

Initializes and uses the queue system behind the scenes.

Parameters:

• crater (Crater | list[Crater] | None) – The crater or list of craters to be emplaced. If None, then a crater will be created using the provided parameters in kwargs and emplaced.

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

Returns:

list[BasicMoonCrater] – The list of BasicMoonCrater objects that were emplaced.

form_crater(crater, **kwargs)

Form a crater or list of craters on the surface.

Parameters:

• crater (BasicMoonCrater) – The crater object to be formed.

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

form_ejecta(crater, **kwargs)

Form the ejecta blanket of the crater by altering the elevation variable of the surface mesh.

Parameters:

• crater (Crater) – The crater object whose ejecta is to be formed.

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

Returns:

tuple[NDArray[np.float64], NDArray[np.float64]] – The computed ejecta thickness and intensity at the face and node elevations.

crater_shape(crater, region, **kwargs)

Compute the crater shape based on the region view and surface.

Parameters:

• crater (BasicMoonCrater) – The crater object containing the parameters for the crater shape.

• region (LocalSurface) – The region view of the surface mesh centered at the crater center.

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

Returns:

NDArray[np.float64] – The computed crater shape at the face and node elevations.

crater_profile(crater, r, r_ref=None)

Compute the crater profile elevation at a given radial distance.

Parameters:

• crater (BasicMoonCrater) – The crater object containing the parameters for the crater profile.

• r (ArrayLike) – Radial distances from the crater center (in meters).

• r_ref (ArrayLike, optional) – Reference elevation values to be modified by the crater profile.

Returns:

elevation (NDArray[np.float64]) – The computed crater elevation profile at each radial point.

Notes

This is a wrapper for a compiled Rust function.

ejecta_shape(crater, region, **kwargs)

Compute the ejecta shape based on the region view and surface.

Parameters:

• region (LocalSurface) – The region view of the surface mesh centered at the crat er center.

• crater (BasicMoonCrater) – The crater object containing the parameters for the ejecta shape.

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

Returns:

• NDArray[np.float64] – The computed ejecta shape at the face and node elevations

• NDArray[np.float64] – The computed ejecta intensity at the face and node elevations which is used to compute the degradation function. When dorays is True, this is the ray intensity function. When dorays is False, this is just a constant 1 over the ejecta region.

ejecta_profile(crater, r)

Compute the ejecta elevation profile at a given radial distance.

Parameters:

• crater (BasicMoonCrater) – The crater object containing the parameters for the ejecta profile.

• r (ArrayLike) – Radial distances from the crater center (in meters).

Returns:

elevation (NDArray[np.float64]) – The computed ejecta profile at each radial point.

Notes

This is a wrapper for a compiled Rust function.

ejecta_distribution(crater, r, theta)

Compute the ejecta thickness distribution modulated by ray patterns.

Parameters:

• crater (BasicMoonCrater) – The crater object containing the parameters for the ejecta distribution.

• r (ArrayLike) – Radial distances from the crater center (in meters).

• theta (ArrayLike) – Angular bearings from the crater center (in degrees).

Returns:

• thickness (NDArray[np.float64]) – The computed ejecta thickness for each (r, theta) pair.

• ray_intensity (NDArray[np.float64]) – The computed ray intensity for each (r, theta) pair.

Notes

This is a wrapper for a compiled Rust function.

ray_intensity(crater, r, theta)

Compute the ray pattern intensity modulation at each (r, theta) pair.

Parameters:

• crater (BasicMoonCrater) – The crater object containing the parameters for the ray intensity.

• r (ArrayLike) – Radial distances from the crater center (in meters).

• theta (ArrayLike) – Angular bearings from the crater center (in degrees).

Returns:

intensity (NDArray[np.float64]) – The computed ray intensity values.

Notes

This is a wrapper for a compiled Rust function.

ejecta_burial_degradation(ejecta_thickness, ejecta_soften_factor=1.5)

Computes the change in degradation state due to ejecta burial.

This function implements a combination of the model by Minton et al. (2019) [1].

Parameters:

• region (LocalSurface) – The region view of the surface mesh centered at the crater center.

• ejecta_thickness (NDArray[np.float64]) – The computed ejecta thickness at the face and node elevations.

Returns:

NDArray[np.float64] – The computed change in degradation state for all faces in the

References

[1]

Minton, D.A., Fassett, C.I., Hirabayashi, M., Howl, B.A., Richardson, J.E., (2019). The equilibrium size-frequency distribution of small craters reveals the effects of distal ejecta on lunar landscape morphology. Icarus 326, 63-87. doi: 10.1016/j.icarus.2019.02.021

compute_subpixel_degradation(time_start, time_end, **kwargs)

Performs the subpixel degradation.

This models the combined degradation of the part of the production population that is below the resolution of the mesh on each face. It is called between batches of craters by the emplace method.

Parameters:

• time_start (float) – The time of the surface at the start of the degradation.

• time_end (float) – The time of the surface at the end of the degradation. Additional keyword arguments that are either ignored or passed to internal functions as needed.

apply_subpixel_degradation(**kwargs)

Apply subpixel degradation to the surface using the current Kdiff values.

This method is called after all craters have been processed and is used to apply the accumulated degradation effects.

rmax(crater, minimum_thickness, feature='ejecta')

Compute the maximum extent of the crater based on the minimum thickness of a feature, or the ejecta_truncation factor, whichever is smaller.

Parameters:

• crater (Crater) – The crater object to be used.

• minimum_thickness (FloatLike) – The minimum thickness of the feature blanket in meters.

• feature (str, optional, default = “ejecta”) – The feature to compute the maximum extent. Either “crater” or “ejecta”. If “crater” is chosen, the rmax is based on where the raised rim is smaller than minimum thickness.

Returns:

float – The maximum extent of the crater or ejecta blanket in meters.

degradation_function(diameter, fe=100.0)

Computes the degradation function, which defines the topographic degradation that each crater contributes to the surface.

This function implements a combination of the model by Minton et al. (2019) [2] for small craters and Riedel et al. (2020) [3] for large craters. It is currently not well-constrained, so may change in the future.

Parameters:

• diameter (FloatLike) – The final diameter of the crater in meters.

• fe (FloatLike, optional) – The degradation function size factor, which is a scaling factor for the degradation function. Default is 100.0.

Returns:

float – The computed degradation function

References

[2]

Minton, D.A., Fassett, C.I., Hirabayashi, M., Howl, B.A., Richardson, J.E., (2019). The equilibrium size-frequency distribution of small craters reveals the effects of distal ejecta on lunar landscape morphology. Icarus 326, 63-87. doi:10.1016/j.icarus.2019.02.021

[3]

Riedel, C., Minton, D.A., Michael, G., Orgel, C., Bogert, C.H. van der, Hiesinger, H., 2020. Degradation of Small Simple and Large Complex Lunar Craters: Not a Simple Scale Dependence. Journal of Geophysical Research: Planets 125, e2019JE006273. doi:10.1029/2019JE006273

static overlap_function(crater)

Get the affected node and face indices for the crater.

Parameters:

crater (BasicMoonCrater) – The crater object to be used.

Returns:

tuple[set[int], set[int]] – The affected node and face indices for the crater.

property ejecta_truncation

The radius at which the crater is truncated relative to the crater radius.

Returns:

float or None

property dorays

A flag to determine if the ray pattern should be used instead of the homogeneous ejecta blanket.

Returns:

bool

class cratermaker.components.morphology.basicmoon.BasicMoonCrater(crater=None, fixed_cls=<class 'cratermaker.components.morphology.basicmoon.BasicMoonCraterFixed'>, variable_cls=<class 'cratermaker.components.morphology.MorphologyCraterVariable'>, **kwargs)

Bases: MorphologyCrater

classmethod maker(crater=None, morphology=None, **kwargs)

Initialize a BasicMoonCrater object either from an existing Crater object or from parameters.

This generates a specialized Crater object with morphology parameters.

Parameters:

• crater (Crater, optional) – The crater object to be converted into a BasicMoonCrater. If None, then a new crater is created using the provided parameters.

• morphology (Morphology, optional) – The morphology model to use for generating morphology parameters.

• kwargs (Any) – The keyword arguments provided are passed down to cratermaker.morphology.MorphologyCrater.maker(). Refer to its documentation for a detailed description of valid keyword arguments.

class cratermaker.components.morphology.basicmoon.BasicMoonCraterFixed(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, rim_height: 'float | None' = None, rim_width: 'float | None' = None, floor_depth: 'float | None' = None, floor_diameter: 'float | None' = None, peak_height: 'float | None' = None, ejrim: 'float | None' = None)

Bases: CraterFixed

rim_height

Original rim height of the crater in meters relative to the reference surface.

rim_width

Original rim width of the crater in meters.

floor_depth

Original floor depth of the crater in meters relative to the reference surface.

floor_diameter

Original floor diameter of the crater in meters.

peak_height

Original central peak height of the crater in meters relative to the reference surface. None for simple craters.

ejrim

Original ejecta rim thickness of the crater in meters.

property depth_to_diameter

The depth to diameter ratio of the crater.

This is computed from rim_height-floor_depth

Usage example

from cratermaker import Morphology
morphology = Morphology.maker("basicmoon")