optikal-physics-suite 1.0.1
Comprehensive physics simulation framework for FSO optical communications, atmospheric propagation, and space environment modeling
License: MIT
Requires Python: >=3.10
Keywords: atmospheric-optics, beam-propagation, free-space-optical, fso, gaussian-beam, optical-communications, orbital-mechanics, physics-simulation, space-environment, vcsel

# Optikal Physics Suite

[![PyPI version](https://badge.fury.io/py/optikal-physics-suite.svg)](https://badge.fury.io/py/optikal-physics-suite)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Comprehensive physics simulation framework for Free-Space Optical (FSO) communications, atmospheric propagation, and space environment modeling.

## Features

- **Gaussian Beam Propagation**: TEM00 beam modeling with divergence, Rayleigh range, and intensity calculations
- **Atmospheric Attenuation**: Fog categories (clear to dense), visibility mapping, ITU-R P.1814 compliance
- **Space Environment**: LEO/MEO/GEO/HEO orbital mechanics, radiation effects, vacuum propagation
- **ML Weather Prediction**: LSTM-based weather forecasting with NOAA and Visual Crossing data sources
- **GPU Acceleration**: Optional PyTorch support for beam propagation

## Installation

```bash
# Core package (beam propagation + space environment)
pip install optikal-physics-suite

# With ML weather prediction
pip install optikal-physics-suite[ml]

# With GPU acceleration
pip install optikal-physics-suite[gpu]

# Full installation
pip install optikal-physics-suite[all]
```

## Quick Start

### Gaussian Beam Propagation

```python
from optikal_physics_suite import GaussianBeam, BeamPropagator

# Create an 850nm VCSEL beam (Class 1 safe)
beam = GaussianBeam(wavelength=850, power=0.39, waist=1.0)

# Calculate beam parameters
print(f"Divergence: {beam.calculate_divergence():.2f} mrad")
print(f"Rayleigh range: {beam.calculate_rayleigh_range():.1f} m")
print(f"Radius at 100m: {beam.radius_at_distance(100):.1f} mm")
print(f"Class 1 safe: {beam.is_class1_safe()}")

# Propagate beam
propagator = BeamPropagator()
result = propagator.propagate_beam(beam, distance=100)
print(f"Peak intensity at 100m: {result['peak_intensity_Wm2']:.2f} W/m^2")
```

### Atmospheric Attenuation

```python
from optikal_physics_suite import FogCategory, ATTENUATION_DB_PER_KM, VISIBILITY_KM

# Get attenuation for different fog conditions
for category in FogCategory:
    attenuation = ATTENUATION_DB_PER_KM[category]
    visibility = VISIBILITY_KM[category]
    print(f"{category.value}: {attenuation:.1f} dB/km, visibility {visibility:.1f} km")
```

### Space Environment

```python
from optikal_physics_suite import SpaceEnvironment, OrbitType

# Create LEO space environment
space = SpaceEnvironment(orbit_type=OrbitType.LEO)

# Calculate link budget
link_budget = space.calculate_link_budget(
    distance_km=400,
    tx_power_dbm=20,
    wavelength_nm=1550,
    aperture_diameter_m=0.1
)
print(f"Received power: {link_budget['received_power_dbm']:.1f} dBm")
print(f"Free-space loss: {link_budget['free_space_loss_db']:.1f} dB")
```

## Modules

| Module | Description |
|--------|-------------|
| `optical.beam_propagation` | Gaussian beam propagation and intensity calculations |
| `optical.atmospheric_constants` | Fog categories, attenuation coefficients |
| `orbital.space_environment` | Space environment modeling, radiation, thermal effects |
| `ml_weather` | LSTM weather prediction, multi-source data collection |

## Physics References

- Saleh & Teich, "Fundamentals of Photonics" (2007)
- IEC 60825-1: Safety of laser products
- ITU-R P.1814: Free-space optical link prediction
- Kim et al., "Comparison of laser beam propagation" (2001)

## License

MIT License - see [LICENSE](LICENSE) for details.

## Author

Daniel Garza - Netrun Systems
https://www.netrunsystems.com