:orphan:

:orphan:

.. image:: ../images/PyMetric.png
   :width: 300px
   :align: center

==================
Example Gallery
==================

Welcome to the **PyMetric Example Gallery**!

This section showcases a curated collection of concise, self-contained examples demonstrating
core features and capabilities of the PyMetric library. Whether you're exploring differential geometry
on structured grids, manipulating tensor fields, or performing symbolic and numerical calculations in curvilinear coordinates,
these examples are designed to help you learn by doing.

Each script is:

- Minimal and focused on a single concept,
- Ready to run and modify interactively,
- Accompanied by inline explanations and visual outputs when appropriate.

Browse through, try them out, and use them as starting points for your own work.

.. contents::
   :local:
   :depth: 2

Examples are separated by their concept's location in the codebase.



.. raw:: html

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

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

:orphan:

Core Modules: Coordinate Systems
================================

This gallery highlights examples built around the :mod:`coordinates` module, PyMetric's foundation
for defining and working with structured coordinate systems.

The :mod:`coordinates` module provides a flexible API for defining Cartesian,
polar, cylindrical, spherical, and general curvilinear systems,
as well as custom user-defined coordinates. These examples showcase how to:

- Instantiate and explore predefined coordinate systems,
- Evaluate coordinate transforms and Jacobians,
- Work with symbolic metrics and basis vectors,
- Integrate coordinate systems into grid construction and field definitions.

Whether you're visualizing a spherical metric or customizing an orthogonal system for a simulation,
these examples serve as practical guides to mastering the geometry backbone of PyMetric.

.. hint::

    For in-depth user documentation, see :ref:`coordinates_user`.



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Visualize how the radial coordinate lines (R-contours) in the OblateSpheroidalCoordinateSystem change as a function of eccentricity.">

.. only:: html

  .. image:: /auto_examples/a_coordinate_systems/images/thumb/sphx_glr_plot_ellipsoidal_coordinates_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_a_coordinate_systems_plot_ellipsoidal_coordinates.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Oblate Spheroidal Coordinates: Effect of Eccentricity</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Visualize how the radial coordinate lines (R-contours) in the OblateHomoeoidalCoordinateSystem change as a function of eccentricity.">

.. only:: html

  .. image:: /auto_examples/a_coordinate_systems/images/thumb/sphx_glr_plot_homoeoidal_coordinates_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_a_coordinate_systems_plot_homoeoidal_coordinates.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Oblate Homoeoidal Coordinates: Effect of Eccentricity</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

:orphan:

Core Modules: Grids
===================

This gallery highlights examples built around the :mod:`grids` module, which provides the structured backbone
for numerical field representation and finite-difference computation in PyMetric.

The :mod:`grids` module offers a powerful API for constructing regular, scaled, and fully generic
structured grids—each integrated with coordinate system metadata and axis-aware utilities.
These examples demonstrate how to:

- Create uniform and non-uniform spatial grids tied to coordinate systems,
- Extract coordinate arrays and physical units,
- Use ghost zones, chunking, and broadcasting,
- Apply field operations like partial derivatives and interpolation.

Whether you're building a finite-difference solver or managing multi-axis tensor data,
these examples provide practical insight into leveraging PyMetric’s spatial grid machinery.

.. hint::

    For detailed user documentation, see :ref:`grids`.



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Compute gradients in a Cartesian coordinate system on a non-uniform grid with higher resolution near the origin.">

.. only:: html

  .. image:: /auto_examples/b_grids/images/thumb/sphx_glr_plot_nonuniform_grid_grad_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_b_grids_plot_nonuniform_grid_grad.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Cartesian Gradient (Non-Uniform)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Compute the Laplacian of a field using the grid interface.">

.. only:: html

  .. image:: /auto_examples/b_grids/images/thumb/sphx_glr_plot_grid_laplacian_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_b_grids_plot_grid_laplacian.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Grid Laplacian</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

:orphan:

Core Modules: Fields
====================

This gallery showcases examples based on the :mod:`fields` module, PyMetric's core abstraction
for physical quantities defined over space—scalars, vectors, tensors, and more.

The :mod:`fields` module provides a unified interface for working with field components, units,
buffers, and coordinate-aware differential operations. These examples walk through how to:

- Construct scalar, vector, and tensor fields over structured grids,
- Manage physical units and buffer types (e.g., NumPy, unyt, HDF5),
- Broadcast, expand, reduce, and reshape field components,
- Apply differential geometry operations like gradients, divergence, and Laplacians,
- Combine symbolic metadata with numerical buffers for hybrid workflows.

From initializing a field from an analytic expression to computing its divergence in curved space,
these examples demonstrate the expressive and extensible field API at the heart of PyMetric.

.. hint::

    For complete documentation, see :ref:`fields`.



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Compute the NFW density from a potential profile.">

.. only:: html

  .. image:: /auto_examples/c_fields/images/thumb/sphx_glr_plot_elem_lap_nfw_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_c_fields_plot_elem_lap_nfw.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">NFW Density from Potential</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to compute the elementwise partial derivatives of a scalar field in a Cartesian coordinate system using PyMetric’s high-level DenseField interface.">

.. only:: html

  .. image:: /auto_examples/c_fields/images/thumb/sphx_glr_plot_elem_wise_diff_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_c_fields_plot_elem_wise_diff.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Elementwise Partial Derivative (2D Cosine)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Compute an NFW density in Oblate Coordinates.">

.. only:: html

  .. image:: /auto_examples/c_fields/images/thumb/sphx_glr_plot_nfw_symmetry_break_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_c_fields_plot_nfw_symmetry_break.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">NFW Density in Oblate Coordinates</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

:orphan:

Auxiliary Modules: Differential Geometry
========================================

These examples showcase some of the low-level functions from the
:mod:`differential_geometry` module.

.. warning::

    In general, direct use of :mod:`differential_geometry` introduces much more
    complexity than using equivalent functions at the level of fields or grids.



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Calculate the gradient of a function in Cartesian coordinates.">

.. only:: html

  .. image:: /auto_examples/d_differential_geometry/images/thumb/sphx_glr_plot_cartesian_gradient_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_d_differential_geometry_plot_cartesian_gradient.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Gradient In Cartesian Coordinates</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /auto_examples/a_coordinate_systems/index.rst
   /auto_examples/b_grids/index.rst
   /auto_examples/c_fields/index.rst
   /auto_examples/d_differential_geometry/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>`_