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.
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:
The recommended way to install PyMetric is via PyPI:
pip install pymetric
This installs the latest stable release, suitable for most users. Additional options are available (see advanced installation).
To install the latest development version directly from GitHub:
pip install git+https://github.com/pisces-project/pymetric
Alternatively, clone and install locally:
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.
If you’re using Conda, you can install via pip in a conda environment:
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:
To install:
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 |
To install:
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) |
To install:
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
$ 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 <eliza.diggins@berkeley.edu>
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: pisces-project/pymetric#issues
📧 Contact us directly: You can reach the maintainer, Eliza Diggins, by email at
eliza.diggins@berkeley.edufor 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:
📂 Fork the repository from the github
🧪 Install the development dependencies:
pip install pymetric[dev,test,docs]
🧼 Run formatting and lint checks:
pre-commit run --all-files
🧪 Run the test suite:
pytest -n auto
📚 Build the documentation locally:
cd docs make html
🔁 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!
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.
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.
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.
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
pisces-project/pymetric#issues
