MoonPIES API¶

MoonPIES¶

Moon Polar Ice and Ejecta Stratigraphy model (MoonPIES).

This module contains the main functions for running the MoonPIES model. This model simulates the evolution of polar ice and ejecta stratigraphy on the Moon over geologic time.

Authors: C.J. Tai Udovicic, K.R. Frizzell, K.M. Luchsinger, A. Madera, T.G. Paladino
Acknowledgements: This model was developed as part of the 2021 Exploration Science Summer Intern Program hosted by the Lunar and Planetary Institute with support from the Center for Lunar Science and Exploration node of the NASA Solar System Exploration Research Virtual Institute.

moonpies.moonpies.main(cfg=CFG)[source]¶

Run MoonPIES model and return stratigraphy columns.

Runs full ejecta and ice straitigraphy model for time, cold traps and model parameters specified in cfg.

Parameters

cfgmoonpies.config.Cfg: MoonPIES config object.

Returns

strat_dictdict: Dict of {str:pandas.DataFrame} of coldtrap names and stratigraphy tables (rows: layers, cols: ice, ejecta, source, time, depth, ice%)

See also

moonpies.config.Cfg

Examples

>>> import moonpies as mp
>>> ej_df, ice_df, strat_dfs = mp.main()
>>> print(strat_dfs['Faustini'].head())

moonpies.moonpies.get_time_array(cfg=CFG)[source]¶

Return model time array [yr].

Parameters

cfgmoonpies.config.Cfg, optional

cfg.timestartint: Start time [yr].
cfg.timeendint: End time [yr].
cfg.timestepint: Time step [yr].

Returns

time_arrnp.ndarray

moonpies.moonpies.init_strat_columns(time_arr, df, ej_dists, cfg=CFG, rng=None)[source]¶

Return initialized model stratigraphy columns.

Initialize dict of list (ice, ej, ej_sources) for each cold trap. Computes the ice and ejecta delivered in each model timestep to each cold trap.

Parameters

time_arrnumpy.ndarray: Time array [yr].
dfpandas.DataFrame: Crater and basin DataFrame.
ej_distsnumpy.ndarray: 2D crater to cold trap distance array [m] (Ncrater, Ncoldtrap).
cfgmoonpies.config.Cfg, optional: MoonPIES config object.
rngint or numpy.random.Generator, optional: Random seed or random number generator, by default None.

Returns

dict: Dict of {str : list of array} of coldtrap names to [ice, ej, ej_src].

See also

get_ejecta_thickness_time, get_ice_cols_time

moonpies.moonpies.update_ice_col(ice_col, ej_col, t, overturn_d, bsed_d, bsed_frac, cfg=CFG)[source]¶

Return ice_column updated with all processes applicable at time t.

Apply effects of impact gardening (overturn) and ballistic sedimentation (bsed) at time t to ice_col. Modifies ice_col in place.

Parameters

ice_columpy.ndarray: Ice column array.
ej_colnumpy.ndarray: Ejecta column array.
tint: Current time index.
overturn_dfloat: Overturn depth [m] at timestep t.
bsed_dfloat: Ballistic sedimentation depth [m] at timestep t.
bsed_fracfloat: Ballistic sedimentation fraction at timestep t.
cfgmoonpies.config.Cfg, optional: MoonPIES config object.

Returns

ice_colnumpy.ndarray: Updated ice column arr.

See also

garden_ice_column, remove_ice_overturn

moonpies.moonpies.update_strat_cols(strat_cols, overturn, bsed_depth, bsed_frac, cfg=CFG)[source]¶

Return strat_cols dict updated with ice modification at each timestep.

Parameters

strat_colsdict: Dict of {str : list of array} of coldtrap names to [ice, ej, ej_src].
overturnnumpy.ndarray: Overturn depth array [m] (Ntime).
bsed_depthnumpy.ndarray: Ballistic sedimentation depth array [m] (Ntime).
bsed_fracnumpy.ndarray: Ballistic sedimentation fraction array (Ntime).
cfgmoonpies.config.Cfg, optional: MoonPIES config object.

Returns

strat_colsdict: Updated strat_cols dict.

See also

update_ice_col

moonpies.moonpies.get_crater_basin_list(cfg=CFG, rng=None)[source]¶

Return dataframe of craters with ages randomized.

Parameters

cfgmoonpies.config.Cfg, optional: MoonPIES config object.
rngint or numpy.random.Generator, optional: Random seed or random number generator, by default None.

Returns

pandas.DataFrame: Crater and basin DataFrame.

See also

random_icy_basins, randomize_crater_ages

moonpies.moonpies.random_icy_basins(df, cfg=CFG, rng=None)[source]¶

Randomly assign each basin an impactor type determining hydration.

Probability of hydration and comet based on cfg. Possible icy_impactor types are {“hyd_ctype”, “comet”, or “no”}.

Parameters

dfpandas.DataFrame

Basin DataFrame.

cfgmoonpies.config.Cfg, optional

cfg.impact_ice_basinsbool: Whether to allow basins to be icy.
cfg.impact_ice_cometsbool: Whether to allow comet impactors.

rngint or numpy.random.Generator, optional

Random seed or random number generator, by default None.

Returns

pandas.DataFrame: Basin DataFrame with icy_impactor column added.

See also

get_random_hydrated_basins

moonpies.moonpies.read_crater_list(cfg=CFG)[source]¶

Return DataFrame of craters from cfg.crater_csv_in.

Required columns, names and units in cfg.crater_csv_in:

‘lat’: Latitude [deg]
‘lon’: Longitude [deg]
‘diam’: Diameter [km]
‘age’: Crater age [Gyr]
‘age_low’: Age error residual, lower (e.g., age - age_low) [Gyr]
‘age_upp’: Age error residual, upper (e.g., age + age_upp) [Gyr]

Optional columns in cfg.crater_csv_in:

‘psr_area’: Permanently shadowed area of crater [km^2]

Parameters

cfgmoonpies.config.Cfg, optional

cfg.crater_csv_instr: Path to crater CSV file.
cfg.crater_colstuple of str: Tuple of column names in cfg.crater_csv_in.

Returns

pandas.DataFrame: Crater DataFrame.

moonpies.moonpies.read_basin_list(cfg=CFG)[source]¶

Return dataframe of craters from basin_csv path with columns names.

Required columns, names and units in cfg.basin_csv_in:

‘lat’: Latitude [deg]
‘lon’: Longitude [deg]
‘diam’: Diameter [km]
‘age’: Crater age [Gyr]
‘age_low’: Age error residual, lower (e.g., age - age_low) [Gyr]
‘age_upp’: Age error residual, upper (e.g., age + age_upp) [Gyr]

Parameters

cfgmoonpies.config.Cfg, optional

cfg.basin_csv_instr: Path to basin CSV file.
cfg.basin_colstuple of str: Tuple of column names in cfg.basin_csv_in.

Returns

pandas.DataFrame: Basin DataFrame.

moonpies.moonpies.read_volcanic_species(cfg=CFG)[source]¶

Return DataFrame of time, species mass from Table S3 [1].

Parameters

cfgmoonpies.config.Cfg, optional

cfg.nk_csv_instr: Path to Table S3 [1] CSV file.
cfg.nk_colstuple of str: Tuple of column names in cfg.nk_csv_in.
cfg.speciesstr: Species name (must be in nk_cols).

Returns

pandas.DataFrame: DataFrame with columns “time” and species.

References

1: Needham, D. H., & Kring, D. A. (2017). “Lunar volcanism produced a transient atmosphere around the ancient Moon.” Earth and Planetary Science Letters, 478, 175-178. https://doi.org/10.1016/j.epsl.2017.09.002

moonpies.moonpies.read_solar_luminosity(cfg=CFG)[source]¶

Return DataFrame of time, solar luminosity from Table 2 [1].

Parameters

cfgmoonpies.config.Cfg, optional

cfg.bahcall_csv_instr: Path to CSV of Table 2 [1].

Returns

pandas.DataFrame: DataFrame with columns “time” and “luminosity”.

References

1: Bahcall, J. N., Pinsonneault, M. H., & Basu, S. (2001). “Solar Models: Current Epoch and Time Dependences, Neutrinos, and Helioseismological Properties.” The Astrophysical Journal, 555(2), 990-1012. https://doi.org/10/dv2q29

moonpies.moonpies.read_ballistic_melt_frac(mean=True, cfg=CFG)[source]¶

Return DataFrame of ballistic sedimentation melt fractions.

Parameters

meanbool, optional

If True, return mean melt fraction. If False, return standard dev

cfgmoonpies.config.Cfg, optional

cfg.bsed_frac_mean_instr: CSV of ballistic sedimentation melt fractions.

Returns

pandas.DataFrame: Melt fractions (index: mixing ratio, cols: ejecta temperature).

moonpies.moonpies.get_coldtrap_dists(df, cfg=CFG)[source]¶

Return great circle distance between all craters and coldtraps.

Returns a 2D array (rows: craters from df, cols: cold traps from cfg.coldtrap_names, in order). Elements are NaN for distance from crater to its own cold trap or distance further than ejecta_threshold radii.

Parameters

dfpandas.DataFrame

Crater DataFrame.

cfgmoonpies.config.Cfg, optional

cfg.coldtrap_namestuple of str: Tuple of cold trap names.
cfg.ejecta_thresholdfloat: Continuous ejecta threshold distance [crater radii].
cfg.basin_ej_thresholdfloat: Continuous ejecta threshold distance for basins [basin radii].

Returns

numpy.ndarray: 2D array of distances from craters to cold traps (Ncrater, Ncoldtrap).

moonpies.moonpies.get_ejecta_thickness(distance, radius, cfg=CFG)[source]¶

Return ejecta thickness as a function of distance given crater radius.

Parameters

distancenumpy.ndarray

Distance from crater center [m].

radiusfloat

Crater radius [m].

cfgmoonpies.config.Cfg, optional

cfg.simple2complexfloat: Simple to complex transition diameter [m]
cfg.complex2peakringfloat: Complex to peak ring basin transition diameter [m]

Returns

thicknessnumpy.ndarray: Ejecta thickness [m] at distance.

See also

get_ej_thick_simple, get_ej_thick_complex, get_ej_thick_basin

moonpies.moonpies.get_ej_thick_simple(distance, radius, cfg=CFG)[source]¶

Return ejecta thickness with distance from a simple crater [1].

Parameters

distancenumpy.ndarray

Distance from crater center [m].

radiusfloat

Crater final radius [m].

cfgmoonpies.config.Cfg, optional

cfg.ej_thickness_expfloat: Ejecta thickness exponent, default: -3.

Returns

thicknessnumpy.ndarray: Ejecta thickness [m] at distance.

References

1: Kring, D. A. (1995). “The dimensions of the Chicxulub impact crater and impact melt sheet.” Journal of Geophysical Research, 100(E8), 16979. https://doi.org/10/fphq8j

moonpies.moonpies.get_ej_thick_complex(distance, radius, cfg=CFG)[source]¶

Return ejecta thickness with distance from a complex crater [1].

Parameters

distancenumpy.ndarray

Distance from crater center [m].

radiusfloat

Crater final radius [m].

cfgmoonpies.config.Cfg, optional

cfg.ej_thickness_expfloat: Ejecta thickness exponent, default: -3.

Returns

thicknessnumpy.ndarray: Ejecta thickness [m] at distance.

References

1: Kring, D. A. (1995). “The dimensions of the Chicxulub impact crater and impact melt sheet.” Journal of Geophysical Research, 100(E8), 16979. https://doi.org/10/fphq8j

moonpies.moonpies.get_ej_thick_basin(distance, t_radius, cfg=CFG)[source]¶

Return ejecta thickness with distance from a basin [1].

Uses Pike (1974) and Haskin et al. (2003) correction for curvature as described in [1].

Parameters

distancenumpy.ndarray

Distance from crater center [m].

t_radiusfloat

Basin transient crater radius [m].

cfgmoonpies.config.Cfg, optional

cfg.ej_thickness_expfloat: Ejecta thickness exponent, default: -3.
cfg.rad_moonfloat: Lunar radius [m].
cfg.grav_moonfloat: Lunar gravity [m/s^2].
cfg.impact_anglefloat: Impact angle [deg].

Returns

thicknessnumpy.ndarray: Ejecta thickness [m] at distance.

References

1: Zhang, X., Xie, M., & Xiao, Z. (2021). “Thickness of orthopyroxene- rich materials of ejecta deposits from the south pole-Aitken basin.” Icarus, 358, 114214. https://doi.org/10/gmfc53

moonpies.moonpies.get_ejecta_thickness_time(time_arr, df, ej_distances, cfg=CFG)[source]¶

Return ejecta thickness and ejecta sources at each time.

Ejecta layers smaller than cfg.thickness_min are set to 0.

Parameters

time_arrnumpy.ndarray

Time array [yr].

dfpandas.DataFrame

Crater DataFrame.

ej_distancesnumpy.ndarray

2D array of crater to cold trap distances [m].

cfgmoonpies.config.Cfg, optional

cfg.thickness_minfloat: Minimum ejecta layer thickness [m].

Returns

thickness_timenumpy.ndarray: 2D array ejecta thickness [m] at each time (Ntime, Ncoldtrap).
sources_timenumpy.ndarray of str: 2D array of ejecta source(s) at each time (Ntime, Ncoldtrap).

See also

get_ejecta_thickness_matrix

moonpies.moonpies.get_ejecta_thickness_matrix(df, ej_dists, cfg=CFG)[source]¶

Return ejecta thickness from each crater to each cold trap.

Rows are craters in df, columns are cold traps from cfg.coldtrap_names.

Parameters

dfpandas.DataFrame: Crater DataFrame.
ej_distsnumpy.ndarray: 2D array of crater to cold trap distances [m] (Ncrater, Ncoldtrap).

Returns

thicknessnumpy.ndarray: 2D array of ejecta thickness [m] (Ncrater, Ncoldtrap).

See also

get_ejecta_thickness_time, get_ejecta_thickness

moonpies.moonpies.ages2time(time_arr, ages, values, agg=np.nansum, fillval=0, dtype=None, cfg=CFG)[source]¶

Return values shaped like time_arr given corresponding ages.

Rounds ages to nearest time in time_arr. If multiple values have the same age, they are combined using agg. Times with no ages are set to fillval.

Parameters

time_arrnumpy.ndarray

Time array [yr].

agesnumpy.ndarray

Age of each value [yr].

valuesnumpy.ndarray

Values to reshape (must be same length as ages).

aggcallable, optional

Function to combine multiple values of same age, by default np.nansum.

fillvalint, optional

Value to use as default (all times lacking a value), by default 0.

dtypedata-type, optional

Data type of output, by default same as values.

cfgmoonpies.config.Cfg, optional

cfg.rtolfloat: Relative tolerance for time comparison to avoid rounding error.

Returns

values_timenumpy.ndarray: Values reshaped like time_arr.

moonpies.moonpies.get_ice_cols_time(time_arr, df, cfg=CFG, rng=None)[source]¶

Return ice thickness from all sources at all times for each cold trap.

Combines polar ice and volcanic-derived ice and applies ballistic hop efficiency to determine amount of ice that reaches each cold trap.

Parameters

time_arrnumpy.ndarray

Time array [yr].

dfpandas.DataFrame

Crater DataFrame.

cfgmoonpies.config.Cfg, optional

cfg.coldtrap_nameslist of str: Names of cold traps.
cfg.ballistic_hop_mooresbool: Use Moores et al. (2016) ballistic hop model for ice deposition.

rngint or numpy.random.Generator, optional

Random seed or random number generator, by default None.

Returns

ice_timenumpy.ndarray: 2D array of ice thickness [m] at each time (Ntime, Ncoldtrap).

See also

get_polar_ice, get_volcanic_ice

moonpies.moonpies.get_polar_ice(time_arr, df, cfg=CFG, rng=None)[source]¶

Return total polar ice at all timesteps from all sources.

Parameters

time_arrnumpy.ndarray: Time array [yr].
dfpandas.DataFrame: Crater DataFrame.
cfgmoonpies.config.Cfg, optional: MoonPIES config object.
rngint or numpy.random.Generator, optional: Random seed or random number generator, by default None.

Returns

ice_timenumpy.ndarray: Total ice delivered to the pole [m] at each time.

See also

get_impact_ice, get_impact_ice_comet, get_solar_wind_ice

moonpies.moonpies.get_ice_thickness(global_ice_mass, cfg=CFG)[source]¶

Return polar ice thickness [m] given globally delivered ice mass [kg].

Assumes ice is uniformly distributed over polar coldtrap area and has a constant ice density. Scale by amount of global ice that reaches poles.

Parameters

global_ice_massnp.ndarray

Ice delivered globally [kg].

cfgmoonpies.config.Cfg, optional

cfg.ice_speciesstr: Ice species {“H2O”, “CO2”}.
cfg.coldtrap_area_H2O, cfg.coldtrap_area_CO2float: Area of cold traps [m^2].
cfg.ballistic_hop_effcyfloat: Ballistic hop efficiency (fraction of ice that reaches poles).
cfg.ice_densityfloat: Ice density [kg/m^3].

Returns

ice_thicknessnp.ndarray: Polar ice thickness [m].

moonpies.moonpies.get_solar_wind_ice(time_arr, cfg=CFG)[source]¶

Return thickness of solar wind ice at all times.

Parameters

time_arrnumpy.ndarray: Time array [yr].
cfgmoonpies.config.Cfg, optional: MoonPIES config object.

Returns

ice_timenumpy.ndarray: Thickness of solar wind ice delivered [m] at each time.

See also

solar_wind_ice_mass, get_ice_thickness

moonpies.moonpies.solar_wind_ice_mass(time_arr, cfg=CFG)[source]¶

Return global solar wind ice mass [kg] deposited at each time.

H2O supply rate is given by cfg.solar_wind_mode (“Benna”: 2g/s [1], “Lucey-Hurley”: H2 supply of 30 g/s, H2 -> H2O at 1 ppt [2]). If cfg.faint_young_sun, scale solar wind H2O supply rate by relative solar luminosity at each time [3].

Parameters

time_arrnumpy.ndarray

Time array [yr].

cfgmoonpies.config.Cfg, optional

cfg.solar_wind_modestr: Solar wind ice mode {“Benna”, “Lucey-Hurley”}.
cfg.faint_young_sunbool: Use faint young sun model.

Returns

ice_massnumpy.ndarray: Global solar wind ice mass [kg] deposited at each time.

References

1: Benna, M., Hurley, D. M., Stubbs, T. J., Mahaffy, P. R., & Elphic, R. C. (2019). “Lunar soil hydration constrained by exospheric water liberated by meteoroid impacts.” Nature Geoscience, 12(5), 333-338. https://doi.org/10/c4nz
2: Lucey, P. G., Costello, E. S., Hurley, D. M., Prem, P., Farrell, W. M., Petro, N., & Cable, M. L. (2020). Relative Magnitudes of Water Sources to the Lunar Poles. LPS LI, Abstract # 2319. Retrieved from https://www.hou.usra.edu/meetings/lpsc2020/pdf/2319.pdf
3: Bahcall, J. N., Pinsonneault, M. H., & Basu, S. (2001). “Solar Models: Current Epoch and Time Dependences, Neutrinos, and Helioseismological Properties.” The Astrophysical Journal, 555(2), 990-1012. https://doi.org/10/dv2q29

moonpies.moonpies.get_volcanic_ice(time_arr, cfg=CFG)[source]¶

Return ice thickness [m] delivered to pole by volcanics at each time.

Parameters

time_arrnumpy.ndarray

Time array [yr].

cfgmoonpies.config.Cfg, optional

cfg.volc_modestr: Volcanic ice mode {“NK”, “Head”}.

Returns

ice_timenumpy.ndarray: Thickness of volcanic ice delivered [m] at each time.

See also

volcanic_ice_nk, volcanic_ice_head

moonpies.moonpies.volcanic_ice_nk(time_arr, cfg=CFG)[source]¶

Return global ice mass [kg] deposited at each time using [1]_.

Parameters

time_arrnumpy.ndarray: Time array [yr].
cfgmoonpies.config.Cfg, optional: cfg.volc_mode : str

Returns

ice_massnumpy.ndarray: Global volcanic ice mass [kg] deposited at each time.

moonpies.moonpies.volcanic_ice_head(time_arr, cfg=CFG)[source]¶

Return global ice [kg] deposited at each time using Head et al. (2020).

Parameters

time_arrnumpy.ndarray

Time array [yr].

cfgmoonpies.config.Cfg, optional

cfg.volc_total_volfloat: Total volcanics volume [km^3].
cfg.volc_magma_densityfloat: Magma density [kg/m^3].
cfg.volc_ice_ppmfloat: Volcanic volatile concentration [ppm].
cfg.volc_earlytuple of float: Early volcanism time period (start, end) [yr].
cfg.volc_early_pctfloat: Percent of total volcanics delivered during volc_early.
cfg.volc_latetuple of float: Late volcanism time period (start, end) [yr].
cfg.volc_late_pctfloat: Percent of total volcanics delivered during volc_late.

Returns

ice_massnumpy.ndarray: Global volcanic ice mass [kg] deposited at each time.

moonpies.moonpies.get_melt_frac(ejecta_temps, mixing_ratios, cfg=CFG)[source]¶

Return fraction of ice melted at given ejecta_temps and vol_fracs.

Parameters

ejecta_tempsnumpy.ndarray: Ejecta temperatures [K].
mixing_ratiosnumpy.ndarray: Mixing ratios (target:ejecta).
cfgmoonpies.config.Cfg, optional: MoonPIES config object.

Returns

melt_fracnumpy.ndarray: Fraction of ice melted at each ejecta_temp and mixing ratio.

See also

read_ballistic_melt_frac

moonpies.moonpies.kinetic_energy(mass, velocity)[source]¶: Return kinetic energy [J] given mass [kg] and velocity [m/s].

moonpies.moonpies.ejecta_temp(df, shape=None, cfg=CFG)[source]¶

Return ejecta temperature [K].

Parameters

dfpandas.DataFrame

Crater DataFrame.

shapetuple, optional

Shape of output, by default (len(df),)

cfgmoonpies.config.Cfg, optional

cfg.polar_ejecta_temp_initfloat: Initial polar ejecta temperature [K].
cfg.basin_ejecta_temp_warmbool: If True, use warm ejecta temperatures for basins, otherwise cold.
cfg.basin_ejecta_temp_init_warmfloat: Initial warm basin ejecta temperature [K].
cfg.basin_ejecta_temp_init_coldfloat: Initial cold basin ejecta temperature [K].

Returns

ejecta_tempnumpy.ndarray: Ejecta temperature [K] for each impact in df.

moonpies.moonpies.ballistic_velocity(dist, cfg=CFG)[source]¶

Return ballistic velocity given distance of travel on a sphere [1].

Parameters

distnumpy.ndarray

Distance of travel [m].

cfgmoonpies.config.Cfg, optional

cfg.grav_moonfloat: Lunar gravity [m/s^2].
cfg.rad_moonfloat: Lunar radius [m].
cfg.impact_anglefloat: Impact angle [deg].

Returns

velocitynumpy.ndarray: Ballistic velocity [m/s].

References

1: Vickery, A. (1986). “Size-velocity distribution of large ejecta fragments.” Icarus, 67(2), 224-236. https://doi.org/10/bjjk93

moonpies.moonpies.get_bsed_depth(time_arr, df, ej_dists, cfg=CFG)[source]¶

Return ballistic sedimentation depth over time [1].

If more than one ballistic sedimentation event occurs in a timestep, take the maximum depth and melt fraction. TODO: make sequential.

Parameters

time_arrnumpy.ndarray: Time array [yr].
dfpandas.DataFrame: Crater DataFrame.
ej_distsnumpy.ndarray: 2D array of ejecta distances [m] (Ncrater, Ncoldtrap).
cfgmoonpies.config.Cfg, optional

Returns

depthsnumpy.ndarray: 2D array of ballistic sedimentation depths [m] (Ntime, Ncoldtrap).
melt_fracsnumpy.ndarray: 2D array of melt fractions (Ntime, Ncoldtrap).

See also

get_mixing_ratio_oberbeck, ejecta_temp, get_melt_frac

References

1: Zhang, X., Xie, M., & Xiao, Z. (2021). “Thickness of orthopyroxene- rich materials of ejecta deposits from the south pole-Aitken basin.” Icarus, 358, 114214. https://doi.org/10/gmfc53

moonpies.moonpies.get_mixing_ratio_oberbeck(ej_distances, cfg=CFG)[source]¶

Return mixing ratio of target to ejecta material [1].

If cfg.mixing_ratio_petro, use the adjustment for large mr from [2].

Parameters

ej_distancesnumpy.ndarray

2D array of ejecta distances [m] (Ncrater, Ncoldtrap).

cfgmoonpies.config.Cfg, optional

cfg.mixing_ratio_afloat: Mixing ratio factor a [1].
cfg.mixing_ratio_bfloat: Mixing ratio exponent b [2].
cfg.mixing_ratio_petrobool: If True, adjust large mixing ratios using [2]

Returns

mixing_rationumpy.ndarray: 2D array of mixing ratios (target:ejecta) (Ncrater, Ncoldtrap).

References

1: Oberbeck, V. R. (1975). “The role of ballistic erosion and sedimentation in lunar stratigraphy.” Reviews of Geophysics, 13(2), 337-362. https://doi.org/10/bcxqfb
2: Petro, N. E., & Pieters, C. M. (2006). “Modeling the provenance of the Apollo 16 regolith.” Journal of Geophysical Research, 111(E9), E09005. https://doi.org/10/dbwzmv

moonpies.moonpies.remove_ice_overturn(ice_col, ej_col, t, depth, cfg=CFG)[source]¶

Return ice_col gardened to depth below time t.

Parameters

ice_colnumpy.ndarray

Ice column [m].

ej_colnumpy.ndarray

Ejecta column [m].

tint

Time index.

depthfloat

Impact gardening depth [m].

cfgmoonpies.config.Cfg, optional

cfg.impact_gardening_costellobool: If True, use Costello impact gardening model, else use Cannon.

Returns

ice_colnumpy.ndarray: Ice column [m] with impact gardening applied.

See also

garden_ice_column, erode_ice_cannon

moonpies.moonpies.erode_ice_cannon(ice_col, ej_col, t, erosion_depth=0.1, ej_shield=0.4)[source]¶

Return ice_col gardened to erosion_depth below time t [1].

Translated directly from Cannon et al. (2020) MATLAB code [1].

Parameters

ice_colnumpy.ndarray: Ice column [m].
ej_colnumpy.ndarray: Ejecta column [m].
tint: Time index.
erosion_depthfloat, optional: Erosion depth [m], by default 0.1
ej_shieldfloat, optional: Ejecta shield thickness [m], by default 0.4

Returns

ice_colnumpy.ndarray: Ice column [m] with impact gardening applied.

References

1: Cannon, K. M., Deutsch, A. N., Head, J. W., & Britt, D. T. (2020). “Stratigraphy of Ice and Ejecta Deposits at the Lunar Poles.” Geophysical Research Letters, 47(21). https://doi.org/10/gksdcc

moonpies.moonpies.garden_ice_column(ice_column, ejecta_column, t, depth, eff=1)[source]¶

Return ice_column gardened to depth, but preserved by ejecta_column.

Ejecta deposited on last timestep preserves ice. Loop through ice_col and ejecta_col until overturn_depth and remove all ice that is encountered.

Parameters

ice_columnnumpy.ndarray: Ice column [m].
ejecta_columnnumpy.ndarray: Ejecta column [m].
tint: Time index.
depthfloat: Impact gardening depth [m].
efffloat, optional: Fraction to remove from each layer in [0, 1], by default 1 (all).

Returns

ice_columnnumpy.ndarray: Ice column [m] with impact gardening applied.

moonpies.moonpies.overturn_depth_time(time_arr, cfg=CFG)[source]¶

Return overturn depth [m] at each time.

Parameters

time_arrnumpy.ndarray

Time array [yr].

cfgmoonpies.config.Cfg, optional

cfg.impact_gardening_costellobool: If True, get overturn over time, else use cfg.ice_erosion_rate.
cfg.ice_erosion_ratefloat: Constant ice erosion rate [m/10 Ma].
cfg.timestepfloat: Timestep [yr] to scale cfg.ice_erosion_rate.

Returns

overturn_depthnumpy.ndarray: Overturn depth [m] at each time.

See also

overturn_depth_costello_time

moonpies.moonpies.overturn_depth_costello_time(time_arr, cfg=CFG)[source]¶

Return regolith overturn depth at each time [1].

Parameters

time_arrnumpy.ndarray

Time array [yr].

cfgmoonpies.config.Cfg, optional

cfg.overturn_ancient_t0float: Time when ancient overturn rate becomes present rate [yr].
cfg.overturn_depth_presentfloat: Present-day overturn depth per cfg.timestep [m].
cfg.overturn_ancient_slopefloat: Slope of ancient overturn depth [m/yr].

Returns

overturn_depthnumpy.ndarray: Overturn depth [m] at each time.

References

1: Costello, E. S., Ghent, R. R., Hirabayashi, M., & Lucey, P. G. (2020). “Impact Gardening as a Constraint on the Age, Source, and Evolution of Ice on Mercury and the Moon.” Journal of Geophysical Research: Planets, 125(3). https://doi.org/10/gk56kr

moonpies.moonpies.get_impact_ice(time_arr, df, cfg=CFG, rng=None)[source]¶

Return polar ice thickness [m] from global impacts at each time.

Parameters

time_arrnumpy.ndarray

Time array [yr].

dfpandas.DataFrame

Crater dataframe.

cfgmoonpies.config.Cfg, optional

cfg.impact_ice_basinsbool: If True, add basin ice contributions

rngint or numpy.random.Generator, optional

Random number generator or seed.

Returns

ice_timenumpy.ndarray: Polar ice thickness [m] at each time.

moonpies.moonpies.get_comet_cfg(cfg)[source]¶

Return config with impact parameters updated to comet values.

Sets cfg.is_comet, cfg.hydrated_wt_pct, cfg.impactor_density, cfg.impact_mass_retained to comet counterparts.

Parameters

cfgmoonpies.config.Cfg: MoonPIES config object.

Returns

comet_cfgmoonpies.config.Cfg: MoonPIES config object with comet parameters set.

moonpies.moonpies.get_impact_ice_comet(time_arr, df, cfg, rng=None)[source]¶

Return polar ice thickness [m] from comet impacts at each time.

Parameters

time_arrnumpy.ndarray: Time array [yr].
dfpandas.DataFrame: Crater dataframe.
cfgmoonpies.config.Cfg: MoonPIES config object.
rngint or numpy.random.Generator, optional: Random number generator or seed.

Returns

ice_timenumpy.ndarray: Comet polar ice thickness [m] at each time.

moonpies.moonpies.get_micrometeorite_ice(time_arr, cfg=CFG)[source]¶

Return ice thickness [m] delivered to pole due to micrometeorites vs time.

Returns

mm_ice_t (arr): Ice thickness [m] delivered to pole at each time.

moonpies.moonpies.get_small_impactor_ice(time_arr, cfg=CFG)[source]¶

Return ice thickness [m] delivered to pole due to small impactors vs time.

Returns

si_ice_t (arr): Ice thickness [m] delivered to pole at each time.

moonpies.moonpies.get_small_simple_crater_ice(time_arr, cfg=CFG)[source]¶

Return ice thickness [m] delivered to pole by small simple crater impacts.

Returns

ssc_ice_t (arr): Ice thickness [m] delivered to pole at each time.

moonpies.moonpies.get_large_simple_crater_ice(time_arr, cfg=CFG, rng=None)[source]¶

Return ice thickness [m] delivered to pole by large simple crater impacts.

Returns

lsc_ice_t (arr): Ice thickness [m] delivered to pole at each time.

moonpies.moonpies.get_complex_crater_ice(time_arr, cfg=CFG, rng=None)[source]¶

Return ice thickness [m] delivered to pole by complex crater impacts.

Returns

cc_ice_t (arr): Ice thickness [m] delivered to pole at each time.

moonpies.moonpies.get_basin_ice(time_arr, df, cfg=CFG, rng=None)[source]¶

Return ice thickness [m] delivered to pole by basin impacts vs time.

Returns

b_ice_t (arr): Ice thickness [m] delivered to pole at each time.

moonpies.moonpies.get_ice_stochastic(time_arr, regime, cfg=CFG, rng=None)[source]¶

Return ice mass [kg] delivered to pole at each time from stochastic delivery by crater-forming impactors.

Parameters

time_arr (arr): Array of times [yr] to calculate ice thickness at.
regime (str): Regime of ice production.
cfg (Cfg): Config object.
rng (int or numpy.random.Generator): Seed or random number generator.

Returns

ice_t (arr): Ice mass [kg] delivered to pole at each time.

moonpies.moonpies.read_ballistic_hop_csv(bhop_csv)[source]¶: Return dict of ballistic hop efficiency of each coldtrap in bhop_csv.

moonpies.moonpies.get_ballistic_hop_coldtraps(coldtraps, cfg=CFG)[source]¶

Return ballistic hop efficiency as row vector of coldtraps [1,N].

Parameters

coldtraps (list of str): Desired coldtraps.
cfg (Cfg): Configuration object.

Returns

bhop (arr): Ballistic hop efficiency of coldtraps.

moonpies.moonpies.ice_micrometeorites(time, cfg=CFG)[source]¶

Return ice from micrometeorites (Regime A, Cannon 2020).

Multiply total_mm_mass / yr by timestep and scale by assumed hydration % and scale by ancient flux relative to today.

Unlike larger impactors, we DO NOT assume ctype composition and fraction of hydrated ctypes and also DO NOT scale by asteroid retention rate. TODO: are these reasonable assumptions?

moonpies.moonpies.ice_small_impactors(diams, impactors_t, cfg=CFG)[source]¶: Return ice mass [kg] from small impactors (Regime B, Cannon 2020) given impactor diams and number of impactors over time.

moonpies.moonpies.ice_small_craters(crater_diams, ncraters, regime, cfg=CFG)[source]¶: Return ice from simple craters, steep branch (Regime C, Cannon 2020).

moonpies.moonpies.ice_large_craters(crater_diams, impactor_speeds, regime, cfg=CFG)[source]¶: Return ice from simple/complex craters, shallow branch of sfd (Regime D-E, Cannon 2020).

moonpies.moonpies.ice_basins(df, time_arr, cfg=CFG, rng=None)[source]¶: Return ice mass [kg] from basin impacts vs time.

moonpies.moonpies.ice_retention_factor(speeds, cfg)[source]¶

Return ice retained in impact, given impactor speeds (Ong et al. 2010).

For speeds < 10 km/s, retain 50% (Svetsov & Shuvalov 2015 via Cannon 2020). For speeds >= 10 km/s, use fit Fig 2 (Ong et al. 2010 via Cannon 2020)

moonpies.moonpies.impactor_mass2water(impactor_mass, cfg)[source]¶

Return water [kg] from impactor mass [kg] using assumptions of Cannon 2020:

36% of impactors are C-type (Jedicke et al., 2018)

2/3 of C-types are hydrated (Rivkin, 2012)

Hydrated impactors are 10% water by mass (Cannon et al., 2020)

16% of asteroid mass retained on impact (Ong et al., 2010)

for comets:

assume 50% of comet hydrated
6.5% of comet mass retained on impact (Ong et al., 2010)

moonpies.moonpies.get_rng(cfg=CFG)[source]¶: Return numpy random number generator from given seed in rng.

moonpies.moonpies.randomize_crater_ages(df, timestep, rng=None)[source]¶

Return ages randomized with a truncated Gaussian between age_low, age_upp.

Parameters

df (DataFrame): Crater dataframe with age, age_low, age_upp columns.
timestep (int): Timestep [yr].
rng (int or numpy.random.Generator): Seed or random number generator.

moonpies.moonpies.get_random_hydrated_craters(n, cfg=CFG, rng=None)[source]¶

Return crater diams of hydrated craters from random distribution.

Parameters

n (int): Number of craters.
cfg (Cfg): Config object.
rng (int or numpy.random.Generator): Seed or random number generator.

moonpies.moonpies.get_random_hydrated_basins(n, cfg=CFG, rng=None)[source]¶

Return indicess of hydrated basins from random distribution with asteroids and comets mutually exclusive.

Parameters

n (int): Number of basins.
cfg (Cfg): Config object.
rng (int or numpy.random.Generator): Seed or random number generator.

moonpies.moonpies.get_random_impactor_speeds(n, cfg=CFG, rng=None)[source]¶

Return n impactor speeds from normal distribution about mean, sd.

Parameters

n (int): Number of impactors.
cfg (Cfg): Config object.
rng (int or numpy.random.Generator): Seed or random number generator.

moonpies.moonpies.asteroid_speed_rv(cfg=CFG)[source]¶: Return asteroid speed random variable object from scipy.stats.truncnorm.

moonpies.moonpies.comet_speed_rv(cfg=CFG)[source]¶: Return comet speed random variable object from scipy.stats.truncnorm.

moonpies.moonpies.neukum(diam, cfg=CFG)[source]¶

Return number of craters per m^2 per yr at diam [m] (eqn. 2, Neukum 2001).

Eqn 2 expects diam [km], returns N [km^-2 Ga^-1].

Parameters

diam (float): Crater diameter [m].
cfg (Cfg): Config object.

moonpies.moonpies.get_impactors_brown(mindiam, maxdiam, timestep, cfg=CFG)[source]¶: Return number of impactors per yr in range mindiam, maxdiam (Brown et al. 2002) and scale by Earth-Moon impact ratio (Mazrouei et al. 2019).

moonpies.moonpies.get_crater_pop(time_arr, regime, cfg=CFG)[source]¶: Return crater population assuming continuous (non-stochastic, regime c).

moonpies.moonpies.num_craters_chronology(mindiam, maxdiam, time, cfg=CFG)[source]¶: Return number of craters [m^-2 yr^-1] mindiam and maxdiam at each time.

moonpies.moonpies.get_small_impactor_pop(time_arr, cfg=CFG)[source]¶

Return population of impactors and number in regime B.

Use constants and eqn. 3 from Brown et al. (2002) to compute N craters.

moonpies.moonpies.get_crater_sfd(dmin, dmax, step, sfd_slope, dtype=None)[source]¶: Return diam_array and sfd_prob. This func makes it easier to cache both.

moonpies.moonpies.get_sfd_prob(diams, sfd_slope)[source]¶: Return size-frequency distribution probability given diams, sfd slope.

moonpies.moonpies.get_diam_array(dmin, dmax, step, dtype=None)[source]¶: Return array of diameters based on diameters from dmin, dmax, dstep.

moonpies.moonpies.impact_flux_scaling(time)[source]¶

Return the factor to scale impact flux by in the past vs. present day.

Take ratio of historical and present day impact fluxes from Ivanov 2008). Parameters ———- time (num or arr): Time [year] before present.

Returns

scaling_factor (num): Impact flux scaling factor.

moonpies.moonpies.impact_flux(time)[source]¶: Return impact flux at time [yrs] (Derivative of eqn. 1, Ivanov 2008).

moonpies.moonpies.diam2len(diams, speeds, regime, cfg=CFG)[source]¶

Return size of impactors based on crater diams and impactor speeds.

Different crater regimes are scaled via the following scaling laws: - regime==’c’: (Prieur et al., 2017) - regime==’d’: (Collins et al., 2005) - regime==’e’: (Johnson et al., 2016)

Parameters

diams (arr): Crater diameters [m].
speeds (arr): Impactor speeds [m/s].
regime (str): Crater scaling regime (‘c’, ‘d’, or ‘e’).

Returns

lengths (arr): Impactor diameters [m].

moonpies.moonpies.final2transient(diam, cfg=CFG)[source]¶

Return transient crater diameters from final crater diams (Melosh 1989).

Parameters

diams (num or array): final crater diameters [m]
g (num): gravitational force of the target body [m s^-2]
rho_t (num): target density (kg m^-3)

Returns

transient_diams (num or array): transient crater diameters [m]

moonpies.moonpies.f2t_melosh(diam, simple=True, ds2c=18e3, gamma=1.25, eta=0.13)[source]¶

Return transient crater diameter(s) from final crater diam (Melosh 1989).

Parameters

diams (num or array): final crater diameters [m]
simple (bool): if True, use simple scaling law (Melosh 1989).

moonpies.moonpies.f2t_croft(diam, ds2c=18.7e3, eta=0.18)[source]¶: Return transient crater diameter(s) fom final crater diam (Croft 1985).

moonpies.moonpies.diam2len_prieur(t_diam, v=20e3, rho_i=1300, rho_t=1500, g=1.62, dtype=None)[source]¶

Return impactor length from input diam using Prieur et al. (2017) method.

Note: Interpolates impactor lengths from the forward Prieur impactor length to transient crater diameter equation.

Parameters

t_diam (num or array): transient crater diameter [m]
speeds (num): impact speed (m s^-1)
rho_i (num): impactor density (kg m^-3)
rho_t (num): target density (kg m^-3)
g (num): gravitational force of the target body (m s^-2)

Returns

impactor_length (num): impactor diameter [m]

moonpies.moonpies.diam2len_collins(t_diam, v=20e3, rho_i=1300, rho_t=1500, g=1.62, theta=45)[source]¶

Return impactor length from input diam using Collins et al. (2005) method.

Parameters

t_diam (num or array): transient crater diameter [m]
speeds (num): impact speed (m s^-1)
rho_i (num): impactor density (kg m^-3)
rho_t (num): target density (kg m^-3)
g (num): gravitational force of the target body (m s^-2)
theta (num): impact angle (degrees)

Returns

impactor_length (num): impactor diameter [m]

moonpies.moonpies.diam2len_johnson(diam, v=20e3, rho_i=1300, rho_t=1500, g=1.62, theta=45, ds2c=18e3)[source]¶

Return impactor length from final crater diam using Johnson et al. (2016).

Parameters

diam (num or array): crater diameter [m]
speeds (num): impact speed (m s^-1)
rho_i (num): impactor density (kg m^-3)
rho_t (num): target density (kg m^-3)
g (num): gravitational force of the target body (m s^-2)
theta (num): impact angle (degrees)

Returns

impactor_length (num): impactor diameter [m]

moonpies.moonpies.specific_heat_capacity(T, cfg=CFG)[source]¶

Return specific heat capacity [J/kg/K] at temperature T [K] for lunar regolith (Hayne et al., 2017).

Parameters

T (num or array): temperature [K]
cfg (Cfg): Config object with specific_heat_coeffs

moonpies.moonpies.get_grid_outputs(df, grdx, grdy, cfg=CFG)[source]¶

Return gridded age of most recent impact and ejecta thickness.

Parameters

dfpandas.DataFrame: Crater DataFrame.
grdxnumpy.ndarray: Grid x-coordinates [m].
grdynumpy.ndarray: Grid y-coordinates [m].
cfgmoonpies.config.Cfg, optional: MoonPIES config object.

Returns

age_gridnumpy.ndarray: Gridded ages of last impact [yr] (Ny, Nx).
thickness_gridnumpy.ndarray: Gridded ejecta thickness [m] (Ny, Nx, Ncoldtraps).

See also

get_age_grid, get_gc_dist_grid, get_ejecta_thickness_matrix

moonpies.moonpies.get_gc_dist_grid(df, grdx, grdy, cfg=CFG)[source]¶

Return gridded great circle distance from each crater

Parameters

dfpandas.DataFrame: Crater DataFrame.
grdxnumpy.ndarray: Grid x-coordinates [m].
grdynumpy.ndarray: Grid y-coordinates [m].
cfgmoonpies.config.Cfg, optional

Returns

distance_gridnumpy.ndarray: Gridded from each crater in df [m] (Ny, Nx, Ncrater).

See also

gc_dist

moonpies.moonpies.get_age_grid(df, grdx, grdy, cfg=CFG)[source]¶

Return final surface age of each grid point after all craters formed.

Parameters

dfpandas.DataFrame

Crater DataFrame.

grdxnumpy.ndarray

Grid x-coordinates [m].

grdynumpy.ndarray

Grid y-coordinates [m].

cfgmoonpies.config.Cfg, optional

cfg.timestartfloat: Start time [yr].
cfg.rad_moonfloat: Lunar radius [m].

Returns

age_gridnumpy.ndarray: Gridded ages of last impact [yr] (Ny, Nx).

moonpies.moonpies.make_strat_col(time, ice, ejecta, ej_srcs, age, cfg=CFG)[source]¶

Return stratigraphy column of ice and ejecta.

Parameters

time (array): Time [yr]
ice (array): Ice thickness [m]
ejecta (array): Ejecta thickness [m]
ej_srcs (array): Labels for ejecta layer sources
age (num): Age at base of strat col [yr]

Returns

ej_col (DataFrame): Ejecta columns vs. time
ice_col (array): Ice columns vs. time
strat_cols (dict of DataFrame)

moonpies.moonpies.merge_adjacent_strata(strat, agg=None)[source]¶: Return strat_col with adjacent rows with same label merged.

moonpies.moonpies.format_csv_outputs(strat_cols, time_arr, df, cfg=CFG)[source]¶

Return all formatted model outputs and write to outpath, if specified.

Returns

ejecta: pandas.DataFrame: Ejecta thickness [m] (rows: time, cols: cold traps)
ice: pandas.DataFrame: Ice thickness [m] (rows: time, cols: cold traps)
strat_dict: dict of str:pandas.DataFrame: Dict of stratigraphy column DataFrames; keys: coldtrap names, values: dataframe (rows: layers, cols: ice, ejecta, source, time, depth, ice%)

moonpies.moonpies.get_all_labels(label_array)[source]¶: Return all unique labels from label_array.

moonpies.moonpies.format_save_outputs(strat_cols, time_arr, df, cfg=CFG)[source]¶: Format dataframes and save outputs based on write / write_npy in cfg.

moonpies.moonpies.save_outputs(outputs, fnames)[source]¶: Save outputs to files in fnames in directory outpath.

moonpies.moonpies.get_grid_arrays(cfg=CFG)[source]¶

Return sparse meshgrid (grdy, grdx) from sizes [m], steps [m] and dtype.

Grid is centered on South pole with y in (ysize, -ysize) and c in (-xsize, xsize) therefore total gridsize is (2*xsize)*(2*ysize).

moonpies.moonpies.latlon2xy(lat, lon, rp=1737.4e3)[source]¶

Return (x, y) [m] South Polar stereo coords from (lat, lon) [deg].

Parameters

lat (num or arr): Latitude(s) [deg]
lon (num or arr): Longitude(s) [deg]
rp (num): Radius of the planet or moon [m]

Returns

x (num or arr): South Pole stereo x coordinate(s) [m]
y (num or arr): South Pole stereo y coordinate(s) [m]

moonpies.moonpies.xy2latlon(x, y, rp=1737.4e3)[source]¶

Return (lat, lon) [deg] from South Polar stereo coords (x, y) [m].

Parameters

x (num or arr): South Pole stereo x coordinate(s) [m]
y (num or arr): South Pole stereo y coordinate(s) [m]
rp (num): Radius of the planet or moon [m]

Returns

lat (num or arr): Latitude(s) [deg]
lon (num or arr): Longitude(s) [deg]

moonpies.moonpies.gc_dist(lon1, lat1, lon2, lat2, rp=1737.4e3)[source]¶

Return great circle distance [m] from (lon1, lat1) - (lon2, lat2) [deg].

Uses the Haversine formula adapted from C. Veness https://www.movable-type.co.uk/scripts/latlong.html

Parameters

lon1 (num or arr): Longitude [deg] of start point
lat1 (num or arr): Latitude [deg] of start point
lon2 (num or arr): Longitude [deg] of end point
lat2 (num or arr): Latitude [deg] of end point
rp (num): Radius of the planet or moon [m]

Returns

gc_dist (num or arr): Great circle distance(s) in meters [m]

moonpies.moonpies.probabilistic_round(x, rng=None)[source]¶

Randomly round float x up or down weighted by its distance to x + 1.

E.g. 6.1 will round down ~90% of the time and round up ~10% of the time such that over many trials the expected value is 6.1.

Modified from C. Locke https://stackoverflow.com/a/40921597/8742181

Parameters

x (float): Any float (works on positive and negative values).

Returns

x_rounded (int): Either floor(x) or ceil(x), rounded probabalistically

moonpies.moonpies.round_to_ts(values, timestep)[source]¶: Return values rounded to nearest timestep.

moonpies.moonpies.rtol(num, tol=CFG.rtol)[source]¶: Return relative tolerance where value is equal to num at tol.

moonpies.moonpies.minmax_rtol(arr, tol=CFG.rtol)[source]¶: Return min and max of arr -/+ relative tolerance tol.

moonpies.moonpies.diam2vol(diameter)[source]¶: Return volume of sphere [m^3] given diameter [m].

moonpies.moonpies.m2km(x)[source]¶: Convert meters to kilometers.

moonpies.moonpies.km2m(x)[source]¶: Convert kilometers to meters.

moonpies.moonpies.vprint(cfg, *args, **kwargs)[source]¶: Print if verbose.

moonpies.moonpies.clear_cache()[source]¶: Reset lru_cache.

class moonpies.moonpies.rv_mixture(submodels, *args, weights=None, **kwargs)[source]¶

Return mixture of scipy.stats.rv_continuous models.

Attributes

random_state: Get or set the generator object for generating random variates.

Methods

`__call__`(args, *kwds)	Freeze the distribution for the given arguments.
`cdf`(x, args, *kwds)	Cumulative distribution function of the given RV.
`entropy`(args, *kwds)	Differential entropy of the RV.
`expect`([func, args, loc, scale, lb, ub, ...])	Calculate expected value of a function with respect to the distribution by numerical integration.
`fit`(data, args, *kwds)	Return estimates of shape (if applicable), location, and scale parameters from data.
`fit_loc_scale`(data, *args)	Estimate loc and scale parameters from data using 1st and 2nd moments.
`freeze`(args, *kwds)	Freeze the distribution for the given arguments.
`interval`([confidence])	Confidence interval with equal areas around the median.
`isf`(q, args, *kwds)	Inverse survival function (inverse of sf) at q of the given RV.
`logcdf`(x, args, *kwds)	Log of the cumulative distribution function at x of the given RV.
`logpdf`(x, args, *kwds)	Log of the probability density function at x of the given RV.
`logsf`(x, args, *kwds)	Log of the survival function of the given RV.
`mean`(args, *kwds)	Mean of the distribution.
`median`(args, *kwds)	Median of the distribution.
`moment`([order])	non-central moment of distribution of specified order.
`nnlf`(theta, x)	Negative loglikelihood function.
`pdf`(x, args, *kwds)	Probability density function at x of the given RV.
`ppf`(q, args, *kwds)	Percent point function (inverse of cdf) at q of the given RV.
`rvs`(args, *kwds)	Random variates of given type.
`sf`(x, args, *kwds)	Survival function (1 - cdf) at x of the given RV.
`stats`(args, *kwds)	Some statistics of the given RV.
`std`(args, *kwds)	Standard deviation of the distribution.
`support`(args, *kwargs)	Support of the distribution.
`var`(args, *kwds)	Variance of the distribution.

MoonPIES Config¶

Configuration for MoonPIES model

Sets all configurable attributes, paths and model options for a MoonPIES run. See documentation for guide to defining custom config parameters.

class moonpies.config.Cfg(run_name: str = 'moonpies', version: str = '1.1.0', seed: int = 0, run_date: str = '', run_time: str = '', verbose: bool = False, write: bool = True, write_npy: bool = False, strat_after_age: bool = True, plot: bool = False, mode: str = 'moonpies', pole: str = 's', solar_wind_ice: typing.Optional[bool] = None, ballistic_hop_moores: typing.Optional[bool] = None, ejecta_basins: typing.Optional[bool] = None, impact_ice_basins: typing.Optional[bool] = None, impact_ice_comets: typing.Optional[bool] = None, use_volc_dep_effcy: typing.Optional[bool] = None, ballistic_sed: typing.Optional[bool] = None, impact_gardening_costello: typing.Optional[bool] = None, ballistic_hop_effcy: typing.Optional[float] = None, volc_dep_effcy: typing.Optional[float] = None, coldtrap_area_H2O: typing.Optional[float] = None, coldtrap_area_CO2: typing.Optional[float] = None, coldtrap_names: typing.Optional[tuple] = None, data_path: str = '', out_path: str = '', figs_path: str = '', crater_csv_in: str = 'crater_list.csv', basin_csv_in: str = 'basin_list.csv', nk_csv_in: str = 'needham_kring_2017_s3.csv', bahcall_csv_in: str = 'bahcall_etal_2001_t2.csv', bhop_csv_in: str = 'ballistic_hop_coldtraps.csv', bsed_frac_mean_in: str = 'ballistic_sed_frac_melted_mean.csv', bsed_frac_std_in: str = 'ballistic_sed_frac_melted_std.csv', mplstyle_in: str = '.moonpies.mplstyle', ej_t_csv_out: str = 'ej_columns.csv', ice_t_csv_out: str = 'ice_columns.csv', config_py_out: str = 'config_moonpies_v1.1.0.py', agegrd_npy_out: str = 'age_grid.npy', ejmatrix_npy_out: str = 'ejecta_matrix.npy', grdxsize: int = 400000.0, grdysize: int = 400000.0, grdstep: int = 1000.0, timestart: int = 4250000000.0, timeend: int = 0, timestep: int = 10000000.0, rad_moon: float = 1737400.0, grav_moon: float = 1.62, sa_moon: float = 37932328099380.46, simple2complex: float = 18000.0, complex2peakring: float = 140000.0, impactor_density: float = 1300, impact_speed_mean: float = 20000.0, impact_speed_sd: float = 6000.0, escape_vel: float = 2380.0, impact_angle: float = 45, target_density: float = 1500, bulk_density: float = 2700, ice_erosion_rate: float = 0.1, ej_threshold: float = 4, basin_ej_threshold: float = 5, ej_thickness_exp: float = -3, thickness_min: float = 0.001, neukum_pf_new: bool = True, neukum_pf_a_2001: tuple = (-3.0876, -3.557528, 0.781027, 1.021521, -0.156012, -0.444058, 0.019977, 0.08685, -0.005874, -0.006809, 0.000825, 5.54e-05), neukum_pf_a_1983: tuple = (-3.0768, -3.6269, 0.4366, 0.7935, 0.0865, -0.2649, -0.0664, 0.0379, 0.0106, -0.0022, -0.000518, 3.97e-05), ice_density: float = 934, ice_melt_temp: float = 273, ice_latent_heat: float = 334000.0, crater_cols: tuple = ('cname', 'lat', 'lon', 'psr_lat', 'psr_lon', 'diam', 'age', 'age_low', 'age_upp', 'psr_area', 'age_ref', 'prio', 'notes'), basin_cols: tuple = ('cname', 'lat', 'lon', 'diam', 'inner_ring_diam', 'bouger_diam', 'age', 'age_low', 'age_upp', 'ref'), ballistic_teq: bool = False, ballistic_sed_frac_lost: float = 1, mixing_ratio_petro: bool = True, mixing_ratio_a: float = 0.0183, mixing_ratio_b: float = 0.87, ice_frac: float = 0.056, ke_heat_frac: float = 0.45, ke_heat_frac_speed: float = 1450.0, polar_ejecta_temp_init: float = 140, basin_ejecta_temp_warm: bool = False, basin_ejecta_temp_init_cold: float = 260, basin_ejecta_temp_init_warm: float = 420, ejecta_temp_dist_params_cold: tuple = (2032000.0, -7658.0, 252.0), ejecta_temp_dist_params_warm: tuple = (2449000.0, -23840.0, 476.2), specific_heat_coeffs: tuple = (-3.6125, 2.7431, 0.0023616, -1.234e-05, 8.9093e-09), kepler_regime: tuple = (18000.0, 60000.0), kepler_diam: float = 31000.0, kepler_a: float = 5.1, kepler_b: float = -0.33, copernicus_regime: tuple = (60000.0, 300000.0), copernicus_diam: float = 93000.0, copernicus_a: float = 120.0, copernicus_b: float = -0.68, orientale_regime: tuple = (300000.0, 2500000.0), orientale_diam: float = 660000.0, orientale_a: float = 18000.0, orientale_b: float = -0.95, mm_mass_rate: float = 1000000.0, ctype_frac: float = 0.36, ctype_hydrated: float = 0.6666666666666666, hydrated_wt_pct: float = 0.1, impact_mass_retained: float = 0.165, brown_c0: float = 1.568, brown_d0: float = 2.7, earth_moon_ratio: float = 22.5, impact_regimes: dict = <factory>, is_comet: bool = False, comet_ast_frac: float = 0.05, comet_density: float = 600, comet_hydrated_wt_pct: float = 0.2, comet_mass_retained: float = 0.065, comet_speed_min: float = 10200.0, comet_speed_max: float = 72000.0, jfc_speed_mean: float = 20000.0, jfc_speed_sd: float = 5000.0, jfc_frac: float = 0.875, lpc_speed_mean: float = 54000.0, lpc_speed_sd: float = 5000.0, lpc_frac: float = 0.125, volc_mode: str = 'Head', volc_early: tuple = (4000000000.0, 3000000000.0), volc_late: tuple = (3000000000.0, 2000000000.0), volc_early_pct: float = 0.75, volc_late_pct: float = 0.25, volc_total_vol: float = 10000000.0, volc_ice_ppm: float = 10, volc_magma_density: float = 3000, nk_species: str = 'min_h2o', nk_cols: tuple = ('time', 'tot_vol', 'sphere_mass', 'min_co', 'max_co', 'min_h2o', 'max_h2o', 'min_h', 'max_h', 'min_s', 'max_s', 'min_sum', 'max_sum', 'min_psurf', 'max_psurf', 'min_atm_loss', 'max_atm_loss'), solar_wind_mode: str = 'Benna', faint_young_sun: bool = True, overturn_depth_present: float = 0.09, overturn_ancient_slope: float = 1e-09, overturn_ancient_t0: float = 3000000000.0)[source]¶

Class to configure a mixing model run.

Attributes

ballistic_hop_effcy
ballistic_hop_moores
ballistic_sed
coldtrap_area_CO2
coldtrap_area_H2O
coldtrap_names
ejecta_basins
impact_gardening_costello
impact_ice_basins
impact_ice_comets
solar_wind_ice
use_volc_dep_effcy
volc_dep_effcy

Methods

`dtype`	alias of `numpy.float32`
`to_dict`()	Return dict representation of dataclass.
`to_py`(out_path)	Write cfg to python file at out_path.
`to_string`()	Return representation of self as dict formatted python string.

dtype¶: alias of numpy.float32

to_dict()[source]¶: Return dict representation of dataclass.

to_string()[source]¶: Return representation of self as dict formatted python string.

to_py(out_path)[source]¶: Write cfg to python file at out_path.

moonpies.config.read_custom_cfg(cfg_path=None, seed=None)[source]¶: Return Cfg from custom config file at cfg_path. Overwrite seed if given.

moonpies.config.from_dict(cdict)[source]¶: Return Cfg setting all provided values in cdict.

moonpies.config.make_default_cfg(out_path='')[source]¶: Write default cfg file to out_path.

MoonPIES Plotting¶

moonpies.plotting.reset_plot_style(mplstyle=True, cfg=CFG)[source]¶: Reset matplotlib style defaults, use MoonPIES mplstyle if True.

moonpies.plotting.plot_version(cfg=CFG, loc='ll', xy=None, xyoff=None, ax=None, bbkw=None, **kwargs)[source]¶: Add MoonPIES version label with ax.annotate().

moonpies.plotting.plot_stratigraphy(out_path, coldtraps=None, runs=None, seeds=None, min_thick=1, fsave='', cmap=None, version=True, fsave_icepct='', strat_kws={}, kwargs={})[source]¶: Plot stratigraphy.

moonpies.plotting.plot_strat(strat, title='', colorbar=True, cmap=None, label_layers='', ylabel_right=False, legend=True, ax=None)[source]¶: Plot a single stratigraphy column.

moonpies.plotting.strat_legend(handles=None, labels=None, cmap=None, ncol=1, ax=None)[source]¶: Make a legend for strat layers.

moonpies.plotting.get_lith_key(liths, hatches=HATCHES)[source]¶: Return dict of dict of lithology to label, hatch style and ice_pct

moonpies.plotting.clean_up_strat_col(strat, min_thick=0)[source]¶: Clean up strat_col by removing thin layers

moonpies.plotting.get_strat_col_ranges(strat_col, cdf=CDF, savefile=None)[source]¶: Return strat_col ranges for strat_col plot

moonpies.plotting.get_cmap(cmap=None)[source]¶: Return matplotlib colormap or custom cmap from list of hex colors.

moonpies.plotting.make_cmap(hex_list, locs=None)[source]¶

Returns color map from hex_list, interpolating linearly if locs=None.

If locs is provided, map each color to its location in locs.

Modified from Kerry Halupka: github.com/KerryHalupka/custom_colormap/blob/master/generate_colormap.py

Parameters

hex_list (list): Hex code strings
locs (list): Locations in [0, 1]. Must start with 0 and end with 1.

Returns

cmap (matplotlib.colors.LinearSegmentedColormap): Color map

MoonPIES Thermal Eq¶

Thermal equillibrium model to compute ballistic sedimentation melting fraction.

Authors

1. Luchsinger, C. J. Tai Udovicic

moonpies.thermal_eq.make_melt_frac_dfs(mrs, ej_temps, nseed=10, parallel=True, savepath='')[source]¶

Return mean, stdev DataFrame of melt fractions at each mr and ej_temp.

Runs nseed times for each mr, ejecta_t combination, randomizing initial positions of ejecta pixels. If savepath is given, save as csvs.

Parameters

mrs (array): Array of mixing ratios [target]
ej_temps (array): Array of ejecta temperatures
nseed (int): Number of seeds to run for each mr, ejecta_t combination
parallel (bool): Whether to run in parallel
savepath (str): Path to save csv files

moonpies.thermal_eq.get_melt_frac_arr(mrs, ejecta_temps, seeds, ncpus=1)[source]¶: Return melt fraction array for each mr and ejecta_temp.

moonpies.thermal_eq.melt_frac_teq_1d(mr, ejecta_t0, target_t0=45, melt_t=110, n=1000, eq_thresh=1, max_iter=10 ** 5, conv_warning=True, rng=None)[source]¶

Return fraction heated above melt_t from 1D thermal conduction model.

Model initialized as array of length n with target_t0 at all indices. A fraction of random ejecta elements (1-mr) are assigned ejecta_t0. Each element is assumed to be 100 microns wide and time step is 1 msec. Complete melting is assumed to occur at melt_t with no heat loss.

The model is stepped through time until one of these conditions is met: - Thermal equilibrium: All elements are within eq_thresh of their neighbors - All melted: All elements are above melt_t - Melting finished: All elements are below melt_t - Timeout: The model reaches max_iter without triggering any of the above

Parameters

ejecta_t0 (num): Initial temperature of the ejecta (pre-impact) [K]
target_t0 (num): Initial temperature of the target material [K]
mr (num): Mixing ratio of target materialejecta material
melt_t (num): Temperature at which elements are considered melted [K]
n (num): Length of 1D model [100 micron pixels]
eq_thresh (num): Threshold temperature for thermal equilibrium [K]
max_iter (num): Max number of iterations to run (100000 approx. 15 sec)
conv_warning (bool): Whether to warn if the model does not converge
rng (int or np.RandomState): Random number generator or seed

Returns

melt_fraction (float): Fraction of target material heated above melt_t

moonpies.thermal_eq.heat1d_finite_diff(T, density=1800, dt=0.001, dx=1e-5)[source]¶

Return updated T from finite difference 1D heat flow conduction model.

See Eq. 2, Onorato et al. (1978).

Parameters

T (num or array): temperature [K]
density (num): density, [kg/m^3]
k (num): conductivity [W/m/K]
Cp (num): heat capacity [J/kg/K]
T_liq_c (num): liquidus of clasts [K]
T_sol_c (num): solidus of clasts [K]
dt (num): time step size [s], must match dx
dx (num): spatial step size [m], must match dt

Returns

alpha (num): scaling factor [unitless]

moonpies.thermal_eq.thermal_diffusivity(conductivity, cp, density=1800)[source]¶: Return thermal diffusivity.

moonpies.thermal_eq.thermal_conductivity(T, Kc=3.4e-3, chi=2.7)[source]¶: Return thermal conductivity of regolith (eqn A4 Hayne 2017).

moonpies.thermal_eq.sphc(T, c0=- 3.6125, c1=2.7431, c2=2.3616e-3, c3=- 1.234e-5, c4=8.9093e-9)[source]¶: Return specific heat capacity [J/kg/K] of regolith.

moonpies.thermal_eq.rand_positions(ej_n, n=100, rng=None)[source]¶

Return ej_n random initial positions in target of length n.

Parameters

ej_n (int): Number of ejecta pixels to assign
n (int): Length of 1D target [pixels]
rng (int or np.RandomState): Random number generator or seed

Returns

inds (array): Indices of initial positions of ejecta