pmmoto 0.1.0__tar.gz

pmmoto-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Timothy M. Weigand
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

pmmoto-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include src/ *.pyx *.pxd *.py *.hpp *.h

pmmoto-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: pmmoto
+Version: 0.1.0
+Summary: Porous Media Topology and Morphology Toolkit
+Author-email: "Timothy M. Weigand" <timothy.weigand@unc.edu>
+License: MIT
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: numpy<2.0
+Requires-Dist: cython==3.0
+Requires-Dist: mpi4py>=4.0.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: connected_components_3d>=3.12.4
+Requires-Dist: matplotlib>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: mypy>=1.15; extra == "dev"
+Requires-Dist: tox>=3.24; extra == "dev"
+Requires-Dist: pytest_benchmark>=5.1.0; extra == "dev"
+Requires-Dist: ruff>=0.11.5; extra == "dev"
+Requires-Dist: interrogate>=1.5.0; extra == "dev"
+Requires-Dist: typing_extensions>=4.6; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Dynamic: license-file

pmmoto-0.1.0/README.md

@@ -0,0 +1,124 @@
+# PMMoTo
+
+![Tests](https://github.com/tmweigand/PMMoTo/actions/workflows/tests.yml/badge.svg)
+
+![logo-1-text](https://github.com/tmweigand/PMMoTo/assets/68024672/5f667c8f-5498-4597-9af0-76fd6a9bc59a)
+
+---
+
+**PMMoTo** (Parallel Morphological Multiphase Toolkit) is an open-source, MPI-parallelized Python/C++ toolkit for simulating multiphase flow and morphological processes in complex porous media. PMMoTo provides efficient, scalable algorithms for generating, analyzing, and simulating pore-scale phenomena in 2D and 3D domains, with a focus on high-performance computing and extensibility.
+
+---
+
+## Features
+
+- **Parallel domain decomposition** using MPI for distributed-memory simulations
+- **Morphological drainage and imbibition** algorithms for capillary-dominated flow
+- **Flexible porous media generation**: random fields, sphere packs, atomistic models, and more
+- **Multiphase simulation**: support for multiple fluid phases and wettability
+- **Distance transforms**: exact Euclidean distance transforms with periodic and distributed support
+- **Capillary pressure–saturation curve computation** and other pore-scale analysis tools
+- **Parallel VTK output** for visualization in ParaView and other tools
+- **Modular, extensible design**: Python/C++ hybrid, easy to add new algorithms
+
+---
+
+## Installation
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/tmweigand/PMMoTo.git
+   cd PMMoTo
+   ```
+
+2. **Install dependencies:**
+
+   - Python 3.8+
+   - `numpy`
+   - `mpi4py`
+   - `matplotlib`
+   - (Optional) `pytest` for testing
+
+   Install with pip:
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Build C/C++ extensions (required for performance):**
+   ```bash
+   python setup.py build_ext --inplace
+   ```
+
+---
+
+## Usage
+
+### Example: Morphological Drainage in an Inkbottle Geometry
+
+```bash
+mpirun -np 8 python examples/drainage_inkbottle.py
+```
+
+- Output images and data are saved in `examples/` or `data_out/`.
+- Results can be visualized with ParaView or other VTK-compatible tools.
+
+### Custom Porous Media
+
+You can generate custom porous media using built-in generators (random, spheres, atoms) or your own. See `examples/drainage_inkbottle.py` and the `domain_generation` module for details.
+
+---
+
+## Directory Structure
+
+```
+src/pmmoto/
+    core/               # Core parallel and utility routines (domain, subdomain, communication, utils)
+    domain_generation/  # Porous media and multiphase domain generation
+    filters/            # Morphological and distance transform algorithms
+    io/                 # Input/output, VTK export, data readers
+    analysis/           # Analysis tools (Minkowski functionals, etc.)
+    particles/          # Particle and atom data structures
+    examples/           # Example scripts and workflows
+    tests/              # Unit and integration tests
+```
+
+---
+
+## Testing
+
+Run the test suite (requires `pytest` and `mpi4py`):
+
+```bash
+mpirun -np 8 python -m pytest tests/
+```
+
+---
+
+## Documentation
+
+- **API documentation:** See docstrings in source files.
+- **Examples:** See the `examples/` directory for ready-to-run scripts.
+
+---
+
+## Citing
+
+If you use PMMoTo in your research, please cite the relevant publication (add citation here if available).
+
+---
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+## Contact
+
+For questions, issues, or contributions, please open an issue or pull request on [GitHub](https://github.com/tmweigand/PMMoTo).
+
+---
+
+**PMMoTo** — Parallel Morphological Multiphase Toolkit for Porous Media Simulation

pmmoto-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "pmmoto"
+version = "0.1.0"
+description = "Porous Media Topology and Morphology Toolkit"
+
+authors = [
+    {name = "Timothy M. Weigand", email = "timothy.weigand@unc.edu"},
+]
+
+license = { text = "MIT" }
+
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "numpy<2.0",
+    "cython==3.0",
+    "mpi4py>=4.0.0",
+    "scipy>=1.11",
+    "connected_components_3d>=3.12.4",
+    "matplotlib>=3.0"
+]
+requires-python = ">=3.10"
+
+[build-system]
+requires = ["setuptools", "numpy", "cython"]
+build-backend = "setuptools.build_meta"
+
+[tools.setuptools.packages.find]
+where = ["src"]
+include = ["pmmoto*"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=6.0",
+    "pytest-cov>=2.0",
+    "mypy>=1.15",
+    "tox>=3.24",
+    "pytest_benchmark>=5.1.0",
+    "ruff>=0.11.5",
+    "interrogate>=1.5.0",
+    # "pytest-mpi @ git+https://github.com/orausch/pytest-mpi.git@master",
+    "typing_extensions>=4.6"
+]
+docs = [
+    "sphinx>=7.0",
+    "sphinx_rtd_theme",
+    "myst-parser"
+]
+
+[tool.black]
+line-length = 88
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+src = ["src"]
+exclude = [
+    "src/pmmoto/io/evtk",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "D"]  # E = pycodestyle, F = pyflakes, D = pydocstyle
+ignore = ["D107", "D203", "D213", "D400", "D415", "D200"]
+
+[tool.interrogate]
+fail-under = 90
+ignore-init-method = true
+ignore-module = true
+

pmmoto-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pmmoto-0.1.0/setup.py

@@ -0,0 +1,103 @@
+"""Setup script for PMMoTo.
+
+Builds Cython/C++ extensions and installs the PMMoTo package.
+"""
+
+import sys
+from setuptools import Extension, setup
+from Cython.Build import cythonize
+import Cython.Compiler.Options
+import numpy
+
+Cython.Compiler.Options.annotate = True
+
+
+# try:
+#     subprocess.run(["mpirun", "--version"], check=True, stdout=subprocess.PIPE)
+# except FileNotFoundError:
+#     sys.stderr.write("Error: MPI is not installed. Install OpenMPI or MPICH.\n")
+#     sys.exit(1)
+
+
+extra_compile_args = ["-std=c++17"]
+if sys.platform == "win32":
+    extra_compile_args += ["/std:c++17", "/O2"]
+else:
+    extra_compile_args += ["-std=c++17", "-O3", "-ffast-math", "-pthread"]
+
+if sys.platform == "darwin":
+    extra_compile_args += ["-stdlib=libc++", "-mmacosx-version-min=10.9"]
+
+
+cmdclass = {}
+
+ext_modules = [
+    Extension(
+        "pmmoto.core._voxels",
+        ["src/pmmoto/core/_voxels.pyx"],
+        include_dirs=["src/pmmoto/core"],
+        language="c++",
+        extra_compile_args=extra_compile_args,
+    ),
+    Extension(
+        "pmmoto.filters.distance._distance",
+        ["src/pmmoto/filters/distance/_distance.pyx"],
+        include_dirs=["src/pmmoto/filters/distance", numpy.get_include()],
+        language="c++",
+        extra_compile_args=extra_compile_args,
+    ),
+    Extension(
+        "pmmoto.analysis._minkowski",
+        [
+            "src/pmmoto/analysis/_minkowski.pyx",
+            "src/pmmoto/analysis/quantimpyc.c",
+            "src/pmmoto/analysis/minkowskic.c",
+        ],
+        include_dirs=["pmmoto/analysis"],
+    ),
+    Extension(
+        "pmmoto.io._data_read",
+        ["src/pmmoto/io/_data_read.pyx"],
+        include_dirs=["src/pmmoto/io"],
+        libraries=["z"],
+        language="c++",
+        extra_compile_args=extra_compile_args,
+    ),
+    Extension(
+        "pmmoto.particles._particles",
+        ["src/pmmoto/particles/_particles.pyx"],
+        include_dirs=["src/pmmoto/particles/"],
+        language="c++",
+        extra_compile_args=extra_compile_args,
+    ),
+    Extension(
+        "pmmoto.domain_generation._rdf",
+        ["src/pmmoto/domain_generation/_rdf.pyx"],
+        include_dirs=["src/pmmoto/domain_generation/", "src/pmmoto/particles/"],
+        language="c++",
+        extra_compile_args=extra_compile_args,
+    ),
+    Extension(
+        "pmmoto.analysis._bins",
+        ["src/pmmoto/analysis/_bins.pyx"],
+        include_dirs=["src/pmmoto/analysis/"],
+        language="c++",
+        extra_compile_args=extra_compile_args,
+    ),
+    Extension(
+        "pmmoto.domain_generation._domain_generation",
+        ["src/pmmoto/domain_generation/_domain_generation.pyx"],
+        include_dirs=["src/pmmoto/domain_generation/", "src/pmmoto/particles/"],
+        language="c++",
+        extra_compile_args=extra_compile_args,
+    ),
+]
+setup(
+    name="pmmoto",
+    ext_modules=cythonize(
+        ext_modules,
+        annotate=True,
+        compiler_directives={"language_level": "3"},
+    ),
+    include_dirs=numpy.get_include(),
+)

pmmoto-0.1.0/src/pmmoto/__init__.py

@@ -0,0 +1,34 @@
+"""PMMoTo package initialization.
+
+This module sets up the logger and imports all major subpackages,
+making core functionality available at the top level.
+
+Exports:
+    - logger: The package-level logger.
+    - initialize: Main initialization function for PMMoTo domains.
+"""
+
+from .core.logging import get_logger
+from .core.pmmoto import initialize
+from .core.boundary_types import BoundaryType
+from . import core
+from . import analysis
+from . import domain_generation
+from . import filters
+from . import io
+from . import particles
+
+# Initialize logger at package level
+logger = get_logger()
+
+__all__ = [
+    "logger",
+    "initialize",
+    "BoundaryType",
+    "core",
+    "analysis",
+    "domain_generation",
+    "filters",
+    "io",
+    "particles",
+]

pmmoto-0.1.0/src/pmmoto/analysis/__init__.py

@@ -0,0 +1,11 @@
+"""Initialize the analysis subpackage for PMMoTo.
+
+Provides statistical, Minkowski, averaging, and binning analysis utilities.
+"""
+
+from . import bins
+from . import minkowski
+from . import stats
+from . import average
+
+__all__ = ["stats", "minkowski", "average", "bins"]