:orphan: :orphan: .. image:: ../images/PyMetric.png :width: 300px :align: center .. _quickstart: ========================== PyMetric Quickstart Guide ========================== Welcome to the **PyMetric Quickstart Guide**! This guide helps you quickly install, configure, and begin using **PyMetric**. Pymetric is a flexible framework for geometry-aware scientific computing. Whether you're installing it for development, documentation, or basic usage, this guide will get you up and running. .. contents:: :local: :depth: 2 .. _installation: Installation ------------ Currently, PyMetric is hosted on PyPI and on github. For standard installations, we suggest installing the stable package version from PyPI using pip or conda. To install the development version of the package, you can install directly from the source code on github: .. tab-set:: .. tab-item:: ๐Ÿ“ฆ PyPI (Stable) The recommended way to install **PyMetric** is via PyPI: .. code-block:: bash pip install pymetric This installs the latest stable release, suitable for most users. Additional options are available (see advanced installation). .. tab-item:: ๐Ÿงช Development (GitHub) To install the latest development version directly from GitHub: .. code-block:: bash pip install git+https://github.com/pisces-project/pymetric Alternatively, clone and install locally: .. code-block:: bash git https://github.com/pisces-project/pymetric cd pymetric pip install -e . This is the suggested approach if you are intent on developing the code base. .. tab-item:: ๐Ÿ“š Conda (Experimental) If you're using **Conda**, you can install via `pip` in a conda environment: .. code-block:: bash conda create -n pymetric-env python=3.11 conda activate pymetric-env pip install pymetric (A native conda package is not yet maintained, so this uses pip within conda.) Dependencies ++++++++++++ In order to use pymetric, the following core dependencies are required: +----------------+-----------+--------------------------------------------+ | Package | Version | Description | +================+===========+============================================+ | numpy | >=1.22 | Core numerical array processing | +----------------+-----------+--------------------------------------------+ | scipy | >=1.10 | Scientific computing and numerical tools | +----------------+-----------+--------------------------------------------+ | unyt | >=2.9 | Unit-aware arrays for physical computations| +----------------+-----------+--------------------------------------------+ | h5py | >=3.0 | HDF5 file format support | +----------------+-----------+--------------------------------------------+ | sympy | >=1.14.0 | Symbolic mathematics and algebra | +----------------+-----------+--------------------------------------------+ | matplotlib | any | Plotting and visualization | +----------------+-----------+--------------------------------------------+ | tqdm | any | Progress bars for loops and scripts | +----------------+-----------+--------------------------------------------+ In addition, a number of additional dependency groups are available for more advanced needs. Specifically, PyMetric supports several **optional dependency groups** for specific workflows: .. tab-set:: .. tab-item:: ๐Ÿงช Development `[dev]` To install: .. code-block:: bash pip install pymetric[dev] Includes tools for formatting, linting, and development workflows. +----------------+---------------------------+ | Package | Purpose | +================+===========================+ | pytest | Test framework | +----------------+---------------------------+ | pytest-cov | Test coverage reporting | +----------------+---------------------------+ | black | Code formatter | +----------------+---------------------------+ | mypy | Static type checker | +----------------+---------------------------+ | pre-commit | Git hook management | +----------------+---------------------------+ | jupyter | Interactive notebooks | +----------------+---------------------------+ .. tab-item:: ๐Ÿ“š Documentation `[docs]` To install: .. code-block:: bash pip install pymetric[docs] Includes packages required to build, style, and preview documentation. +------------------------------+-------------------------------------------+ | Package | Purpose | +==============================+===========================================+ | sphinx | Core documentation generator | +------------------------------+-------------------------------------------+ | numpydoc | NumPy-style docstring parser | +------------------------------+-------------------------------------------+ | myst-parser | Markdown support via MyST | +------------------------------+-------------------------------------------+ | sphinx-gallery | Auto-build galleries from example scripts | +------------------------------+-------------------------------------------+ | sphinx-design | Responsive design components (tabs, etc.) | +------------------------------+-------------------------------------------+ | jupyter | Notebook integration | +------------------------------+-------------------------------------------+ | sphinxcontrib-* | Various builder integrations (HTML, Qt) | +------------------------------+-------------------------------------------+ .. tab-item:: ๐Ÿงช Testing `[test]` To install: .. code-block:: bash pip install pymetric[test] A minimal environment to run the test suite and property-based tests. +----------------+------------------------------+ | Package | Purpose | +================+==============================+ | pytest | Core test runner | +----------------+------------------------------+ | pytest-xdist | Parallel test execution | +----------------+------------------------------+ | pytest-cov | Test coverage metrics | +----------------+------------------------------+ | hypothesis | Property-based testing | +----------------+------------------------------+ .. hint:: To confirm that pymetric has been installed correctly, use .. code-block:: bash $ pip show pymetric Name: pymetric Version: 0.1.dev22+g0f5941d Summary: A high-performance library for structured differential geometry and physical field manipulation. Home-page: Author: Author-email: Eliza Diggins License: GPL-3.0-or-later Location: /Users/ediggins/Dev/pymetric/.venv/lib/python3.12/site-packages Editable project location: /Users/ediggins/Dev/pymetric Requires: h5py, matplotlib, numpy, scipy, sympy, tqdm, unyt Required-by: Getting Help ------------ If you encounter issues using **PyMetric**, or have questions about its functionality: - ๐Ÿ’ฌ **Search or open an issue** on our GitHub issue tracker: https://github.com/pisces-project/pymetric/issues - ๐Ÿ“ง **Contact us directly**: You can reach the maintainer, Eliza Diggins, by email at ``eliza.diggins@berkeley.edu`` for questions, bug reports, or suggestions. - ๐Ÿ“– Refer to the full documentation for API details, examples, and conceptual guides. Weโ€™re happy to help you resolve installation problems, clarify behavior, or explore new use cases! Help Develop PyMetric --------------------- Contributions are welcome and encouraged! Whether you're fixing typos, adding examples, writing tests, or developing new features, you can help improve **PyMetric** for everyone. To contribute: 1. ๐Ÿ“‚ **Fork the repository** from the `github `__ 2. ๐Ÿงช Install the development dependencies: .. code-block:: bash pip install pymetric[dev,test,docs] 3. ๐Ÿงผ Run formatting and lint checks: .. code-block:: bash pre-commit run --all-files 4. ๐Ÿงช Run the test suite: .. code-block:: bash pytest -n auto 5. ๐Ÿ“š Build the documentation locally: .. code-block:: bash cd docs make html 6. ๐Ÿ” Submit a pull request with a clear description of the change. If youโ€™re not sure where to start, check the `GitHub issues `__ labeled **`good first issue`** or feel free to ask questions by opening a discussion or emailing the maintainer directly `here `__. Weโ€™d love your help building a powerful, flexible tool for computational geometry and physical modeling! .. raw:: html
.. thumbnail-parent-div-open .. thumbnail-parent-div-close .. raw:: html
Cookbook -------- .. warning:: This section of documentation is under development. Welcome to the **PyMetric Cookbook** โ€” a curated collection of short, practical examples designed to illustrate common tasks, patterns, and utilities within the PyMetric ecosystem. Unlike full tutorials, each recipe focuses on a **specific task** or use case and is meant to be **easy to read and directly usable** in your own workflows. .. contents:: :local: :depth: 1 What You'll Find +++++++++++++++++ - ๐Ÿ“ Coordinate system manipulations (e.g., create custom orthogonal systems) - ๐Ÿงฎ Grid setup for structured domains (uniform, scaled, and ghost-zoned) - ๐Ÿ“Š Field initialization, slicing, and unit handling - ๐Ÿ“ค Buffer conversions and HDF5-backed I/O - โš™๏ธ Applying differential geometry operations (gradient, divergence, Laplacian) - ๐Ÿงช Testing and validating geometric correctness Each recipe is self-contained and includes minimal setup, input/output descriptions, and short code blocks. Think of these as your "how do I...?" reference section. Contributions +++++++++++++ Want to add a recipe? Fork the repository and submit a pull request, or email us at ``eliza.diggins@berkeley.edu``. .. raw:: html
.. thumbnail-parent-div-open .. thumbnail-parent-div-close .. raw:: html
Tutorials --------- .. warning:: This section of documentation is under development. The **PyMetric Tutorials** provide guided, narrative-based walkthroughs that cover broader topics and workflows. Theyโ€™re ideal for: - ๐Ÿง  Learning concepts behind structured differential geometry and physical fields - ๐Ÿ› ๏ธ Building intuition about PyMetricโ€™s abstractions - ๐Ÿงช Developing domain-specific simulations or visualizations These tutorials go beyond isolated examples by combining multiple features of PyMetric into coherent, real-world scenarios. .. contents:: :local: :depth: 1 Topics Covered ++++++++++++++ - ๐Ÿ”ฐ Getting started with coordinate systems, grids, and fields - ๐Ÿงญ Constructing curvilinear coordinate systems - ๐Ÿงฌ Working with symbolic tensors and metrics - ๐Ÿ“‰ Visualizing data fields and derivatives - ๐Ÿ“ฆ Saving, loading, and transforming physical data Each tutorial includes: - Explanatory text - Live examples (or Jupyter integration, where applicable) - Step-by-step commentary and plots Happy modeling! ๐ŸŽ‰ If youโ€™d like to contribute or request a tutorial, contact: ๐Ÿ“ง ``eliza.diggins@berkeley.edu`` or open an issue on https://github.com/pisces-project/pymetric/issues .. raw:: html
.. thumbnail-parent-div-open .. raw:: html
.. only:: html .. image:: /auto_quickstart/tutorials/images/thumb/sphx_glr_plot_building_fields_thumb.png :alt: :ref:`sphx_glr_auto_quickstart_tutorials_plot_building_fields.py` .. raw:: html
Building Fields
.. thumbnail-parent-div-close .. raw:: html
.. toctree:: :hidden: :includehidden: /auto_quickstart/cookbook/index.rst /auto_quickstart/tutorials/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_quickstart_python.zip ` .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download all examples in Jupyter notebooks: auto_quickstart_jupyter.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_