:orphan:

:orphan:

.. image:: ../images/pisces.svg
   :width: 300px
   :align: center

.. _examples:
######################
Pisces Example Gallery
######################

Welcome to the **Pisces Example Gallery**!

This section presents a curated collection of concise, hands-on examples illustrating the key features and modeling
capabilities of the Pisces library. Whether you're working with analytic cluster models, constructing physical profiles,
or exploring differential geometry in astrophysical systems, these examples are built to teach by doing.

Each example is:

- Focused on a single, well-defined concept,
- Ready to run and customize in your own workflows,
- Accompanied by inline documentation and visual outputs where helpful.

Explore the gallery to get started quickly, understand how to use Pisces effectively, and adapt these
templates to accelerate your scientific modeling.

Examples are grouped by their conceptual location within the Pisces codebase.

.. contents:: Gallery Sections
   :local:
   :depth: 2



.. raw:: html

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

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

*************************************
Models
*************************************

This section showcases end-to-end examples for building and analyzing complete astrophysical models.
These are practical workflows that combine various components, such as density profiles,
temperature or pressure models, and often include magnetic fields or particle distributions.

Models are contained in the :mod:`~pisces.models` subpackage. For documentation on models,
see :ref:`models_overview`.



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example constructs a simple spherical galaxy cluster model using Pisces and visualizes its thermodynamic profiles, including temperature, entropy, and pressure.">

.. only:: html

  .. image:: /auto_examples/a_models/images/thumb/sphx_glr_plot_spherical_galaxy_cluster_model_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_a_models_plot_spherical_galaxy_cluster_model.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Build a Spherical Galaxy Cluster</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to build a spherical galaxy cluster model from an analytic temperature profile and a gas density profile using the .from_temperature_and_density constructor.">

.. only:: html

  .. image:: /auto_examples/a_models/images/thumb/sphx_glr_plot_spherical_galaxy_cluster_model_from_temp_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_a_models_plot_spherical_galaxy_cluster_model_from_temp.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Build a Galaxy Cluster From Temperature and Density</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use the PolytropicStarModel to generate the internal structure of a star governed by a polytropic equation of state.">

.. only:: html

  .. image:: /auto_examples/a_models/images/thumb/sphx_glr_plot_polytropic_star_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_a_models_plot_polytropic_star.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Build a Polytropic Star Model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example generates a set of magnetized galaxy cluster models with varying magnetic pressure fractions (beta parameters) and compares their resulting temperature, entropy, magnetic field strength, and Alfven speed profiles.">

.. only:: html

  .. image:: /auto_examples/a_models/images/thumb/sphx_glr_plot_magnetized_galaxy_clusters_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_a_models_plot_magnetized_galaxy_clusters.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Build a Magnetized Galaxy Cluster</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

*************************************
Simulations and Initial Conditions
*************************************

These examples demonstrate how to export models created in Pisces for use as initial conditions in
various astrophysical simulation codes. They cover the process of translating static models into
dynamic simulations, including setting up the necessary parameters and formats required by different simulation
software.

Simulation support is provided through :mod:`~pisces.extensions.simulation` and may depend on third-party libraries.
For documentation on simulation features, see :ref:`simulations`.



.. 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 ICs for Gadget-4. As an example, we&#x27;ll create two spherical galaxy cluster models with slightly different properties and then construct initial conditions where they will collide. These initial conditions can then be passed off to Gadget-4 to run the simulation.">

.. only:: html

  .. image:: /auto_examples/b_simulations/images/thumb/sphx_glr_plot_gadget_ics_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_b_simulations_plot_gadget_ics.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Initial Conditions for Gadget-4</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

*************************************
Profiles
*************************************

This section provides examples illustrating how to use and customize built-in profiles for density,
temperature, entropy, and related physical quantities.

Examples here are generally isolated to demonstrate specific analytic or empirical profiles and how they
can be composed into more complex systems.



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example compares several widely used spherically symmetric density profiles in astrophysics:">

.. only:: html

  .. image:: /auto_examples/c_profiles/images/thumb/sphx_glr_plot_comparing_density_profiles_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_c_profiles_plot_comparing_density_profiles.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Comparing Common Density Profiles</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="See how profiles can provide both numeric and analytical derived quantities.">

.. only:: html

  .. image:: /auto_examples/c_profiles/images/thumb/sphx_glr_plot_nfw_einasto_potential_profiles_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_c_profiles_plot_nfw_einasto_potential_profiles.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Derived and Computed Gravitational Potentials</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

*************************************
Geometry and Grids
*************************************

This section provides examples related to geometry and grids in the context of astrophysical modeling with Pisces.
These examples demonstrate how to define and manipulate various geometric configurations and grid structures
that are essential for accurate simulations and analyses. Because these grids and coordinate systems are
a core part of every Pisces model, these examples are more conceptual and less end-to-end than those in other sections.

Geometry and grid support is provided through :mod:`~pisces.geometry.grids` and :mod:`~pisces.geometry.coordinates`.
Documentation for coordinate grids can be found at :ref:`grid_overview`, and documentation for coordinate systems
can be found at :ref:`coordinate_overview`.



.. raw:: html

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

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

*************************************
Particle Generation and Sampling
*************************************

This gallery focuses on examples where particle sampling and data generation are the main goals.
This includes distributing particles from profile-based models, assigning velocities, and exporting
snapshots for simulation use.



.. 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 particle datasets for a galaxy cluster model using Pisces. To do so, we&#x27;ll use the built-in hook for generating particles, which gives us access to the generate_particles method.">

.. only:: html

  .. image:: /auto_examples/u_particles/images/thumb/sphx_glr_plot_galaxy_cluster_particles_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_u_particles_plot_galaxy_cluster_particles.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Particle Datasets: Galaxy Clusters</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

*************************************
Extensions and Experimental Features
*************************************

This section showcases examples that go beyond the core functionality of `Pisces`.
It includes experimental modules, plugin-based systems, or utilities that may be under active development
or not yet part of the stable API.

Contents:

- Visualization tools
- Third-party integrations
- Experimental and contributed utilities



.. raw:: html

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

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /auto_examples/a_models/index.rst
   /auto_examples/b_simulations/index.rst
   /auto_examples/c_profiles/index.rst
   /auto_examples/d_geometry_and_grids/index.rst
   /auto_examples/u_particles/index.rst
   /auto_examples/z_extensions/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>`_