Crater#
The Crater class is one of the core components of Cratermaker. It is a dataclass that represents the properties of a crater and the projectile that formed it. Like all other components, it is instantiated with its maker factory method. You can create a crater by either specifying either its size or the size of a projectile. In either case, the crater and projectile properties will be computed using Target, Scaling, and Projectile objects. These can be provided to Crater.maker(), but if not, then the default values will be used.
At a minimum, you need to specify exactly one size input, which can be one of the following:
diameter: The final rim-to-rim diameter (post collapse phase) of the crater in meters.
radius: The final rim-to-rim radius (post collapse phase) of the crater in meters.
transient_diameter: The transient diameter (pre-collapse phase) of the crater in meters.
transient_radius: The transient radius (pre-collapse phase) of the crater in meters.
projectile_diameter: The diameter of the projectile that formed the crater in meters.
projectile_radius: The radius of the projectile that formed the crater in meters.
projectile_mass: The mass of the projectile that formed the crater in kilograms.
All other parameters are optional, and if not specified, will be determined by the provided (or default) Target, Scaling, and Projectile objects. We can demonstrate this behavior by specifiying the minimum set of arguments for a Crater, in which we define a crater with a final rim-to-rim diameter of 100 meters and then printing the resulting crater object to show its full set of properties:
In [1]: from cratermaker import Crater
In [2]: crater = Crater.maker(diameter=100.0)
In [3]: print(crater)
<Crater>
ID: 3561794449
Diameter: 100.0 m
morphology_type: simple
transient_diameter: 81.78 m
projectile_diameter: 4.780 m
projectile_mass: 1.2866e+05 kg
projectile_density: 2250 kg/m³
projectile_velocity: 17.41 km/s
projectile_angle: 42.3°
projectile_direction: 241.8°
location (lon,lat): (-90.6410°, 9.6730°)
As we can see, the Crater object contains values for the transient crater diameter, projectile properties, including size, mass, and impact velocity, angle and direction. It also contains a set of location coordinates on the target body, and a string value of the morphology type indicating that this is a simple crater.
Because we didn’t specify them, the default values of Target, Scaling, and Projectile were used. Therefore the above is quivalent to:
In [4]: crater = Crater.maker(diameter=100.0,
...: target="Moon",
...: projectile="asteroids",
...: scaling="montecarlo")
...:
In [5]: print(crater)
<Crater>
ID: 1935562966
Diameter: 100.0 m
morphology_type: simple
transient_diameter: 84.04 m
projectile_diameter: 3.271 m
projectile_mass: 4.1243e+04 kg
projectile_density: 2250 kg/m³
projectile_velocity: 24.62 km/s
projectile_angle: 85.4°
projectile_direction: 119.0°
location (lon,lat): (-42.2339°, 17.6177°)
Measured location (lon, lat): (-42.2339°, 17.6177°)
Crater from Projectile#
You can also create a crater by specifying the projectile size, which will then compute the crater size based on the projectile properties and the target body. For example, if we want to create a crater on Europa with a projectile diameter of 1.5 km , we can do so as follows:
In [6]: crater = Crater.maker(target="Europa", projectile_diameter=1500)
In [7]: print(crater)
<Crater>
ID: 1133341485
Diameter: 82.73 km
morphology_type: complex
transient_diameter: 54.90 km
projectile_diameter: 1.500 km
projectile_mass: 8.8357e+11 kg
projectile_density: 500 kg/m³
projectile_velocity: 16.24 km/s
projectile_angle: 64.7°
projectile_direction: 266.2°
location (lon,lat): (36.5513°, 16.3866°)
Measured location (lon, lat): (36.5513°, 16.3866°)
Because we chose Europa as a target, the default projectile population is “comets” instead of “asteroids.”
Specifying Crater Properties#
Besides the crater or projectile sizes values, which are required, there are a number of optional arguments you can pass to Crater.maker(), including
projectile_density: The density of the projectile in kg/m3. If not provided, it will be defined through the Projectile component provided. (e.g., “asteroids” or “comets”).
projectile_mean_velocity: The mean velocity in m/s from which to sample a projectile velocity. This will override the value from the Projectile model.
projectile_velocity: The total impact velocity of the projectile in m/s. If not provided, it is drawn from a distribution based on the target body and projectile populations.
projectile_vertical_velocity: The vertical component of the velocity in m/s. The total impact velocity will be determined by the projectile angle (either provided or drawn from a distribution).
projectile_angle: The impact angle in degrees (0-90). If not provided, it is drawn from a distribution that peaks at 45 degrees.
projectile_direction: The direction of the impact in degrees (0-360) relative to true north. If not provided, it is drawn from a uniform distribution.
location: The (longitude, latitude) location of the crater in degrees.
projectile_location: The (longitude, latitude) location of the projectile impact. This is equivalent to location, which takes precedence
age: The age of the crater in My. If not provided, it is not set. This is used by the Simulation for tracking the age at which a crater formed during the simulation. Setting it has no effect on the crater properties.
Suppose we wish to create a crater with a 10km transient diameter on Europa, but want to specify that it formed from an impactor with a density of 900 kg/m3, an impact velocity of 30 km/s, an impact angle of 25°, and a location at 45° S, 150° E. We can do so as follows:
In [8]: crater = Crater.maker(
...: target="Europa",
...: transient_diameter=10e3,
...: projectile_density=900,
...: projectile_velocity=30e3,
...: projectile_angle=25.0,
...: location=(150, -45),
...: )
...:
In [9]: print(crater)
<Crater>
ID: 2739295606
Diameter: 14.06 km
morphology_type: complex
transient_diameter: 10.00 km
projectile_diameter: 194.8 m
projectile_mass: 1.9353e+09 kg
projectile_density: 500 kg/m³
projectile_velocity: 30.00 km/s
projectile_angle: 25.0°
projectile_direction: 355.9°
location (lon,lat): (150.0000°, -45.0000°)
We can specify the projectile angle from a combination of the vertical velocity and total impact velocity. In this example we can create an impact on Mercury using a 3 km projectile that indirectly specifies the projectile angle from a 35 km/s velocity and a vertical velocity of 20 km/s.
In [10]: crater = Crater.maker(
....: target="Mercury",
....: projectile_diameter=3000.0,
....: projectile_velocity=35.0e3,
....: projectile_vertical_velocity=20e3,
....: )
....:
In [11]: print(crater)
<Crater>
ID: 945110596
Diameter: 47.84 km
morphology_type: complex
transient_diameter: 34.14 km
projectile_diameter: 3.000 km
projectile_mass: 3.1809e+13 kg
projectile_density: 2250 kg/m³
projectile_velocity: 35.00 km/s
projectile_angle: 45.9°
projectile_direction: 291.5°
location (lon,lat): (-163.9510°, 33.5583°)
Crater on a Custom Target#
The following example uses a custom-defined Target object. Here we will create a 300 km diameter body in the Kuiper belt with a mass of 1019 kg (about 700 kg/m3 bulk density). It will use both the ice model for its surface material and simple-to-complex scaling model.
In [12]: from cratermaker import Crater, Target
In [13]: kuip_belt_obj = Target(
....: name="KBO-1",
....: diameter=300e3,
....: mass=1e19,
....: material="Ice",
....: transition_scale_type="ice"
....: )
....:
In [14]: print(kuip_belt_obj)
<Target: KBO-1>
Material: Ice
Diameter: 300.0 km
Mass: 1.00e+19 kg
Surface density: 900.0 kg/m³
Transition Type: ice
Escape Velocity: 94.33 m/s
Gravity: 0.030 m/s²
Next we will feed our custom target body to the Crater.maker() method to create a crater on it. We will use a rocky projectile with a diameter of 500 m, an impact velocity of 5 km/s. All other properties will be computed.
In [15]: crater = Crater.maker(
....: target=kuip_belt_obj,
....: projectile_density=2800,
....: projectile_diameter=500,
....: projectile_velocity=5000,
....: )
....:
In [16]: print(crater)
<Crater>
ID: 624860487
Diameter: 41.02 km
morphology_type: transitional
transient_diameter: 34.54 km
projectile_diameter: 500.0 m
projectile_mass: 6.5450e+10 kg
projectile_density: 1000 kg/m³
projectile_velocity: 5.000 km/s
projectile_angle: 54.3°
projectile_direction: 28.8°
location (lon,lat): (18.1951°, -16.1693°)
Measured location (lon, lat): (18.1951°, -16.1693°)