physimlab is a comprehensive physics simulation package for ball drop experiments with advanced aerodynamics, Magnus effect, and ground interaction 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

• 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

• 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

• 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

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']}")

# 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

pip install physimlab

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

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

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

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

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']}")

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
  }
}

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.

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

Compare two simulation results.

physimlab compare RESULT1 RESULT2

Arguments:

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

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

Show information about a scenario.

physimlab info [SCENARIO]

Arguments:

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

Show version information.

physimlab version

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)

• 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

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

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

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
...

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"
}

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

High-quality matplotlib plots:

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

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

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

Run the test suite:

pip install physimlab[dev]
pytest

Run with coverage:

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

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

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.

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

For questions, bug reports, or feature requests:

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

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