:orphan:

.. currentmodule:: cratermaker

.. _gal:

###############
Example Gallery
###############

Below you will find a selection of examples that demonstrate how to use Cratermaker. The gallery is organized by the main components of Cratermaker. Each example is fully working and can be run directly.


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>


Simuation and Visualization
===========================

This section provides examples of how to run simulations using the main :ref:`api-simulation` component of Cratermaker to emplace craters on a surface and visualize the results with various tools.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to emplace a single large crater on the Moon using Cratermaker&#x27;s Simulation.emplace() method. The crater is defined with a specific diameter and location. The final surface is exported and visualized using PyVista.">

.. only:: html

  .. image:: /auto_examples/01-simulation_and_visualization/images/thumb/sphx_glr_1.1-visualize_one_crater_thumb.png
    :alt:

  :doc:`/auto_examples/01-simulation_and_visualization/1.1-visualize_one_crater`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Manually emplace a single crater on the Moon and visualize it with PyVista</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to use the DataSurface to fetch real DEM data for a local region on the Moon. In this case, we center the surface on Kepler crater (321.9913E, 8.121N) with a radius of 50 km and a resolution of 200 m/pix. We then visualize the surface using PyVista both with and without the superdomain.">

.. only:: html

  .. image:: /auto_examples/01-simulation_and_visualization/images/thumb/sphx_glr_1.5-Kepler_crater_datasurface_thumb.png
    :alt:

  :doc:`/auto_examples/01-simulation_and_visualization/1.5-Kepler_crater_datasurface`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Create a DataSurface centered on Kepler crater</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to load arbitrary DEM data using the data composer.">

.. only:: html

  .. image:: /auto_examples/01-simulation_and_visualization/images/thumb/sphx_glr_1.7-load_phobos_dem_thumb.png
    :alt:

  :doc:`/auto_examples/01-simulation_and_visualization/1.7-load_phobos_dem`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Load a DEM of phobos</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to run a crater population simulation on the Moon and visualize the final surface using PyVista.">

.. only:: html

  .. image:: /auto_examples/01-simulation_and_visualization/images/thumb/sphx_glr_1.2-Moon_simulation_pyvista_thumb.png
    :alt:

  :doc:`/auto_examples/01-simulation_and_visualization/1.2-Moon_simulation_pyvista`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Run a simulation of the Moon and visualize with PyVista</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to run a lunar simulation in &#x27;Quasi-Monte Carlo&#x27; mode, where the largest craters are read from a csv file that gives their diameters and locations, along with one or more columns that indicate an emplacement time or time range.  For details, see ug-production-quasimc for details.">

.. only:: html

  .. image:: /auto_examples/01-simulation_and_visualization/images/thumb/sphx_glr_1.8-Moon_quasimc_thumb.png
    :alt:

  :doc:`/auto_examples/01-simulation_and_visualization/1.8-Moon_quasimc`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Run a simulation of the Moon with basins emplaced using QuasiMC mode</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to emplace a crater at a specific distance and bearing from the center of a HiResLocalSurface using the new relative_location arguments that can be passed to the emplace method. This is useful to place a crater on a HiResLocalSurface at a specific location relative to the center without trying to figure out what lat,lon coordinates to use. In this example, we will emplace a sequence of craters in a spiral pattern. This not meant to be a realistic planetary surface, but it looks pretty cool!">

.. only:: html

  .. image:: /auto_examples/01-simulation_and_visualization/images/thumb/sphx_glr_1.6-emplace_crater_at_distance_thumb.png
    :alt:

  :doc:`/auto_examples/01-simulation_and_visualization/1.6-emplace_crater_at_distance`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Emplace a crater a specific distance and bearing from the center of a HiResLocalSurface</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Cratermaker can export Simulation data to a variety of GIS vector formats, including GeoPackage, ESRI Shapefile, and more. We do this using the GeoPandas library, which provides a set of useful tools for working with geospatial data in Python. Using the &quot;driver&quot; argument of the export method, you can export to just about any format supported by GeoPandas (see here). This is the same tool used to export data as a mesh in VTK format using the &quot;VTK&quot; driver, which does not use GeoPandas.">

.. only:: html

  .. image:: /auto_examples/01-simulation_and_visualization/images/thumb/sphx_glr_1.4-export_to_geopackage_thumb.png
    :alt:

  :doc:`/auto_examples/01-simulation_and_visualization/1.4-export_to_geopackage`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Export Cratermaker data to GeoPackage and visualize with GeoPandas</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to use the HiResLocal Surface to run a crater population over a small region of a planet, in this case Mars.">

.. only:: html

  .. image:: /auto_examples/01-simulation_and_visualization/images/thumb/sphx_glr_1.3-mars_simulation_pyvista_thumb.png
    :alt:

  :doc:`/auto_examples/01-simulation_and_visualization/1.3-mars_simulation_pyvista`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Run a simulation of a local region on Mars.</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


Production Functions and Monte Carlo Utilities
==============================================

This section provides examples of how to generate both projectile and crater populations using the :ref:`api-production` component, as well as how to use the functions contained in the :ref:`api-utils-montecarlo` utilities.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Here we plot the chronology component of the Neukum production function for the Moon and Mars. The chronology function is the number of craters per unit area per unit time, which is a function of crater diameter and age. The plot shows the number of craters per square kilometer per million years as a function of time for a 1 km crater.">

.. only:: html

  .. image:: /auto_examples/02-production/images/thumb/sphx_glr_2.3-plot_chronology_thumb.png
    :alt:

  :doc:`/auto_examples/02-production/2.3-plot_chronology`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plot the NPF Chronology function for the Moon and Mars</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the generation of random impact angles.">

.. only:: html

  .. image:: /auto_examples/02-production/images/thumb/sphx_glr_2.8-plot_random_impact_angle_thumb.png
    :alt:

  :doc:`/auto_examples/02-production/2.8-plot_random_impact_angle`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plot a distribution of random impact angles</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the generation of random impact sizes, which is used to sample production function SFDs. In this example, we just draw from a simple power law.">

.. only:: html

  .. image:: /auto_examples/02-production/images/thumb/sphx_glr_2.5-plot_random_size_thumb.png
    :alt:

  :doc:`/auto_examples/02-production/2.5-plot_random_size`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plot a distribution of random sizes</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we will plot the cumulative size-frequency distribution of projectiles for a 1 Gy age, which is derived from Ivanov, Neukum, and Wagner (2001) [#]_.">

.. only:: html

  .. image:: /auto_examples/02-production/images/thumb/sphx_glr_2.2-plot_projectilecsfd_thumb.png
    :alt:

  :doc:`/auto_examples/02-production/2.2-plot_projectilecsfd`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plot the Neukum projectile CSFD</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the generation of random impact locations.">

.. only:: html

  .. image:: /auto_examples/02-production/images/thumb/sphx_glr_2.6-plot_random_location_thumb.png
    :alt:

  :doc:`/auto_examples/02-production/2.6-plot_random_location`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plot a distribution of random locations</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we use the :pyProduction.sample method to sample populations of craters from a production function. We will sample 1000 craters from each production function and repeat this 100 times. The population samples are then plotted against the expected value given by :pyProduction.function">

.. only:: html

  .. image:: /auto_examples/02-production/images/thumb/sphx_glr_2.4-plot_sample_csfd_thumb.png
    :alt:

  :doc:`/auto_examples/02-production/2.4-plot_sample_csfd`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Sample a power law and lunar Neukum Production Function</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the generation of random velocities using the :pyget_random_velocity function from the api-utils-montecarlo module. The expected distribution of imapct velocities is a modified Maxwell-Boltzmann distribution. The modification is related to the relationship between the mean velocity and the escape velocity. If vmean &gt; vescape, then the distribution will adjusted so that the escape velocity is the minimum velocity by computing an encounter velocity then summing the encounter and escape velocities in quadrature. If vmean &lt; vescape, then the distirbution will be a truncated maxwellian.">

.. only:: html

  .. image:: /auto_examples/02-production/images/thumb/sphx_glr_2.7-plot_random_velocity_thumb.png
    :alt:

  :doc:`/auto_examples/02-production/2.7-plot_random_velocity`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plot a distribution of random velocities given a mean</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we will be using the &quot;neukum&quot; prodcution model in Cratermaker to plot isochrons for three different age surfaces. We will also format the plots so with similar axes as Figure 2 of Neukum, Ivanov, and Hartmann (2001) [#]_, but with a handy logarithmic grid.">

.. only:: html

  .. image:: /auto_examples/02-production/images/thumb/sphx_glr_2.1-plot_isochron_thumb.png
    :alt:

  :doc:`/auto_examples/02-production/2.1-plot_isochron`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plot isochrons for the Moon and Mars for 1 Ma, 1 Ga, and 4 Ga using the Neukum Production Function</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


Projectiles and Scaling
=======================

This section provides examples of the use of the :ref:`api-projectile` and :ref:`api-scaling` components of Cratermaker to model projectil populations and projectile-crater size scaling relationships.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to generate and visualize random impact angles for projectiles using cratermaker.">

.. only:: html

  .. image:: /auto_examples/03-projectiles_and_scaling/images/thumb/sphx_glr_3.5-plot_projectile_impact_angle_thumb.png
    :alt:

  :doc:`/auto_examples/03-projectiles_and_scaling/3.5-plot_projectile_impact_angle`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plot random projectile impact angles</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the generation of random velocities using the :pyget_random_velocity function from the api-utils-montecarlo module. The expected distribution of imapct velocities is a modified Maxwell-Boltzmann distribution. The modification is related to the relationship between the mean velocity and the escape velocity. If vmean &gt; vescape, then the distribution will adjusted so that the escape velocity is the minimum velocity by computing an encounter velocity then summing the encounter and escape velocities in quadrature. If vmean &lt; vescape, then the distirbution will be a truncated maxwellian.">

.. only:: html

  .. image:: /auto_examples/03-projectiles_and_scaling/images/thumb/sphx_glr_3.4-plot_projectile_random_velocity_thumb.png
    :alt:

  :doc:`/auto_examples/03-projectiles_and_scaling/3.4-plot_projectile_random_velocity`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plot a distribution of random velocities given a mean</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the generation of random impact locations.">

.. only:: html

  .. image:: /auto_examples/03-projectiles_and_scaling/images/thumb/sphx_glr_3.3-plot_projectile_random_location_thumb.png
    :alt:

  :doc:`/auto_examples/03-projectiles_and_scaling/3.3-plot_projectile_random_location`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plot a distribution of random locations</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to use the ug-scaling class to calculate the simple-to-complex transition diameter as a function of surface gravity bodies using the Monte Carlo scaling model. Because the scaling model is non-deterministic, we sample each body 100 times to get a distribution of transition diameters. We plot the mean and standard deviation of the transition diameter is plotted for each body, showing results that resemble Fig. 7 of Schenk et al. (2021) [#]_.">

.. only:: html

  .. image:: /auto_examples/03-projectiles_and_scaling/images/thumb/sphx_glr_3.1-plot_transition_diameter_thumb.png
    :alt:

  :doc:`/auto_examples/03-projectiles_and_scaling/3.1-plot_transition_diameter`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The simple-to-complex transition diameter</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to use the ug-scaling class to calculate the final crater diameter for different planetary bodies.  Normally, the scaling component would not be invoked manually like this. Instead, the scaling model is used internally by the ug-crater component. This example demonstrates how the scaling model can be used on its own.">

.. only:: html

  .. image:: /auto_examples/03-projectiles_and_scaling/images/thumb/sphx_glr_3.2-plot_projectile_to_crater_scaling_thumb.png
    :alt:

  :doc:`/auto_examples/03-projectiles_and_scaling/3.2-plot_projectile_to_crater_scaling`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Crater scaling for various planetary surfaces</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


Topography
==========

This section provides examples of how to use the :ref:`api-surface` and :ref:`api-morphology` components of Cratermaker to model the surface topography of craters and the topographic evolution of cratered surfaces.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example showcases how to create a crater and ejecta profile using the &quot;basicmoon&quot; morphology model from the CraterMaker package. The crater is created with a radius of 1 km, and the profiles are plotted in a 2D space normalized to the crater radius.">

.. only:: html

  .. image:: /auto_examples/04-topography/images/thumb/sphx_glr_4.2-plot_crater_profile_thumb.png
    :alt:

  :doc:`/auto_examples/04-topography/4.2-plot_crater_profile`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Create a crater and ejecta profile with the "basicmoon" morphology model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example showcases how to create a crater and ejecta profile using the &quot;basicmoon&quot; morphology model from the Cratermaker and visual its topography. This will mimic how CTEM generates a test crater, though it is much simpler to run than that venerable old Fortran-based beast of a code!. The crater is created with a radius of 1 km. The hill shade uses the same settings that CTEM uses.">

.. only:: html

  .. image:: /auto_examples/04-topography/images/thumb/sphx_glr_4.1-plot_shaded_crater_thumb.png
    :alt:

  :doc:`/auto_examples/04-topography/4.1-plot_shaded_crater`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Create a shaded topographic representation of a crater</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to create a ray intensity map for a crater using the &quot;basicmoon&quot; morphology model.">

.. only:: html

  .. image:: /auto_examples/04-topography/images/thumb/sphx_glr_4.4-plot_ray_intensity_thumb.png
    :alt:

  :doc:`/auto_examples/04-topography/4.4-plot_ray_intensity`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plot the ray intensity map for a crater</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to use the :pyapply_diffusion method in the ug-surface class to model topographic diffusion. In this example, we will simulate the change in elevation over time of a hill with a Gaussian profile. This example has an analytical solution, which we will compare against the numerical solution provided by the diffusion method.">

.. only:: html

  .. image:: /auto_examples/04-topography/images/thumb/sphx_glr_4.3-plot_topographic_diffusion_thumb.png
    :alt:

  :doc:`/auto_examples/04-topography/4.3-plot_topographic_diffusion`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Topographic Diffusion</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


Counting
========

This section provides examples of how to use the :ref:`api-counting` component of Cratermaker to analye crater statistics from a Cratermaker simulation.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we will emplace a small simple crater on a HiResLocal surface, and then apply topographic diffusion to the surface in order to simulate diffusive degradation of the crater. We will then compare the applied diffusive degradation amount with the estimated degradation state of the crater using the DepthCount model, which uses depth-to-diameter as a proxy for degradation state. If the proxy is good, the values of degradation state computed by Cratermaker vs applied degradation should plot along a 1:1 line.">

.. only:: html

  .. image:: /auto_examples/05-counting/images/thumb/sphx_glr_5.2-degradation-state_thumb.png
    :alt:

  :doc:`/auto_examples/05-counting/5.2-degradation-state`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Compute the degradation state of a crater</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example, we will create a DataSurface centered on a region of the Moon that contains the Lansberg B crater. We will then supply a slightly wrong crater size and location, and use the Counting class to fit the crater rim to the DEM data.">

.. only:: html

  .. image:: /auto_examples/05-counting/images/thumb/sphx_glr_5.1-fit_rim_thumb.png
    :alt:

  :doc:`/auto_examples/05-counting/5.1-fit_rim`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Fit a crater rim given a DEM and approximate crater size and location</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /auto_examples/01-simulation_and_visualization/index.rst
   /auto_examples/02-production/index.rst
   /auto_examples/03-projectiles_and_scaling/index.rst
   /auto_examples/04-topography/index.rst
   /auto_examples/05-counting/index.rst


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download all examples in Python source code: auto_examples_python.zip </auto_examples/auto_examples_python.zip>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download all examples in Jupyter notebooks: auto_examples_jupyter.zip </auto_examples/auto_examples_jupyter.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_