🌊 PyFlowMeld - Multiphase Flow Analysis Toolkit

📋 Project Overview

PyFlowMeld is a comprehensive Python toolkit for analyzing the results of multiphase flow simulations generated by FlowMeld, a physics-based multi-phase, multicomponent solver. PyFlowMeld provides specialized modules for phase flow physics, drying phenomena, and pore network analysis. This package enables powerful post-processing of simulation data with features for visualization, statistical analysis, and network extraction.

🎯 Key Capabilities

• Phase Flow Analysis: Track phase distributions, calculate saturations, and visualize flow patterns.
• Drying Simulation: Analyze evaporation processes and receding contact lines.
• Pore Network Extraction: Extract and analyze pore/throat networks from binary images.
• Velocity Field Analysis: Process and visualize velocity fields in multiphase systems.

✨ Features

🔬 Flow Physics Module (flowphysics.py)

• 📊 Phase saturation tracking over time
• 🖼️ Slice visualization generation
• 📈 Saturation profile calculations
• 🎨 3D phase distribution maps
• 💨 Velocity field visualization (streamlines & quiver plots)

🌡️ Drying Module (drying.py)

• 🔍 Liquid fraction computation
• 📉 Drying rate analysis
• 🗺️ Phase map generation for specific slices
• ⏱️ Time-series processing of evaporation

🕸️ Network Module (network.py)

• 🔗 Pore network extraction via PoreSpy
• 📐 Connectivity analysis
• 📊 Pore size distribution statistics
• 💧 Phase filling fraction calculations
• 📈 Mercury intrusion porosimetry (MIP) curves

🛠️ Installation & Setup

📦 Prerequisites

• Python 3.8 or newer (tested with 3.9)
• Git
• (Optional) Conda, pyenv, or uv for environment management

---

📄 Requirements Files

Before you begin, ensure you have the following files in your repo:

requirements.txt:

numpy>=1.20.0
scipy>=1.7.0
pandas>=1.3.0
matplotlib>=3.4.0
tqdm>=4.62.0
porespy>=2.0.0
openpnm>=3.0.0
natsort>=7.1.0
pytest>=6.2.0
pytest-cov>=2.12.0

environment.yml (for conda):

name: pyflowmeld
channels:
  - defaults
  - conda-forge
dependencies:
  - python=3.9
  - numpy>=1.20.0
  - scipy>=1.7.0
  - pandas>=1.3.0
  - matplotlib>=3.4.0
  - tqdm>=4.62.0
  - porespy>=2.0.0
  - openpnm>=3.0.0
  - natsort>=7.1.0
  - pytest>=6.2.0
  - pytest-cov>=2.12.0
  - pip
  - pip:
      - -e .

---

🐍 Using Conda

# Clone the repository first
git clone https://github.com/yourusername/pyflowmeld.git
cd pyflowmeld

# Create environment from YAML file
conda env create -f environment.yml

# Activate the environment
# On Linux/Mac:
conda activate pyflowmeld
# On Windows (Anaconda Prompt):
activate pyflowmeld

Alternative conda setup using requirements.txt

# Create a new conda environment
conda create -n pyflowmeld python=3.9 -y
# On Linux/Mac:
conda activate pyflowmeld
# On Windows (Anaconda Prompt):
activate pyflowmeld

# Install dependencies from the requirements file
conda install --file requirements.txt -c conda-forge -y

# Install the package in development mode
pip install -e .

---

🔧 Using pyenv

# Clone the repository first
git clone https://github.com/yourusername/pyflowmeld.git
cd pyflowmeld

# Install Python 3.9 using pyenv (you can skip this if already installed)
pyenv install 3.9.16
pyenv local 3.9.16

# Create virtual environment
python -m venv venv

# Activate the virtual environment
# On Linux/Mac:
source venv/bin/activate
# On Windows (CMD or PowerShell):
venv\Scripts\activate

# Install dependencies from requirements.txt
pip install -r requirements.txt

# Install the package in development mode
pip install -e .

---

⚡ Using uv

# Clone the repository first
git clone https://github.com/yourusername/pyflowmeld.git
cd pyflowmeld

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
uv venv

# Activate the virtual environment
# On Linux/Mac:
source .venv/bin/activate
# On Windows (CMD or PowerShell):
.venv\Scripts\activate

# Install dependencies from requirements.txt
uv pip install -r requirements.txt

# Install the package in development mode
uv pip install -e .

---

🐧 Windows & Linux/Mac Activation Reference

• Linux/Mac: source venv/bin/activate or source .venv/bin/activate
• Windows: venv\Scripts\activate or .venv\Scripts\activate
• conda (all OSs): conda activate pyflowmeld or activate pyflowmeld (Anaconda Prompt, Windows)

---

📖 Usage Instructions

🌊 Phase Flow Analysis

from pyflowmeld.postprocess.flowphysics import PhaseFlow

# Initialize phase flow analyzer
phase_flow = PhaseFlow(
    data_path="/path/to/simulation/data",
    domain_size=(100, 100, 100),
    padding=[5, 5, 5, 5, 5, 5],
    rho_f1_stem="f1_rho_",
    rho_f2_stem="f2_rho_"
)

# Run analysis
phase_flow(
    time_range=(0, 50),
    slices={"x": 50, "z": 30},
    phase="invading",
    saturation_profiles=["x", "z"],
    thresh="median"
)

🌡️ Drying Analysis

from pyflowmeld.postprocess.drying import Drying

# Initialize drying analyzer
drying = Drying(
    path_to_data="/path/to/data",
    padding=[0, 0, 0, 0, 0, 0],
    domain_size=[100, 100, 100],
    threshold_tol=0.1
)

# Process drying simulation
drying(
    time_range=[0, 100],
    slices={'x': [25, 50, 75], 'y': 50}
)

🕸️ Pore Network Analysis

from pyflowmeld.postprocess.network import (
    PoreNetworkExtractor, 
    PoreNetworkAnalyzer,
    PhaseDistributionTracker,
    NetworkProperties
)

# Extract network from binary image
extractor = PoreNetworkExtractor()
network_data = extractor.extract(binary_image)

# Analyze network properties
analyzer = PoreNetworkAnalyzer(network_data)
properties = NetworkProperties.from_analyzer(analyzer)
properties.print_summary()

# Track phase distributions
tracker = PhaseDistributionTracker(network_data)
phase_data = tracker.track_phase(rho1, rho2, time_step=10)

💨 Velocity Visualization

from pyflowmeld.postprocess.flowphysics import PhaseVelocities

# Initialize velocity processor
pv = PhaseVelocities(
    path_to_data="/path/to/data",
    domain_size=(100, 100, 100),
    trim=[2, 2, 2, 2, 1, 1]
)

# Create flow visualization
fig, ax = pv.plot_flow(
    plot_type="streamlines",
    phase="f1",
    number=10,
    z_plane=50,
    density=25
)

---

📁 Project Structure

pyflowmeld/
├── postprocess/
│   ├── __init__.py
│   ├── flowphysics.py    # 🌊 Phase flow analysis
│   ├── drying.py         # 🌡️ Drying phenomena
│   └── network.py        # 🕸️ Pore network analysis
├── utils/
│   └── tools.py          # 🔧 Utility functions
├── tests/                # 🧪 Test suite
├── examples/             # 📚 Example scripts
├── requirements.txt      # 📦 Dependencies (pip)
├── environment.yml       # 📦 Dependencies (conda)
├── setup.py              # 🔧 Package setup
└── README.md             # 📖 This file

---

🔄 Updating Dependencies

Using pip

# Activate your environment first (see above)
pip install --upgrade -r requirements.txt

Using conda

# Update all packages in the environment
conda update --all -y

# Or update specific package
conda update numpy scipy -y

Using uv

uv pip install --upgrade -r requirements.txt

---

🧪 Running Tests

# Run all tests
python -m pytest tests/

# Run specific test module
python -m pytest tests/test_flowphysics.py

# Run with coverage
python -m pytest --cov=pyflowmeld tests/

On Windows, make sure to activate your environment as shown above before running these commands.

---

🚀 Quick Start Guide

# 1. Clone the repository
git clone https://github.com/yourusername/pyflowmeld.git
cd pyflowmeld

# 2. Create and activate environment (choose one method)

# Using conda:
conda env create -f environment.yml
# On Linux/Mac:
conda activate pyflowmeld
# On Windows (Anaconda Prompt):
activate pyflowmeld

# OR using pip:
python -m venv venv
# On Linux/Mac:
source venv/bin/activate
# On Windows (CMD or PowerShell):
venv\Scripts\activate
pip install -r requirements.txt
pip install -e .

# 3. Verify installation
python -c "import pyflowmeld; print('PyFlowMeld installed successfully!')"

# 4. Run example (if available)
python examples/basic_analysis.py

---

🤝 Contributing

We welcome contributions! Please follow these steps:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/AmazingFeature)
3. 💾 Commit your changes (git commit -m 'Add some AmazingFeature')
4. 📤 Push to the branch (git push origin feature/AmazingFeature)
5. 🔄 Open a Pull Request

📝 Code Style

• Follow PEP 8 guidelines
• Add type hints where applicable
• Include docstrings for all functions and classes
• Write unit tests for new features

---

📄 License

Copyright 2025. Corning Incorporated. All rights reserved.

This software may only be used in accordance with the identified license(s).
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.

---

🙏 Acknowledgements

👥 Authors

• Hamed Haddadi — Staff Scientist (haddadigh@corning.com)
• David Heine — Principal Scientist and Manager (heinedr@corning.com)

🔗 Dependencies

Special thanks to:

• PoreSpy — Pore network extraction
• OpenPNM — Pore network modeling
• NumPy — Numerical computing
• Matplotlib — Visualization

🎓 References

If you use PyFlowMeld in your research, please cite:

@software{pyflowmeld2025,
  title = {PyFlowMeld: A Python Toolkit for Multiphase Flow Analysis},
  author = {Haddadi, Hamed and Heine, David},
  year = {2025},
  organization = {Corning Incorporated}
}

---

Made with ❤️ by the Corning Incorporated Science and Technology Organization