Simulation

Simulation#

The Simulation class is the main class for the cratermaker project. It is used to create a simulation of a crater on a given target body. The Simulation class is used to generate craters of a given size and morphology based on the production function, morphology function, and crater scaling relationship model. The surface of the target body is represented by a Surface attribute called surface, which contains a UxDataset object called surface.uxds. This is an unstructured grid dataset that contains data for the target body surface.

class cratermaker.core.simulation.Simulation(*, target=None, scaling=None, production=None, morphology=None, projectile=None, surface=None, counting=None, simdir=None, rng=None, rng_seed=None, rng_state=None, reset=None, ask_overwrite=True, do_counting=True, save_actions=None, **kwargs)[source]#

Bases: CratermakerBase

Creates a simulation of a crater population on a target body. It allows for the generation of craters based on a variety of parameters, including the target body, scaling laws, production functions, and morphology models.

Parameters:

  • target (Target or str, optional, default “Moon”) – Name target body for the simulation, default is “Moon”.

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

  • production (Production or str, optional) – The production function model to use from the components library that defines the production function used to populate the surface with craters. If none provided, then the default will be based on the target body, with the NeukumProduction crater-based scaling law used if the target body is the Moon or Mars, the NeukumProduction projectile-based scaling law if the target body is Mercury, Venus, or Earth, and a simple power law model otherwise.

  • morphology (str, optional) – The model used to generate the morphology of the crater. If none provided, then the default will “basicmoon”, which is similar to the one used by CTEM.

  • projectile (str, optional) – The projectile model to use from the components library, which is used to generate the projectile properties for the simulation, such as velocity and density. The default is “asteroids” when target is Mercury, Venus, Earth, Moon, Mars, Ceres, or Vesta, and “comets” otherwise.

  • surface (str, optional) – The name of the surface used for the surface. Default is “icosphere”.

  • counting (Counting or str, optional) – The crater counting model to use from the components library. Default is “depthcount”.

  • 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.

  • ask_overwrite (bool, optional) – If True, the user will be prompted before overwriting any existing files. Default is True.

  • reset (bool, optional) – Flag to indicate whether to reset the simulation or resume from an old simulation. If False, the simulation will attempt to load the previous state from the config file. Default is False if ask_overwrite=False and a config file is detected, otherwise default is True.

  • do_counting (bool, optional) – If True, the counting component will keep track of emplaced craters during the simulation. Default is True.

  • save_actions (list[dict[str, dict]], optional) – A dictionary of actions to perform when the save method is called. The keys are the names of the actions and the values are dictionaries of keyword arguments to pass to the corresponding component’s save method. For example, if you want to automatically generate a hillshade plot every time the simulation is saved, you can pass save_actions=[{“plot”: {“plot_style”: “hillshade”, “cmap”: “pink”, “scalebar”: True, “label”: “Mars region simulation”, “show”: True, “save”: True}}]. This will call the surface’s save method with the specified keyword arguments every time the simulation is saved. Default is to save a hillshade plot of the surface every time the simulation is saved.

  • **kwargs (Any) – Additional keyword arguments that are either ignored or passed to internal functions as needed., including those for component function constructors. Refer to the documentation of each component module for details.

run(age=None, time_start=None, time_end=None, diameter_number=None, time_interval=None, ninterval=None, **kwargs)[source]#

Run the simulation over a specified interval using the current production function.

Parameters:

  • age (FloatLike, optional) – Start age in My relative to the present for the simulation, used to compute the starting point of the production function. Default is None, which requires ‘time_start’ or diameter_number to be set.

  • time_start (Floatlike, optional) – An alternative to age that specifies the starting time in My relative to the present for the simulation, used to compute the starting point of the production function. This is used in conjunction with time_end in order to allow for simulations that span a range of time rather than being of a specific age. Default is None, which requires either age or diameter_number to be set.

  • time_end (FloatLike, optional) – Ending time in My relative to the present for the simulation, used to compute the ending point of the production function. Default is 0 (present day) if not provided but time_start is provided.

  • diameter_number (PairOfFloats, optional) – Cumulative number and diameter pair (D, N) that defines the total crater accumulation for the given production function. Default is None, which requires age or time_start and time_end to be set.

  • time_interval (FloatLike, optional) – Interval in My for outputting intermediate results. If not provided, calculated as age / ninterval or (time_start - time_end) / ninterval if ninterval is provided, otherwise set to the total simulation duration (e.g. ninterval=1).

  • ninterval (int, optional) – Number of intervals for outputting results. This has a special use case where one can specify age-based inputs but output are computed in equal cumulative number intervals and vice versa.

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

Notes

This function allows defining the simulation parameters either in terms of time or crater frequency (cumulative number). The arguments age, time_start, time_end are mutually exclusive with diameter_number and time_interval is mutually exclusive with ninterval.

The initial state of the simulation (before any craters are emplaced) is always saved automatically. As a result, the total number of saved states will be ninterval + 1, where ninterval is the number of simulation intervals requested.

Examples

# Create a simulation object with default parameters (Moon, NeukumProduction, etc.)
sim = cratermaker.Simulation()

# Run the simulation for 3.8 billion years, saving the results every 100 million years
sim.run(age=3.8e3, time_interval=100.0)

# Run the simulation for 3.8 billion years, saving 100 intervals with equal cumulative number intervals
sim.run(age=3.8e3, ninterval=100)

# Run the simulation to create 80 craters larger than 300 km and output 100 equal cumulative number intervals
sim.run(diameter_number=(300e3, 80), ninterval=100)

# Run the simulation from 3.8 billion years to 3.0 billion years, saving the results every 100 million years
sim.run(time_start=3.8e3, time_end=3.0e3, time_interval=100.0)
populate(age=None, time_start=None, time_end=None, diameter_number=None, diameter_number_end=None, **kwargs)[source]#

Populate the surface with craters over a specified interval using the current production function.

Parameters:

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

  • time_start (FloatLike, optional) – An alternative to age that specifies the starting time in My relative to the present for the simulation, used to compute the starting point of the production function. This is used in conjunction with time_end in order to allow for simulations that span a range of time rather than being of a specific age. Default is None, which requires either age or diameter_number

  • time_end (FloatLike, optional) – The ending time in My relative to the present for the simulation, used to compute the ending point of the production function. 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 will 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.

emplace(craters=None, **kwargs)[source]#

Emplace one or more craters in the simulation.

This method orchestrates the creation and placement of a crater in the simulation. It can create a crater directly or based on the characteristics of a projectile.

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 crat er 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[Crater] – A list of the Crater objects that were emplaced in the simulation. Returns an empty list if no craters were emplaced.

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 Simulation, Crater

sim = Simulation()

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

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

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

# Create multiple craters
craters = [Crater.maker(diameter=20.0e3), Crater.maker(diameter=20.0e3)]
sim.emplace(craters)
save(**kwargs)[source]#

Save the current simulation state to a file.

Parameters:

**kwargs (Any) – Additional keyword argumments to pass to the component save methods.

export(driver='OpenCraterTool', interval=-1, ask_overwrite=None, **kwargs)[source]#

Export component output to a specified file format.

Parameters:

  • driver (str, optional) – The driver to use export the data to. Supported formats are ‘OpenCraterTool’, ‘VTK’ or a driver supported by GeoPandas (‘GPKG’, ‘ESRI Shapefile’, etc.). This is overridden if either the filename or file_extension parameters are provided. Default is ‘OpenCraterTool’.

  • interval (int, optional) – The interval number to export. Default is -1 (the most current interval saved in the simulation).

  • ask_overwrite (bool, optional) – If True, the user will be prompted to confirm before overwriting any existing files. If False, existing files will be overwritten without confirmation. If None, the default behavior of the class will be used. This will only persist for the duration of the export, and will be reset to its original value afterwards.

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

Notes

The default driver is ‘OpenCraterTool’, which is designed to output data into a format that is relatively easy to import into QGIS with the OpenCraterTool plugin. This will create a GeoTIFF file representation of the surface, and a set of SCC files for the crater counting data if counting is enabled.

plot(include_counting=False, interval=None, plot_style='hillshade', label='default', show=False, save=True, ax=None, **kwargs)[source]#

Plot the current state of the surface.

Parameters:

  • include_counting (bool, optional) – If True, the counting data will be included in the plot if counting is enabled. Default is False

  • interval (int, optional) – The interval number to plot. Default is None, which will plot the most current interval saved in the simulation.

  • plot_style (str, optional) – The style to use for surface plots. See Surface.plot() for more details. Default is ‘hillshade’.

  • label (str, optional) – The label to use for the plot. Default is None, which will use a label based on the current time and elapsed time of the simulation.

  • show (bool, optional) – If True, the plot will be displayed. Default is False.

  • save (bool, optional) – If True, the plot will be saved to a file. Default is True.

  • ax (matplotlib.axes.Axes, optional) – An optional matplotlib Axes object to plot on. If not provided, a new figure and Axes will be created. Default is None.

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

Returns:

Axes – The matplotlib Axes object created by the surface plot method.

show3d(engine='pyvista', **kwargs)[source]#

Show the current state of the simulated surface.

Parameters:

  • engine (str, optional) – The engine to use for plotting. Currently, only “pyvista” is supported. Default is “pyvista”.

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

Returns:

plotter (pyvista.Plotter or other engine-specific plotter object)

to_config(save_to_file=True, **kwargs)[source]#

Converts values to types that can be used in yaml.safe_dump.

This will convert various types into a format that can be saved in a human-readable YAML file. This will consolidate all of the configuration parameters into a single dictionary that can be saved to a YAML file. This will also remove any common arguments from the individual configurations for each component model to avoid repeating them.

Parameters:

  • save_to_file (bool, optional) – If True, the configuration will be saved to a file. Default is True.

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

Returns:

dict[str, Any] – A dictionary of the object’s attributes that can be serialized to YAML.

Notes

  • The function will ignore any attributes that are not serializable to human-readable YAML. Therefore, it will ignore anything that cannot be converted into a str, int, float, or bool.

  • The function will convert Numpy types to their native Python types.

reset(skip_component=None)[source]#

Reset the simulation by clearing all data and files associated with it.

Parameters:

skip_component (str or list of str, optional) – List of component names to skip during the reset process. Default is an empty list, which means all components will be reset.

update_elevation(*args, **kwargs)[source]#

Set the elevation on the surface. Delegates to the Surface object.

Parameters:

  • *args (Variable length argument list to pass to self.surface.update_elevation.)

  • |kwargs|

property target#

The target body for the impact simulation. Set during initialization.

property surface#

Surface mesh data for the simulation. Set during initialization.

property production#

The Production class instance used for crater production. Set during initialization.

property scaling#

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

property morphology#

The crater morphology model. Set during initialization.

property projectile#

The crater projectile model. Set during initialization.

property counting#

The crater counting model. Set during initialization.

property n_node#

Number of nodes in the simulation mesh. Dynamically set based on surface attribute.

property n_face#

Number of faces in the simulation mesh. Dynamically set based on surface attribute.

property interval#

The index of the current time step.

property elapsed_time#

The elapsed time in My since the start of the simulation.

property time#

The age of the current time step in My relative to the present from the chronology of the production function.

property elapsed_n1#

The elapsed number of craters larger than 1 km in diameter.

property smallest_crater#

The smallest crater diameter in meters. Set during initialization.

property largest_crater#

The largest crater diameter in meters. Set during initialization.

property smallest_projectile#

The smallest projectile diameter in meters. Set during initialization.

property largest_projectile#

The largest projectile diameter in meters. Set during initialization.

property name#

The name of the simulation.

property config_file#

The path to the configuration file for the simulation.

property config_readonly#

Flag indicating whether the configuration is read-only.

property time_variables#

A dictionary of time-related variables for the simulation.

Returns:

dict[str, float] – A dictionary containing the following keys: - “time”: The current age in My relative to the present. - “elapsed_time”: The elapsed time in My since the start of the simulation. - “elapsed_n1”: The elapsed number of craters larger than 1 km in diameter.

property do_counting#

A boolean flag indicating whether or not counting is enabled for the simulation. This is determined by whether or not a counting model is present and has counting enabled.

Returns:

bool – True if counting is enabled, False otherwise.

property observed#

Pass-through to retrieve the current observed craters from the counting model, if it is enabled.

property emplaced#

Pass-through to retrieve the current emplaced craters from the morphology model, if it is enabled.

property n_observed#

Pass-through to retrieve the current number of observed craters from the counting model, if it is enabled.

property n_emplaced#

Pass-through to retrieve the current number of emplaced craters from the counting model, if it is enabled.

output_filename(interval=None, **kwargs)[source]#

Generate the base output filename for a given interval, but does not include the output directory.

Parameters:

  • interval (int or None, optional) – The interval number to generate the filename for. If None, the filename will not include an interval number. Default is None.

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

Returns:

str – The generated output filename for the given interval.

property is_new#

A boolean flag indicating that this is a new simulation run, which will trigger a reset action when run is called.

property Crater#

The Crater class used for crater generation in the simulation. Set during initialization.