PhySimLab - Physics Simulation Laboratory

physimlab is a comprehensive physics simulation package for ball drop experiments with advanced aerodynamics, Magnus effect, and ground interaction physics.

🚀 Features

📊 Advanced Physics

• Aerodynamics: Multi-regime drag coefficient, Reynolds number, Mach number calculations
• Magnus Effect: Spin-induced lift forces with advanced correlations
• Thermodynamics: Temperature and humidity effects on air properties (ISA model)
• Ground Physics: Hertzian contact mechanics, advanced friction modeling, surface geometry
• Wind Effects: Power law wind profiles, gust modeling, atmospheric turbulence
• Virtual Mass: Added mass effects for realistic acceleration behavior
• Compressibility: High-speed flow corrections

🎯 Multiple Scenarios

• Ball Drop: Standard drop simulation with advanced bounce physics
• Wind Tunnel: Aerodynamics testing with controlled airflow and turbulence
• Terminal Velocity: Free fall with complete drag force analysis
• Projectile Motion: Trajectory simulation with full aerodynamic effects
• Spin Analysis: Rotational dynamics with advanced decay modeling

📈 Rich Output

• CSV Data: Full trajectory data with all physics parameters
• Interactive HTML: Plotly-powered reports with 3D visualization
• Animated GIFs: Real-time trajectory animations
• High-Quality Plots: Publication-ready static plots
• JSON Summary: Machine-readable results and configuration
• Detailed Statistics: Energy conservation, stability analysis, timestep monitoring

🔧 Advanced Numerical Methods

• Adaptive Integration: RK45 Dormand-Prince with error control
• Fixed-Step Euler: For comparison and simple cases
• Stability Monitoring: Energy-based stability checks
• Adaptive Timestep: Automatic step size control

🐍 Python Library

import physimlab

# Simple usage with configuration file
result = physimlab.run_simulation(config_path="config.json")
print(f"Flight time: {result['summary']['flight_time']:.2f} s")

# Advanced usage with configuration
result = physimlab.run_simulation(
    config_path="config.json",
    output_dir="./results"
)

# Batch simulations with parameter sweep
results = physimlab.batch_simulation(
    config_path="config.json",
    parameters=[
        {"name": "mass", "min": 0.1, "max": 1.0, "steps": 5},
        {"name": "radius", "min": 0.05, "max": 0.2, "steps": 3}
    ]
)

# Compare results
comparison = physimlab.compare_results(
    "./result1", 
    "./result2"
)

# Access detailed results
summary = result['summary']
data = result['data']
config = result['config']
detailed_stats = result.get('detailed_stats', {})

print(f"Flight time: {summary['flight_time']:.3f} seconds")
print(f"Max height: {summary['max_height']:.2f} meters")
print(f"Horizontal range: {summary['horizontal_range']:.2f} meters")
print(f"Max Reynolds number: {detailed_stats.get('max_reynolds', 0):.2e}")
print(f"Energy conserved: {detailed_stats.get('energy_conserved', True)}")

# Save outputs
output_files = result['output_files']
print(f"CSV data: {output_files['data']}")
print(f"HTML report: {output_files['html']}")

🖥️ Command Line Interface

# Basic usage (configuration file required)
$ physimlab run --config config.json
$ physimlab run --config config.yaml

# Advanced usage
$ physimlab run --config config.json --output ./results
$ physimlab batch --config config.json --param mass 0.1 0.5 5
$ physimlab compare ./result1 ./result2

# Information and management
$ physimlab list
$ physimlab info drop
$ physimlab version
$ physimlab init my_project --scenario drop

# Enhanced output options
$ physimlab run --config config.json --quiet          # Minimal output
$ physimlab run --config config.json --verbose        # Detailed output

📦 Installation

PyPI (Recommended)

pip install physimlab

Development Version

pip install git+https://github.com/rehanguha/physimlab.git

From Source

git clone https://github.com/rehanguha/physimlab.git
cd physimlab
pip install -e .

🎮 Quick Start

1. Basic Simulation

# Run with configuration file (required)
physimlab run --config config.json

# Run with custom configuration
physimlab run --config my_config.json --output ./results

2. Python API

import physimlab

# Run simulation with configuration
result = physimlab.run_simulation(config_path="config.json")

# Access results
summary = result['summary']
print(f"Flight time: {summary['flight_time']:.3f} seconds")
print(f"Max height: {summary['max_height']:.2f} meters")
print(f"Horizontal range: {summary['horizontal_range']:.2f} meters")

# Get output files
output_files = result['output_files']
print(f"Data saved to: {output_files['data']}")

3. Configuration File

Create a config.json file:

{
  "scenario": "drop",
  "object": {
    "type": "sphere",
    "mass": 0.5,
    "radius": 0.1,
    "spin_rate": 8.0
  },
  "initial_height": 100,
  "environment": {
    "gravity": 9.81,
    "temperature": 288.15,
    "humidity": 0.5
  },
  "simulation": {
    "time_step": 0.001,
    "max_time": 30.0,
    "tolerance": 1e-6
  }
}

📋 CLI Reference

physimlab run

Run a ball drop simulation with specified configuration.

physimlab run --config CONFIG [OPTIONS]

Required:

• --config, -c: Configuration file path (JSON or YAML)

Options:

• --output, -o: Output directory (auto-generated if not specified)
• --quiet, -q: Minimal output
• --verbose, -v: Verbose output

Note: Configuration file is required. Individual parameters (height, mass, radius, spin) are no longer supported - use configuration files instead.

physimlab batch

Run batch simulations with parameter sweep.

physimlab batch --config CONFIG --param PARAM [PARAM ...]

Required:

• --config: Base configuration file
• --param, -p: Parameter to vary: name min max steps

Example:

physimlab batch --config config.json --param mass 0.1 0.5 5

physimlab compare

Compare two simulation results.

physimlab compare RESULT1 RESULT2

Arguments:

• RESULT1: First result directory
• RESULT2: Second result directory

physimlab list

List available scenarios.

physimlab list

Available scenarios:

• drop: Ball drop simulation with aerodynamics
• wind-tunnel: Wind tunnel aerodynamics test
• terminal-velocity: Terminal velocity measurement
• projectile: Projectile motion with drag

physimlab info

Show information about a scenario.

physimlab info [SCENARIO]

Arguments:

• SCENARIO: Scenario to show information for (default: drop)

physimlab version

Show version information.

physimlab version

physimlab init

Initialize a new physimlab project.

physimlab init NAME --output DIR --scenario SCENARIO

Arguments:

• NAME: Project name

Options:

• --output, -o: Output directory (default: current directory)
• --scenario, -s: Default scenario (default: drop)

🔬 Physics Models

Aerodynamics

• Air Density: Ideal gas law with humidity effects
• Viscosity: Sutherland's formula for temperature dependence
• Speed of Sound: Temperature-dependent calculation
• Reynolds Number: Flow regime characterization
• Drag Coefficient: Reynolds number-dependent model
• Magnus Force: Spin-induced lift calculation

Mechanics

• Gravity: Altitude-dependent gravitational acceleration
• Terminal Velocity: Drag vs. gravity equilibrium
• Spin Decay: Air resistance effects on rotation

Environment

• Temperature Effects: On air density, viscosity, and speed of sound
• Humidity Effects: On air density calculations
• Wind Effects: Crosswind and relative velocity calculations

📊 Output Formats

CSV Data

Full trajectory data with all calculated physics parameters:

Time,X,Y,Z,Vx,Vy,Vz,Speed,OmegaZ,AirDensity,Reynolds,Cd,Mach
0.000,0.035,0.000,100.035,7.071,0.001,7.022,9.965,50.206,1.209,234928,0.160,0.026
...

JSON Summary

Machine-readable summary and configuration:

{
  "summary": {
    "flight_time": 19.995,
    "max_height": 102.56,
    "horizontal_range": 45.77,
    "max_velocity": 42.90,
    "ground_contacts": 6,
    "max_mach": 0.126,
    "is_stable": true,
    "energy_conserved": true
  },
  "config": { ... },
  "timestamp": "2026-02-24T16:51:32"
}

HTML Report

Interactive Plotly report with rich formatting:

• 2D and 3D trajectory plots
• Velocity and height over time
• Physics parameter visualization
• Summary statistics with enhanced formatting
• Rich terminal output display

Static Plots

High-quality matplotlib plots:

• Trajectory visualization
• Velocity components over time
• Physics parameters analysis
• Publication-ready formatting

Output Files Structure

When running simulations, outputs are organized as:

outputs/
├── data.csv              # Full trajectory data
├── summary.json          # Results summary
├── report.html           # Interactive HTML report
├── plots/                # Static matplotlib plots
│   ├── trajectory.png
│   ├── velocity.png
│   └── physics.png
└── animation.gif         # Trajectory animation

🏗️ Package Structure

physimlab/
├── __init__.py         # Package entry point
├── cli.py              # Typer CLI interface with rich formatting
├── core.py             # Main simulation engine and API functions
├── config/             # Configuration handling
│   ├── __init__.py
│   └── loader.py       # JSON/YAML loading and validation
├── objects/            # Physical object definitions
│   └── __init__.py
├── output/             # Output management and reporting
│   ├── __init__.py
│   ├── manager.py      # File saving and organization
│   └── result.py       # Result object with plotting capabilities
├── physics/            # Physics calculations
│   ├── __init__.py
│   ├── aerodynamics.py # Drag, lift, air properties, Magnus effect
│   └── mechanics.py    # Gravity, motion, collisions, spin decay
├── scenarios/          # Predefined simulation scenarios
│   └── __init__.py
└── utils/              # Utilities and constants
    ├── __init__.py
    ├── constants.py    # Physical constants
    └── helpers.py      # Formatting and utility functions

🧪 Testing

Run the test suite:

pip install physimlab[dev]
pytest

Run with coverage:

pytest --cov=physimlab --cov-report=html

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

📄 License

physimlab is licensed under the Apache License 2.0.

Copyright 2026 Rehan Guha

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

🙏 Acknowledgments

• NumPy: Numerical computations
• Pandas: Data handling and CSV export
• Matplotlib: Static plotting
• Plotly: Interactive visualization
• Typer: CLI interface
• Rich: Beautiful terminal output

📞 Support

For questions, bug reports, or feature requests:

• GitHub Issues: https://github.com/rehanguha/physimlab/issues
• Documentation: GitHub README

🏷️ Keywords

physics simulation, aerodynamics, ball drop, Magnus effect, terminal velocity, projectile motion, scientific computing, Python package, CLI tool, data visualization