Base

The base classes define common methods and attributes that are shared across all components, such as the output directory where data files are stored. It also defines the interface for saving and loading data, which is used by all components to manage their data files.

CommonArgs

The CommonArgs class defines a set of common arguments that can be passed to any components. This is used to pass arguments to different components when they are created as part of a Simulation object.

class cratermaker.core.base.CommonArgs(simdir, rng, rng_seed, rng_state, ask_overwrite=True)

Bases: object

Stores the common arguments that are shared among all components of the project.

This is used to pass these common arguments to the maker functions of each component when they are initialized from other components. For example, the Scaling component will store an instance of Target and Projectile. If defaults of these components are used, then the Scaling.maker will pass the arguments stored here to the Target.maker and Projectile.maker functions when it initializes the Target and Projectile objects. This way, if the user has specified any non-default arguments for the simulation (e.g. a custom simdir or rng_seed), then those arguments will be passed to the Target and Projectile makers when they are initialized from the Scaling maker, ensuring that all components of the simulation are initialized with the same common arguments.

simdir

The root directory of the simulation.

rng

The random number generat or object.

rng_seed

The random number seed.

rng_state

The current state of the random number generator.

ask_overwrite = True

Flag indicating whether to prompt the user before overwriting a file.

CratermakerBase

This is a base class that defines common methods and attributes for all components in the cratermaker package. It includes methods for saving and loading data, as well as a reference to the output directory where data files are stored.

class cratermaker.core.base.CratermakerBase(simdir=None, rng=None, rng_seed=None, rng_state=None, ask_overwrite=None, **kwargs)

Bases: object

Base class for the Cratermaker project.

Parameters:

• 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, prompt the user for confirmation before overwriting any existing files when saving output. Default is True.

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

reset(files_to_remove=None, **kwargs)

Reset the component by removing its output files.

Parameters:

• files_to_remove (list[Path | str], optional) – If set, this is the list of files that will be removed. If not set, then the removed files will be determined using the component’s output_dir and output_file_pattern attributes.

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

to_config(remove_common_args=False, **kwargs)

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.

Parameters:

• obj (Any) – The object whose attributes will be stored. It must have a _user_defined attribute.

• remove_common_args (bool, optional) – If True, remove the set of common arguments that are shared among all components of the project from the configuration. Default is False.

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

save(interval=None, filename=None, skip_actions=False, **kwargs)

Runs the action methods specified in the save_actions property of this component, which should be a dictionary where the keys are the names of actions that can be performed on this component (e.g. “plot”) when calling the save function and the values are the arguments that should be passed to that action when it is called by the save function.

Parameters:

• interval (int or None, optional) – The interval number to save. If None, save without an interval number. Default is None.

• filename (str or Path or None, optional) – The base filename to save to, without the output directory or file extension. If None, the filename will be generated using the output_file_prefix and output_file_extension properties. Default is None.

• skip_actions (bool, optional) – If True, skip running the actions specified in the save_actions property and just return without doing anything. Default is False.

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

Notes

• skip_actions should be set to True if the save method is called from inside another method of the same object that could potentially be included in a save_actions entry. This will prevent recursive calls to save.

export(**kwargs)

Export the component data to the specified format.

This is a stub that acts as a pass-through for components that don’t have an export method defined.

Parameters:

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

from_file(filename, **kwargs)

Load the component data from a file.

This is a stub that acts as a pass-through for components that don’t have a from_file method defined.

Parameters:

• filename (str or Path) – The path to the file to load the component data from.

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

get_saved_interval_numbers()

Retrieved one or more lists of saved interval numbers that match the output file pattern(s).

Returns:

tuple[list[int], …] or None – A tuple of integer lists containing the interval numbers of saved output files. The order of the lists in the tuple corresponds to the order of the file patterns returned by the output_file_pattern property. If no output files are found, returns (None, …).

read_saved_output(interval=None, **kwargs)

Read the saved output files for this component and return them as xarray Datasets.

Parameters:

• interval (int or None, optional) – The interval number to read. If None, read all intervals. Default is None.

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

Returns:

tuple[xr.Dataset, …] or None – A tuple of xarray Datasets containing the data from the saved output files. The order of the Datasets in the tuple corresponds to the order of the file patterns returned by the output_file_pattern property. If no output files are found, returns (None, …).

saved_output_files(**kwargs)

Check if the component has any output files in its output directory.

Returns:

list[Path] – A list of Path objects representing the files that would be removed during a reset operation. Returns an empty list if no files found

get_time_variables(interval=None, **kwargs)

Retrieves any time-based variables (variables that have only an ‘interval’ dimension) that are stored in saved output files.

Parameters:

• interval (int or None, optional) – The interval number to retrieve the time variables for. If None, retrieves time variables for all intervals. Default is None.

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

Returns:

tuple[dict, …] or dict or None – A dictionary or tuple of dictionaries (depending on how many file save patterns there are) where the keys are the names of the time variables and the values are the corresponding values for the specified interval. If no time variables are found, returns an empty tuple.

output_filename(interval=None, **kwargs)

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.

pyvista_plotter(**kwargs)

A placeholder function that is overridden by components with a PyVista plotting method.

show3d(engine='pyvista', **kwargs)

Show the component using an interactive 3D plot.

Valid arguments are those that are passed the engine functions (e.g. arguments to pyvista_plotter(), and plotter.show())

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.

add_save_action(action)

Add an action to the save_actions property of this component.

Parameters:

action (dict[str, dict]) – A dictionary where the keys are the names of actions that can be performed on this component (e.g. “plot”) when calling the save function and the values are the arguments that should be passed to that action when it is called by the save function.

property save_actions

A dictionary where the keys are the names of actions that can be performed on this component (e.g. “plot”) when calling the save function and the values are the arguments that should be passed to that action when it is called by the save function.

property ask_overwrite

Flag to indicate whether the user should be prompted to overwrite any old files or not.

property simdir

The main project simulation directory. Default is the current working directory if None.

Returns:

Path – The initialized simulation directory as a Path object. Will be a relative path if possible, otherwise will be absolute. If it doesn’t exist, it will be created.

property output_dir

The output directory for a component. If None, the component does not have an output directory set.

property export_dir

The export directory for a component. If None, the component does not have an export directory set.

property plot_dir

The directory for plots.

property output_image_file_extension

The file extension to use for output images.

property output_file_pattern

Return a list of one or more file patterns that this component will generate when saved.

This is used when reading save output files or when restting the components. Some components may generate multiple output files with different patterns (e.g. the observed and emplaced crater files generated by the counting component), so this should return a list of all patterns that are generated by this component. If the component does not generate any files, this should return an empty list.

Returns:

list[str] – A list of file patterns (e.g., [“surface*.nc”]) that this component will generate when saved. If the component does not generate any files, return an empty list.

property output_file_prefix

Return the file prefix for this component’s output files. This is used to identify the files generated by this component when reading saved output or resetting the component. If the component does not generate any files, this should return None.

Returns:

str or None – The file prefix (e.g., “surface”) for this component’s output files, or None if the component does not generate any files.

property output_file_extension

Return the file extension for this component’s output files. This is used to identify the files generated by this component when reading saved output or resetting the component. If the component does not generate any files, this should return None.

Returns:

str or None – The file extension (e.g., “nc”) for this component’s output files, or None if the component does not generate any files.

property rng_seed

The random rng_seed for the simulation RNG.

Returns:

int or None – The integer rng_seed used to initialize the RNG, or None if not set.

property rng

The random number generator used for stochastic elements of the simulation.

Returns:

numpy.random.Generator or None – The RNG instance, or None if not initialized.

property rng_state

The state of the random number generator.

Returns:

dict or None – A dictionary representing the RNG state, or None if the RNG is not initialized.

property common_args

property driver_to_extension_map

A dictionary mapping valid export/from_file drivers for this component to the corresponding file extensions that can be used when exporting files with that driver.

property valid_drivers

A list of valid export/from_file drivers for this component.

property valid_extensions

A list of valid export/from_file file extensions for this component.

ComponentBase

This is a base class for all components in the cratermaker package. It inherits from CratermakerBase and defines additional methods and attributes that are specific to high level component classes.

class cratermaker.core.base.ComponentBase(**kwargs)

Bases: CratermakerBase, ABC

Base class for components of the Cratermaker project.

Defines the common parameters and methods for all components in the Cratermaker project, including the maker class that is used to select the correct component from user arguments.

classmethod maker(component=None, **kwargs)

Initialize a component model with the given name or instance.

Parameters:

• component (str or ComponentBase or None) – The name of the component to use, or an instance of ComponentBase. If None, it choose a default component.

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

Returns:

component – An instance of the specified component model.

Raises:

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

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

property component_name

The registered name of this component set by the @ComponentBase.register decorator.

classmethod register(name)

Class decorator to register a component model component under the given key.

classmethod available()

Return list of all registered catalogue names.

Importing components

import_components(package_name, package_path)

Import all modules of a component package, optionally skipping private modules.