pycphy 0.2.0

Python: Computational Physics - Tools for physics dynamics simulation with CAD-based OpenFOAM case generation

pycphy

Python: Computational Physics

A comprehensive Python package for computational physics simulations and tools, with a focus on OpenFOAM case development and management.

Author: Sanjeev Bashyal
Repository: https://github.com/SanjeevBashyal/pycphy

Overview

pycphy is a Python package designed to provide tools and utilities for computational physics simulations. The package currently includes the foamCaseDeveloper module, which offers comprehensive tools for creating and managing OpenFOAM CFD simulation cases.

Features

foamCaseDeveloper Module

The foamCaseDeveloper module provides:

• BlockMesh Generation: Create OpenFOAM blockMeshDict files with custom geometries
• CAD-based Mesh Generation: Generate blockMeshDict directly from AutoCAD CAD files with XData annotations
• Control Dictionary Setup: Configure solver settings, time control, and output parameters
• Turbulence Model Configuration: Set up RAS, LES, and laminar turbulence models
• Zero Field Generation: Create initial field files (p, U, f, lambda) with CSV-based boundary conditions
• Complete Case Management: Automatically create complete OpenFOAM case directories
• Validation and Error Checking: Built-in validation for all configuration parameters

Installation

From Source

git clone https://github.com/SanjeevBashyal/pycphy.git
cd pycphy
pip install -e .

With CAD Support (Recommended)

git clone https://github.com/SanjeevBashyal/pycphy.git
cd pycphy
pip install -e ".[cad]"

Development Installation

git clone https://github.com/SanjeevBashyal/pycphy.git
cd pycphy
pip install -e ".[dev]"

Full Installation (All Features)

git clone https://github.com/SanjeevBashyal/pycphy.git
cd pycphy
pip install -e ".[all]"

Quick Start

Using the Command Line Interface

# Create an example case (traditional CLI)
pycphy-foam --example

# Create a custom case from configuration files (traditional CLI)
pycphy-foam --case myCase --geometry configBlockMesh.py --control configControl.py --turbulence configTurbulence.py

# Create a case with CAD-based mesh generation (default behavior)
python pycphy/foamCaseDeveloper/develop_case.py
# OR after installation:
pycphy-develop

# Create a case with traditional config-based generation
python pycphy/foamCaseDeveloper/develop_case.py --config-mode
# OR after installation:
pycphy-develop --config-mode

# Create a case with CAD-based mesh generation and debug output
python pycphy/foamCaseDeveloper/develop_case.py --cad-debug --cad-tolerance 1e-6
# OR after installation:
pycphy-develop --cad-debug --cad-tolerance 1e-6

Using Python API

from pycphy.foamCaseDeveloper import FoamCaseManager, BlockMeshConfig, ControlConfig, TurbulenceConfig

# Create a case manager
case_manager = FoamCaseManager("myCase")

# Set up geometry
geometry_config = BlockMeshConfig(
    p0=(0.0, 0.0, 0.0),
    p1=(1.0, 1.0, 1.0),
    cells=(50, 50, 50),
    patch_names={
        'minX': 'inlet',
        'maxX': 'outlet',
        'minY': 'frontWall',
        'maxY': 'backWall',
        'minZ': 'floor',
        'maxZ': 'ceiling'
    }
)

case_manager.setup_geometry(
    p0=geometry_config.p0,
    p1=geometry_config.p1,
    cells=geometry_config.cells,
    patch_names=geometry_config.patch_names
)

# Set up control
control_config = ControlConfig()
control_config.set_solver("interFoam")
control_config.set_time_control(start_time=0, end_time=1.0, delta_t=0.001)

case_manager.setup_control(control_config.get_parameters())

# Set up turbulence
turbulence_config = TurbulenceConfig("RAS")
turbulence_config.set_ras_model("kOmegaSST")

case_manager.setup_turbulence(
    simulation_type=turbulence_config.get_simulation_type(),
    model_properties=turbulence_config.get_model_properties()
)

# Create the complete case
case_manager.create_full_case()

CAD-based Mesh Generation

from pycphy.foamCaseDeveloper import CADBlockMeshDeveloper, cad_mesh_config

# Create CAD-based mesh developer
cad_developer = CADBlockMeshDeveloper(
    blocks_csv_file="Inputs/blocks.csv",
    patches_csv_file="Inputs/patches.csv",
    tolerance=1e-6,
    block_xdata_app_name="BLOCKDATA",
    region_xdata_app_name="REGIONDATA"
)

# Process CAD file and generate complete OpenFOAM case
success = cad_developer.process_cad_file(
    output_path="system/blockMeshDict",
    debug=True
)

if success:
    summary = cad_developer.get_summary()
    print(f"Generated mesh with {summary['total_blocks']} blocks and {summary['total_patches']} patches")
    print("Zero field files created with CSV boundary conditions")

Package Structure

pycphy/
├── __init__.py
└── foamCaseDeveloper/
    ├── __init__.py
    ├── main.py                    # Command-line interface
    ├── core/                      # Core functionality
    │   ├── __init__.py
    │   ├── foam_case_manager.py   # Main case management class
    │   ├── block_mesh_developer.py # BlockMesh generation
    │   ├── control_dict_writer.py  # Control dictionary writer
    │   └── turbulence_properties_writer.py # Turbulence properties writer
    ├── writers/                   # OpenFOAM dictionary writers
    │   ├── __init__.py
    │   ├── foam_writer.py         # Base writer class
    │   ├── block_mesh_writer.py   # BlockMesh dictionary writer
    │   ├── control_dict_writer.py # Control dictionary writer
    │   └── turbulence_properties_writer.py # Turbulence properties writer
    └── config/                    # Configuration classes
        ├── __init__.py
        ├── block_mesh_config.py   # Geometry configuration
        ├── control_config.py      # Control configuration
        └── turbulence_config.py   # Turbulence configuration

Configuration

Geometry Configuration (BlockMesh)

from pycphy.foamCaseDeveloper import BlockMeshConfig

config = BlockMeshConfig(
    p0=(0.0, 0.0, 0.0),      # Minimum corner
    p1=(1.0, 1.0, 1.0),      # Maximum corner
    cells=(50, 50, 50),      # Number of cells
    patch_names={            # Boundary patch names
        'minX': 'inlet',
        'maxX': 'outlet',
        'minY': 'frontWall',
        'maxY': 'backWall',
        'minZ': 'floor',
        'maxZ': 'ceiling'
    }
)

Control Configuration

from pycphy.foamCaseDeveloper import ControlConfig

config = ControlConfig()
config.set_solver("interFoam")
config.set_time_control(start_time=0, end_time=1.0, delta_t=0.001)
config.set_write_control(write_interval=0.05)
config.set_courant_control(max_co=1)

Turbulence Configuration

from pycphy.foamCaseDeveloper import TurbulenceConfig

# RAS configuration
ras_config = TurbulenceConfig("RAS")
ras_config.set_ras_model("kOmegaSST")

# LES configuration
les_config = TurbulenceConfig("LES")
les_config.set_les_model("kEqn")
les_config.set_delta_model("smooth")

# Laminar configuration
laminar_config = TurbulenceConfig("laminar")

Examples

Channel Flow Case

from pycphy.foamCaseDeveloper import FoamCaseManager, BlockMeshConfig, ControlConfig, TurbulenceConfig

# Create channel flow case
case_manager = FoamCaseManager("channelFlow")

# Channel geometry: 0.5m x 0.2m x 0.1m
geometry = BlockMeshConfig(
    p0=(0.0, 0.0, 0.0),
    p1=(0.5, 0.2, 0.1),
    cells=(50, 20, 50),
    patch_names={
        'minX': 'inlet',
        'maxX': 'outlet',
        'minY': 'frontWall',
        'maxY': 'backWall',
        'minZ': 'floor',
        'maxZ': 'ceiling'
    }
)

case_manager.setup_geometry(
    p0=geometry.p0, p1=geometry.p1, cells=geometry.cells,
    patch_names=geometry.patch_names
)

# Set up solver
control = ControlConfig()
control.set_solver("interFoam")
control.set_time_control(start_time=0, end_time=1.0, delta_t=0.001)

case_manager.setup_control(control.get_parameters())

# Set up turbulence
turbulence = TurbulenceConfig("RAS")
turbulence.set_ras_model("kOmegaSST")

case_manager.setup_turbulence(
    simulation_type=turbulence.get_simulation_type(),
    model_properties=turbulence.get_model_properties()
)

# Create the case
case_manager.create_full_case()

Requirements

Basic Requirements

• Python >= 3.7
• NumPy >= 1.19.0
• SciPy >= 1.6.0
• Matplotlib >= 3.3.0

CAD-based Generation Requirements

• AutoCAD (with COM automation support)
• Windows operating system (for AutoCAD COM interface)
• pyautocad >= 0.2.0
• win32com (included with pywin32)

CAD Setup for Mesh Generation

To use CAD-based mesh generation:

1. Prepare your CAD file:

   • Create 3DSOLID entities for mesh blocks
   • Create REGION entities for boundary patches
   • Add XData to entities with block/patch information

2. Create CSV configuration files:

   • blocks.csv: Define block parameters (ID, cells, grading, etc.)
   • patches.csv: Define boundary conditions for each patch

3. XData Format:

   • Blocks: Use "BLOCKDATA" app with block ID and description
   • Regions: Use "REGIONDATA" app with region name

4. Run the generation:

   # CAD-based case generation with all OpenFOAM files (default)
   python pycphy/foamCaseDeveloper/develop_case.py
   # OR after installation:
   pycphy-develop
   
   # Traditional config-based case generation
   python pycphy/foamCaseDeveloper/develop_case.py --config-mode
   # OR after installation:
   pycphy-develop --config-mode
   

Integrated Workflow

The develop_case.py script now supports both traditional config-based and CAD-based OpenFOAM case generation:

CAD-based Generation

• Mesh: Generated directly from AutoCAD CAD files using XData annotations
• Zero fields: Created with boundary conditions from CSV files
• Other files: Generated from configuration files (control, turbulence, etc.)

Traditional Generation

• Mesh: Generated from geometry configuration files
• Zero fields: Generated from configuration files with hardcoded boundary conditions
• Other files: Generated from configuration files

Command Line Options

# Basic usage (CAD-based generation is now default)
python pycphy/foamCaseDeveloper/develop_case.py
# OR after installation:
pycphy-develop

# Traditional config-based generation
python pycphy/foamCaseDeveloper/develop_case.py --config-mode
# OR after installation:
pycphy-develop --config-mode

# CAD-based with custom CSV files
python pycphy/foamCaseDeveloper/develop_case.py --blocks-csv my_blocks.csv --patches-csv my_patches.csv
# OR after installation:
pycphy-develop --blocks-csv my_blocks.csv --patches-csv my_patches.csv

# CAD-based with debug output
python pycphy/foamCaseDeveloper/develop_case.py --cad-debug
# OR after installation:
pycphy-develop --cad-debug

# CAD-based with custom tolerance and XData app names
python pycphy/foamCaseDeveloper/develop_case.py --cad-tolerance 1e-5 --block-xdata-app MYBLOCKDATA --region-xdata-app MYREGIONDATA
# OR after installation:
pycphy-develop --cad-tolerance 1e-5 --block-xdata-app MYBLOCKDATA --region-xdata-app MYREGIONDATA

Development

Running Tests

pytest

Code Formatting

black pycphy/
flake8 pycphy/

Building Documentation

sphinx-build docs/ docs/_build/

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-feature)
3. Commit your changes (git commit -am 'Add new feature')
4. Push to the branch (git push origin feature/new-feature)
5. Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use pycphy in your research, please cite:

@software{bashyal2025pycphy,
  title={pycphy: Python Computational Physics},
  author={Bashyal, Sanjeev},
  year={2025},
  url={https://github.com/SanjeevBashyal/pycphy}
}

Support

For questions, issues, or contributions, please visit the GitHub repository.