terraingenpy 0.1.1.dev73__tar.gz → 0.1.1.dev77__tar.gz

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/CHANGELOG.md

@@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Defaults give a plausible lunar terrain at 1 m per pixel in which every height layer shows: craters from a production surface capped below the Trask equilibrium with steady-state ages, diffusion and irregular outlines; Surveyor boulders; noise relief scaled to its wavelength; and visible roughness, bedforms and dunes.
+- Boulder layers default to the nominal NASA SP-8023 intercrater sizes rather than Golombek-Rapp; a `coverage`, `qa`, `qb` or `ejecta.coverage` that no Golombek-Rapp sizes use is now an error that names `"sizes": {"type": "golombek_rapp"}`.
 - Boulder lists and models hold every boulder of the layer's diameter range; only the heightmap leaves out boulders too small to resolve.
 - Boulder ejecta come from every crater layer before the boulder layer, not only the last one.
 - The boulder layer's `exposure_spacing` key is now `ground_spacing` (Python `ground_spacing`), the spacing of every ground read the layer makes.

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/CMakeLists.txt

@@ -8,7 +8,7 @@ endif()
 
 # The release being worked towards, such as 0.1.0, or for a development build a PEP 440 pre-release of
 # it, such as 0.1.0.dev42, which only the Python package carries.
-set(TERRAINGEN_FULL_VERSION "0.1.1.dev73")
+set(TERRAINGEN_FULL_VERSION "0.1.1.dev77")
 string(REGEX MATCH "^[0-9]+\\.[0-9]+\\.[0-9]+" TERRAINGEN_VERSION "${TERRAINGEN_FULL_VERSION}")
 
 project(

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: terraingenpy
-Version: 0.1.1.dev73
+Version: 0.1.1.dev77
 Summary: Scientific terrain generation for planetary surfaces
 Keywords: terrain,moon,mars,craters,planetary science,simulation
 Author: Alex Maietta

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/README.md

@@ -57,7 +57,7 @@ Options:
 | terrain | `example_terrain_billow`, `_cellular`, `_domain_warp`, `_fbm`, `_layered`, `_ridged`, `_roughness`, `_voronoi` | `example_terrain_fbm`, `_layered` | `example_terrain_fbm`, `_fractal_types`, `_hurst_sweep`, `_layered`, `_noise_kernels` |
 | craters | `example_craters_datum`, `_degradation_diffusion`, `_degradation_none`, `_interior_replacement`, `_irregular`, `_manual`, `_max_craters`, `_profile_complex`, `_profile_martin_parkes_dunstan`, `_rim_smoothing_soft`, `_secondaries`, `_secondary_rays`, `_simple`, `_smoothed_rims`, `_spacing` | `example_craters_degradation`, `_manual`, `_profiles`, `_secondaries`, `_simple` | `example_craters_age_sweep`, `_apply_options`, `_degradation`, `_irregularity`, `_manual`, `_positioning`, `_profiles`, `_rim_smoothing`, `_secondaries`, `_simple` |
 | distributions | `example_distributions_moore_rough_mare`, `_piecewise_power_law`, `_power_law`, `_tabulated`, `_trask_equilibrium`, `_viper` | `example_distributions_csfd` | `example_distributions_csfd`, `_custom` |
-| ages | `example_ages_fresh`, `_steady_state`, `_uniform` | `example_ages_models` | `example_ages_models` |
+| ages | `example_ages_fresh`, `_freshness`, `_steady_state`, `_uniform` | `example_ages_models` | `example_ages_models` |
 | boulders | `example_boulders_buried`, `_ejecta`, `_fragments`, `_exposure`, `_layer`, `_models`, `_patches`, `_scene`, `_shapes`, `_sp8023` | `example_boulders_ejecta`, `_layer`, `_shapes` | `example_boulders_exposure`, `_layer`, `_positioning`, `_shapes`, `_size_models` |
 | albedo | `example_albedo_blast_zone`, `_crater_rays`, `_fresh_crater`, `_moon_site`, `_new_crater`, `_oblique_rays`, `_rgb`, `_synthetic` | `example_albedo_crater_rays` | `example_albedo_crater_rays`, `_moon_site`, `_options` |
 | layers | `example_layers_regions`, `_roughness`, `_scale_and_clamp` | `example_layers_custom`, `_regions` | `example_layers_custom`, `_regions` |

terraingenpy-0.1.1.dev77/examples/config/ages/example_ages_freshness.json

@@ -0,0 +1,71 @@
+{
+    "schema_version": 1,
+    "layers": [
+        {
+            "type": "noise",
+            "stack": [
+                {
+                    "seed": 1,
+                    "wavelength": 800,
+                    "amplitude": 40,
+                    "octaves": 8
+                }
+            ]
+        },
+        {
+            "type": "craters",
+            "seed": 1,
+            "density": {
+                "type": "minimum",
+                "distributions": [
+                    {
+                        "type": "production_surface",
+                        "production": "extended_neukum",
+                        "chronology": "neukum",
+                        "age_gyr": 3.5
+                    },
+                    {
+                        "type": "trask"
+                    }
+                ]
+            },
+            "min_diameter": 8,
+            "max_diameter": 300,
+            "ages": {
+                "type": "freshness",
+                "lifetime_gyr": 3.5,
+                "freshness": {
+                    "kind": "normal",
+                    "a": 0.35,
+                    "b": 0.15,
+                    "min": 0,
+                    "max": 1
+                }
+            },
+            "degradation": {
+                "type": "freshness",
+                "cutoff_depth_ratio": 0.04
+            }
+        }
+    ],
+    "outputs": [
+        {
+            "type": "heightmap",
+            "path": "example_ages_freshness.tif",
+            "region": {
+                "width": 513,
+                "height": 513,
+                "pixel_size": 2
+            }
+        },
+        {
+            "type": "crater_list",
+            "path": "example_ages_freshness.csv",
+            "region": {
+                "width": 513,
+                "height": 513,
+                "pixel_size": 2
+            }
+        }
+    ]
+}

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/albedo/example_albedo_rocks_and_slopes.json

@@ -28,6 +28,9 @@
             "type": "boulders",
             "seed": 5,
             "coverage": 0.01,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.05,
             "max_diameter": 1.5,
             "ejecta": {

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/boulders/example_boulders_buried.json

@@ -20,6 +20,9 @@
             "type": "boulders",
             "seed": 3,
             "coverage": 0.03,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.15,
             "max_diameter": 1.5,
             "ejecta": {

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/boulders/example_boulders_ejecta.json

@@ -28,6 +28,9 @@
             "type": "boulders",
             "seed": 1,
             "coverage": 0.01,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.2,
             "max_diameter": 3,
             "ejecta": {

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/boulders/example_boulders_exposure.json

@@ -16,6 +16,9 @@
             "type": "boulders",
             "seed": 1,
             "coverage": 0.02,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.3,
             "max_diameter": 4,
             "exposure": {

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/boulders/example_boulders_fragments.json

@@ -9,6 +9,9 @@
             "type": "boulders",
             "seed": 4,
             "coverage": 0.06,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.1,
             "max_diameter": 2.5,
             "clusters": {

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/boulders/example_boulders_layer.json

@@ -43,6 +43,9 @@
             "type": "boulders",
             "seed": 1,
             "coverage": 0.05,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.2,
             "max_diameter": 3
         }

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/boulders/example_boulders_max_slope.json

@@ -16,6 +16,9 @@
             "type": "boulders",
             "seed": 1,
             "coverage": 0.06,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.2,
             "max_diameter": 3,
             "max_slope": 0.35

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/boulders/example_boulders_models.json

@@ -16,6 +16,9 @@
             "type": "boulders",
             "seed": 1,
             "coverage": 0.05,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.2,
             "max_diameter": 3,
             "models": {

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/boulders/example_boulders_patches.json

@@ -16,6 +16,9 @@
             "type": "boulders",
             "seed": 1,
             "coverage": 0.06,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.2,
             "max_diameter": 3,
             "patches": {

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/boulders/example_boulders_rolling.json

@@ -16,6 +16,9 @@
             "type": "boulders",
             "seed": 1,
             "coverage": 0.06,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.2,
             "max_diameter": 3,
             "max_slope": 0.35,

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/boulders/example_boulders_scene.json

@@ -16,6 +16,9 @@
             "type": "boulders",
             "seed": 1,
             "coverage": 0.05,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.2,
             "max_diameter": 3,
             "models": {

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/boulders/example_boulders_shapes.json

@@ -16,6 +16,9 @@
             "type": "boulders",
             "seed": 1,
             "coverage": 0.05,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.2,
             "max_diameter": 3,
             "min_height_ratio": 0.6,

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/planets/example_planets_mars_exposure.json

@@ -28,6 +28,9 @@
             "type": "boulders",
             "seed": 3,
             "coverage": 0.02,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.3,
             "max_diameter": 3,
             "exposure": {

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/planets/example_planets_mars_sand_shadows.json

@@ -16,6 +16,9 @@
             "type": "boulders",
             "seed": 3,
             "coverage": 0.08,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.2,
             "max_diameter": 2
         },

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/examples/config/planets/example_planets_mars_ventifacts.json

@@ -16,6 +16,9 @@
             "type": "boulders",
             "seed": 4,
             "coverage": 0.08,
+            "sizes": {
+                "type": "golombek_rapp"
+            },
             "min_diameter": 0.1,
             "max_diameter": 1.5,
             "relief": "shape",

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/terraingen/config/build.cpp

@@ -20,6 +20,7 @@
 #include "terraingen/distribution/spliced.h"
 #include "terraingen/distribution/tabulated.h"
 #include "terraingen/layers/craters/ages/age_model.h"
+#include "terraingen/layers/craters/ages/freshness.h"
 #include "terraingen/layers/craters/ages/steady_state.h"
 #include "terraingen/layers/craters/degradation/degradation_model.h"
 #include "terraingen/layers/craters/degradation/diffusivities.h"
@@ -156,6 +157,9 @@ std::shared_ptr<const CraterAgeModel> BuildAges(const AgesSpec& spec) {
                                                          BuildEquilibrium(s.equilibrium), s.ageGyr,
                                                          BuildChronology(s.chronology));
             },
+            [](const FreshnessAgesSpec& s) -> Result {
+                return std::make_shared<FreshnessAges>(s.freshness, s.lifetimeGyr);
+            },
         },
         spec);
 }

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/terraingen/config/config.h

@@ -33,6 +33,7 @@
 #include "terraingen/layers/strata.h"
 #include "terraingen/noise/noise_layers.h"
 #include "terraingen/pipeline/materials.h"
+#include "terraingen/random/value_distribution.h"
 #include "terraingen/raster/geotiff/geotiff.h"
 #include "terraingen/raster/resample.h"
 #include "terraingen/sources/geotiff_source.h"
@@ -285,8 +286,15 @@ struct SteadyStateAgesSpec {
     ChronologyModel chronology = ChronologyModel::Neukum;
     bool operator==(const SteadyStateAgesSpec&) const = default;
 };
+/// Crater ages "freshness": `FreshnessAges(freshness, lifetimeGyr)`.
+struct FreshnessAgesSpec {
+    double lifetimeGyr = 1.0;
+    ValueDistribution freshness{ValueDistribution::Kind::Uniform, 0.0, 1.0, 0.0, 1.0};
+    bool operator==(const FreshnessAgesSpec&) const = default;
+};
 /// A crater age model, named in JSON by its "type".
-using AgesSpec = std::variant<UniformAgesSpec, FreshAgesSpec, SteadyStateAgesSpec>;
+using AgesSpec =
+    std::variant<UniformAgesSpec, FreshAgesSpec, SteadyStateAgesSpec, FreshnessAgesSpec>;
 
 /// Degradation "none": `NoDegradation`, optionally with a fixed depth-to-diameter ratio.
 struct NoDegradationSpec {

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/terraingen/config/fields/boulders.h

@@ -110,7 +110,8 @@ template <typename IO> void Fields(IO& io, BoulderEjecta& ejecta) {
        "", AboveUpTo(0.0, 1.0));
     io("coverage", ejecta.coverage,
        "Golombek-Rapp k, the fraction of ground covered by blocks at the rim of a fresh crater, "
-       "between 0 and 1; used with golombek_rapp ejecta sizes.",
+       "between 0 and 1. Only golombek_rapp ejecta sizes use it, so any other value than the "
+       "default needs them.",
        "", Inside(0.0, 1.0));
     io("profile", ejecta.profile,
        "How the share of a crater's blocks falls off with distance from its centre.");
@@ -323,15 +324,19 @@ template <> struct SpecName<BoulderLayerSpec> {
 /// The fields of the Golombek-Rapp terms and diameter range of a boulder layer's boulders.
 template <typename IO> void BoulderSizeRangeFields(IO& io, BoulderSizes& sizes) {
     io("coverage", sizes.coverage,
-       "Golombek-Rapp k, the fraction of the ground covered by boulders, between 0 and 1; used "
-       "with golombek_rapp sizes, where higher values give more boulders.",
+       "Golombek-Rapp k, the fraction of the ground covered by boulders, between 0 and 1; higher "
+       "values give more boulders. Only golombek_rapp sizes use it, so any other value than the "
+       "default needs them.",
        "", Inside(0.0, 1.0));
     io("qa", sizes.qConstant,
        "Constant term of the Golombek-Rapp q = qa + qb / k, per metre; a larger q leaves fewer "
-       "large boulders. Also used for golombek_rapp ejecta.",
+       "large boulders. Only golombek_rapp sizes or ejecta sizes use it, so any other value than "
+       "the default needs them.",
        "1/m");
     io("qb", sizes.qCoverageCoefficient,
-       "Term of the Golombek-Rapp q = qa + qb / k divided by the coverage k, per metre.", "1/m");
+       "Term of the Golombek-Rapp q = qa + qb / k divided by the coverage k, per metre; used as "
+       "qa is.",
+       "1/m");
     io("min_diameter", sizes.minDiameter,
        "Smallest boulder generated, in metres; lower values add many more small boulders.", "m",
        Above(0.0));

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/terraingen/config/fields/crater_models.h

@@ -192,6 +192,23 @@ template <typename IO> void Fields(IO& io, SteadyStateAgesSpec& spec) {
        "Chronology whose formation rate the craters' ages are drawn from.");
 }
 
+template <> struct SpecName<FreshnessAgesSpec> {
+    static constexpr std::string_view kName = "freshness";
+    static constexpr std::string_view kDescription =
+        "Ages from a freshness f between 0 and 1 drawn per crater, age = (1 - f) lifetime, with "
+        "one lifetime for every diameter; freshness stands for age as in degree-of-freshness "
+        "dating (Pohn and Offield 1970; Trang et al. 2015).";
+};
+template <typename IO> void Fields(IO& io, FreshnessAgesSpec& spec) {
+    io("lifetime_gyr", spec.lifetimeGyr,
+       "Lifetime in Gyr, positive, of every crater: freshness 0 is this old, 1 is new; crater "
+       "albedo such as ray fading reads these ages.",
+       "Gyr", Above(0.0));
+    io("freshness", spec.freshness,
+       "Distribution each crater's freshness is drawn from, also clamped to 0 to 1: 1 is fresh, "
+       "0 at the end of its lifetime; with freshness degradation, depth and rim scale with it.");
+}
+
 template <> struct SpecName<FreshnessDegradationSpec> {
     static constexpr std::string_view kName = "freshness";
     static constexpr std::string_view kDescription =

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/terraingen/config/fields/craters.h

@@ -72,6 +72,13 @@ template <typename IO> void Fields(IO& io, ValueDistribution& distribution) {
     OptionalBound(io, "max", distribution.max,
                   "Upper bound drawn values are clamped to; unset leaves them unbounded above, "
                   "which normal and log-normal kinds do not allow.");
+    io("edges", distribution.edges,
+       "With piecewise, the edges of the bins, at least two and strictly increasing; values are "
+       "uniform within each bin. Empty for every other kind.");
+    io("weights", distribution.weights,
+       "With piecewise, the relative weight of each bin, one fewer than the edges, not negative "
+       "and not all zero; each bin draws its share of the total. Empty for every other kind.",
+       "", AtLeast(0.0));
 }
 
 /// The fields of irregular craters' rough, wavy rims.

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/terraingen/config/fields/enums.h

@@ -224,12 +224,14 @@ template <> struct EnumNames<BaseSolid> {
 };
 
 template <> struct EnumNames<ValueDistribution::Kind> {
-    static constexpr std::array<EnumEntry<ValueDistribution::Kind>, 4> kValues{{
+    static constexpr std::array<EnumEntry<ValueDistribution::Kind>, 5> kValues{{
         {"constant", ValueDistribution::Kind::Constant, "Always a."},
         {"uniform", ValueDistribution::Kind::Uniform, "Uniform between a and b."},
         {"normal", ValueDistribution::Kind::Normal, "Normal with mean a and standard deviation b."},
         {"log_normal", ValueDistribution::Kind::LogNormal,
          "Log-normal with median a and standard deviation b of the natural logarithm."},
+        {"piecewise", ValueDistribution::Kind::Piecewise,
+         "Uniform within each bin between edges, each bin drawn in proportion to its weight."},
     }};
 };
 

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/terraingen/config/validate.cpp

@@ -211,7 +211,36 @@ void CheckBoulderMaps(const BoulderLayerOptions& boulders, const std::string& pa
     }
 }
 
+bool IsGolombekRapp(const BoulderSizesSpec& sizes) {
+    return std::holds_alternative<GolombekRappBouldersSpec>(sizes);
+}
+
+/// @throws ConfigError at a Golombek-Rapp term changed from its default, such as "coverage", when
+/// no size model of the layer is Golombek-Rapp and so none would use it.
+void CheckGolombekRappTerms(const BoulderLayerSpec& spec, const std::string& path) {
+    const BoulderLayerSpec defaults{};
+    const BoulderSizes& sizes = spec.boulders.sizes;
+    const BoulderSizes& unset = defaults.boulders.sizes;
+    const bool layer = IsGolombekRapp(spec.sizes);
+    const bool ejecta = IsGolombekRapp(spec.ejectaSizes.value_or(spec.sizes));
+    const auto check = [](bool used, double value, double fallback, const std::string& at,
+                          const char* fix) {
+        if (!used && value != fallback) {
+            throw ConfigError(at, std::string("is only used by Golombek-Rapp sizes; set ") + fix +
+                                      " or leave it out");
+        }
+    };
+    const char* const layerFix = R"("sizes": {"type": "golombek_rapp"})";
+    check(layer, sizes.coverage, unset.coverage, Child(path, "coverage"), layerFix);
+    check(layer || ejecta, sizes.qConstant, unset.qConstant, Child(path, "qa"), layerFix);
+    check(layer || ejecta, sizes.qCoverageCoefficient, unset.qCoverageCoefficient,
+          Child(path, "qb"), layerFix);
+    check(ejecta, spec.boulders.ejecta.coverage, defaults.boulders.ejecta.coverage,
+          Child(Child(path, "ejecta"), "coverage"), R"("ejecta_sizes": {"type": "golombek_rapp"})");
+}
+
 void CheckLayerSpec(const BoulderLayerSpec& spec, const std::string& path, LayerChecks& context) {
+    CheckGolombekRappTerms(spec, path);
     const BoulderLayerOptions boulders = BuildBoulderOptions(spec, path, context.directory);
     CheckBoulderMaps(boulders, path);
     At(path, [&] { ValidateBoulderLayerOptions(boulders); });

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/terraingen/layers/CMakeLists.txt

@@ -36,6 +36,7 @@ terraingen_add_library(
     craters/secondaries.cpp
     craters/secondary_model.cpp
     craters/ages/age_model.cpp
+    craters/ages/freshness.cpp
     craters/ages/steady_state.cpp
     craters/degradation/degradation_model.cpp
     craters/degradation/diffusion.cpp

terraingenpy-0.1.1.dev77/terraingen/layers/craters/ages/freshness.cpp

@@ -0,0 +1,41 @@
+#include "terraingen/layers/craters/ages/freshness.h"
+
+#include "terraingen/util/checks.h"
+
+#include <cmath>
+#include <utility>
+
+namespace terraingen {
+
+namespace {
+
+ValueDistribution ClampedToUnit(ValueDistribution freshness) {
+    freshness.min = std::fmax(freshness.min, 0.0);
+    freshness.max = std::fmin(freshness.max, 1.0);
+    ValidateValueDistribution(freshness);
+    return freshness;
+}
+
+}  // namespace
+
+FreshnessAges::FreshnessAges(ValueDistribution freshness, double lifetimeGyr)
+    : freshness_(ClampedToUnit(std::move(freshness))), lifetimeGyr_(lifetimeGyr) {
+    RequirePositive(lifetimeGyr_, "Lifetime");
+}
+
+double FreshnessAges::SampleFreshness(RandomStream& random) const {
+    const double u1 = random.NextDouble();
+    const double u2 = random.NextDouble();
+    return freshness_.Sample(u1, u2);
+}
+
+double FreshnessAges::LifetimeAt(double /*diameter*/) const {
+    return lifetimeGyr_;
+}
+
+double FreshnessAges::SampleAgeAt(RandomStream& random, double /*diameter*/,
+                                  double lifetimeGyr) const {
+    return (1.0 - SampleFreshness(random)) * lifetimeGyr;
+}
+
+}  // namespace terraingen

terraingenpy-0.1.1.dev77/terraingen/layers/craters/ages/freshness.h

@@ -0,0 +1,37 @@
+/// @file
+/// @brief `FreshnessAges`, crater ages from a distribution of freshness.
+#pragma once
+
+#include "terraingen/layers/craters/ages/age_model.h"
+#include "terraingen/random/value_distribution.h"
+
+namespace terraingen {
+
+/// Ages from a freshness f in [0, 1] drawn per crater: age = (1 - f) * lifetime, with one lifetime
+/// for every diameter, so `RemainingLifetime` gives back f.
+class FreshnessAges final : public CraterAgeModel {
+  public:
+    /// @param freshness The distribution f is drawn from; its clamp is narrowed to [0, 1].
+    /// @param lifetimeGyr The lifetime of every crater, in Gyr.
+    /// @throws std::invalid_argument unless `lifetimeGyr` is positive and finite and `freshness`,
+    /// once clamped to [0, 1], is valid (`ValidateValueDistribution`).
+    FreshnessAges(ValueDistribution freshness, double lifetimeGyr);
+
+    /// The distribution freshness is drawn from, clamped to [0, 1].
+    const ValueDistribution& Freshness() const {
+        return freshness_;
+    }
+
+    /// Draws a freshness in [0, 1] from two draws of `random`.
+    double SampleFreshness(RandomStream& random) const;
+
+  protected:
+    double LifetimeAt(double diameter) const override;
+    double SampleAgeAt(RandomStream& random, double diameter, double lifetimeGyr) const override;
+
+  private:
+    ValueDistribution freshness_;
+    double lifetimeGyr_;
+};
+
+}  // namespace terraingen

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/terraingen/python/src/crater_models.cpp

@@ -4,6 +4,7 @@
 #include "trampolines.h"
 
 #include "terraingen/layers/craters/ages/age_model.h"
+#include "terraingen/layers/craters/ages/freshness.h"
 #include "terraingen/layers/craters/ages/steady_state.h"
 #include "terraingen/layers/craters/crater_layer.h"
 #include "terraingen/layers/craters/degradation/degradation_model.h"
@@ -15,6 +16,7 @@
 #include "terraingen/layers/craters/profiles/martin_parkes_dunstan.h"
 #include "terraingen/layers/craters/shaping/morphometry.h"
 #include "terraingen/random/stream.h"
+#include "terraingen/random/value_distribution.h"
 
 #include <functional>
 #include <memory>
@@ -101,6 +103,14 @@ void BindAges(nb::module_& m) {
     nb::class_<UniformAges, CraterAgeModel>(
         m, "UniformAges", "Ages uniform over a lifetime of `lifetime_gyr`, whatever the size.")
         .def(nb::init<double>(), "lifetime_gyr"_a);
+    nb::class_<FreshnessAges, CraterAgeModel>(
+        m, "FreshnessAges",
+        "Ages from a freshness f drawn per crater from `freshness` (a `ValueDistribution`, also "
+        "clamped to [0, 1]): age = (1 - f) * `lifetime_gyr`, whatever the size.")
+        .def(nb::init<ValueDistribution, double>(), "freshness"_a, "lifetime_gyr"_a)
+        .def_prop_ro("freshness", &FreshnessAges::Freshness)
+        .def("sample_freshness", &FreshnessAges::SampleFreshness, "random"_a,
+             "Draws a freshness in [0, 1].");
     nb::class_<SteadyStateAges, CraterAgeModel>(
         m, "SteadyStateAges",
         "Ages of a surface `age_gyr` old in steady state: a crater lasts until the "

{terraingenpy-0.1.1.dev73 → terraingenpy-0.1.1.dev77}/terraingen/python/src/random.cpp

@@ -120,7 +120,8 @@ void BindValueDistribution(nb::module_& m) {
     BindOptions<ValueDistribution>(
         m, "ValueDistribution",
         "A random value: constant `a`, uniform from `a` to `b`, normal or log-normal with mean "
-        "`a` and deviation `b`, clipped to [min, max].",
+        "`a` and deviation `b`, or piecewise: uniform within bins between `edges`, each drawn "
+        "in proportion to its entry in `weights`; clipped to [min, max].",
         &ValidateValueDistribution);
     m.def("validate_value_distribution", &ValidateValueDistribution, "distribution"_a,
           kValidateDoc);