lsurf 1.0.0__tar.gz

lsurf-1.0.0/.gitlab/ci-setup.md

@@ -0,0 +1,95 @@
+# GitLab CI Setup
+
+## Overview
+
+This repository uses GitLab CI/CD for automated testing, building, and deployment.
+
+## Pipeline Stages
+
+### 1. Check Stage
+- **check:pre-commit**: Runs all pre-commit hooks to ensure code quality
+  - Code formatting (Black)
+  - Linting (Ruff)
+  - File checks (trailing whitespace, EOF, merge conflicts, etc.)
+
+### 2. Test Stage
+- **test:py313**: Main test suite on Python 3.13
+  - Runs full test suite with pytest
+  - Generates coverage reports
+  - Creates JUnit XML for GitLab integration
+- **test:py314**: Test suite on Python 3.14-rc (allow_failure: true)
+  - Early testing for upcoming Python version
+
+### 3. Build Stage
+- **build:package**: Builds distribution packages
+  - Only runs on `main` branch and tags
+  - Creates wheel and source distribution
+  - Validates with twine
+  - Artifacts stored for 1 week
+
+### 4. Deploy Stage
+- **pages**: Builds and deploys Sphinx documentation
+  - Only runs on `main` branch and tags
+  - Generates HTML documentation
+  - Deploys to GitLab Pages
+- **deploy:pypi**: Deploys to PyPI
+  - Only runs on tags
+  - Uses `PYPI_TOKEN` secret variable
+  - Uploads built packages from build stage
+
+## Required Variables
+
+Set these in GitLab CI/CD Settings → Variables:
+
+- `PYPI_TOKEN`: PyPI API token for package deployment
+  - Type: Variable
+  - Protected: Yes
+  - Masked: Yes
+
+## Local Testing
+
+Test the pipeline locally before pushing:
+
+```bash
+# Install dependencies
+pip install -e ".[dev,test]"
+
+# Run pre-commit checks
+pre-commit run --all-files
+
+# Run tests
+pytest -v tests/
+
+# Build package
+python -m build
+python -m twine check dist/*
+
+# Build documentation
+sphinx-build -b html docs public
+```
+
+## Python Version Support
+
+- **Minimum**: Python 3.13
+- **Tested**: Python 3.13, 3.14-rc
+- **Recommended**: Python 3.13
+
+## Cache Configuration
+
+The pipeline caches pip packages to speed up builds:
+- Cache directory: `$CI_PROJECT_DIR/.cache/pip`
+- Separate cache for pre-commit hooks
+
+## Coverage Reports
+
+Coverage reports are:
+- Displayed in pipeline output
+- Stored as HTML artifacts (1 week)
+- Integrated with GitLab's coverage visualization
+
+## Artifacts
+
+Build artifacts are stored for:
+- Test reports: 1 week
+- Built packages: 1 week
+- Documentation: 1 week

lsurf-1.0.0/.gitlab-ci.yml

@@ -0,0 +1,127 @@
+image: python:3.14
+
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+
+cache:
+  paths:
+    - .cache/pip
+
+stages:
+  - check
+  - test
+  - build
+  - deploy
+
+# =============================================================================
+# Pre-commit checks
+# =============================================================================
+
+check:pre-commit:
+  stage: check
+  allow_failure: false
+  before_script:
+    - pip install pre-commit
+  script:
+    - pre-commit run --all-files --verbose --show-diff-on-failure
+  cache:
+    key: pre-commit
+    paths:
+      - ~/.cache/pre-commit
+
+# =============================================================================
+# Tests
+# =============================================================================
+
+test:py314:
+  stage: test
+  image: python:3.14
+  before_script:
+    - pip install -e ".[test]"
+  script:
+    # Run non-slow tests only (~5 min) - use `pytest` for full suite
+    - pytest -v -m "not slow" tests/
+  coverage: '/(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/'
+  artifacts:
+    when: always
+    reports:
+      junit: junit.xml
+    paths:
+      - htmlcov/
+    expire_in: 1 week
+
+# =============================================================================
+# Build
+# =============================================================================
+
+build:package:
+  stage: build
+  only:
+    - tags
+    - master
+  before_script:
+    - pip install build twine
+  script:
+    - python -m build
+    - python -m twine check dist/*
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 1 week
+
+# =============================================================================
+# Documentation
+# =============================================================================
+
+pages:
+  stage: deploy
+  only:
+    - master
+    - tags
+  before_script:
+    - pip install -e ".[dev]"
+    - pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehints
+  script:
+    - sphinx-build -b html docs public
+  artifacts:
+    paths:
+      - public
+    expire_in: 1 week
+
+# =============================================================================
+# Publish to TestPyPI (manual trigger)
+# =============================================================================
+
+publish:testpypi:
+  stage: deploy
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v.*/
+      when: manual
+  dependencies:
+    - build:package
+  before_script:
+    - pip install twine
+  script:
+    - python -m twine upload --repository testpypi dist/*
+  variables:
+    TWINE_USERNAME: __token__
+    TWINE_PASSWORD: $TESTPYPI_TOKEN
+
+# =============================================================================
+# Publish to PyPI (manual trigger)
+# =============================================================================
+
+publish:pypi:
+  stage: deploy
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v.*/
+      when: manual
+  dependencies:
+    - build:package
+  before_script:
+    - pip install twine
+  script:
+    - python -m twine upload dist/*
+  variables:
+    TWINE_USERNAME: __token__
+    TWINE_PASSWORD: $PYPI_TOKEN

lsurf-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

lsurf-1.0.0/.ruff.toml

@@ -0,0 +1,11 @@
+# Ruff configuration
+[lint.per-file-ignores]
+"__init__.py" = [
+    "E402",
+    "F401",
+] # Allow module-level imports not at top, unused imports
+"tests/*.py" = ["E722"] # Allow bare except in tests for CUDA checks
+"scripts/*.py" = [
+    "E402",
+    "F841",
+] # Allow imports after code, unused variables in scripts

lsurf-1.0.0/LICENSE

@@ -0,0 +1,32 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.

lsurf-1.0.0/MANIFEST.in

@@ -0,0 +1,37 @@
+# Include documentation
+include README.md
+include LICENSE
+include CHANGELOG.md
+
+# Include package data
+include src/surface_reflections/py.typed
+
+# Include configuration files
+include pyproject.toml
+include setup.cfg
+include environment.yml
+
+# Include conda recipe
+recursive-include conda-recipe *
+
+# Exclude development files
+exclude .gitignore
+exclude .pre-commit-config.yaml
+
+# Exclude test cache
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude .pytest_cache
+global-exclude .mypy_cache
+global-exclude .ruff_cache
+
+# Exclude data and plots directories
+prune data
+prune plots
+prune old
+prune info
+prune docs
+
+# Exclude large binary files
+global-exclude numba
+global-exclude sys

lsurf-1.0.0/PKG-INFO

@@ -0,0 +1,381 @@
+Metadata-Version: 2.4
+Name: lsurf
+Version: 1.0.0
+Summary: L-SURF: GPU-accelerated physically-accurate raytracing framework for simulating light-surface interactions
+Author: Tobias Heibges
+Maintainer: Tobias Heibges
+License: BSD-3-Clause-Clear
+Project-URL: Homepage, https://github.com/tobi-h/lsurf
+Project-URL: Documentation, https://github.com/tobi-h/lsurf#readme
+Project-URL: Repository, https://github.com/tobi-h/lsurf.git
+Project-URL: Issues, https://github.com/tobi-h/lsurf/issues
+Keywords: raytracing,gpu,cuda,numba,optics,fresnel,reflection,refraction,waves,ocean,simulation,physics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: numba>=0.58.0
+Requires-Dist: h5py>=3.8.0
+Requires-Dist: astropy-healpix>=1.0.0
+Requires-Dist: matplotlib-label-lines>=0.7.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: tomli>=2.0.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: dearpygui>=2.0.0
+Requires-Dist: pytest>=7.0.0
+Requires-Dist: pytest-cov>=4.0.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: black>=23.0.0
+Requires-Dist: ruff>=0.1.0
+Requires-Dist: mypy>=1.0.0
+Requires-Dist: pre-commit>=3.0.0
+Requires-Dist: build>=1.0.0
+Requires-Dist: twine>=4.0.0
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.24.0; extra == "docs"
+Dynamic: license-file
+
+# L-SURF
+
+<p align="center">
+  <img src="lsurf_logo.jpg" alt="L-SURF Logo" width="400">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/lsurf/"><img src="https://badge.fury.io/py/lsurf.svg" alt="PyPI version"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.13+-blue.svg" alt="Python 3.13+"></a>
+  <a href="https://spdx.org/licenses/BSD-3-Clause-Clear.html"><img src="https://img.shields.io/badge/License-BSD--3--Clause--Clear-blue.svg" alt="License"></a>
+  <a href="https://l-surf-b86f2d.gitlab.io/"><img src="https://img.shields.io/badge/docs-GitLab%20Pages-orange.svg" alt="Documentation"></a>
+</p>
+
+**L**ight **SURF**ace Reflections - GPU-accelerated physically-accurate raytracing framework for simulating light-surface interactions.
+
+**Documentation:** https://l-surf-b86f2d.gitlab.io
+
+## Features
+
+- **Fresnel reflection and refraction** - Physically accurate polarization-dependent coefficients
+- **Multiple scattering** - Multi-bounce ray tracing with intensity splitting
+- **Ocean wave surfaces** - Gerstner wave modeling with curved Earth geometry
+- **GPU acceleration** - CUDA-accelerated via Numba for high-performance simulations
+- **Wavelength-dependent materials** - Sellmeier and Cauchy dispersion models
+- **Polarization tracking** - s and p polarization component handling
+
+## Installation
+
+### Prerequisites
+
+#### NVIDIA GPU Support (Recommended)
+
+For GPU-accelerated ray tracing, you need:
+
+1. **NVIDIA GPU** with CUDA Compute Capability 3.5+ (most GPUs from 2012 onwards)
+2. **NVIDIA Driver** (version 450+ recommended)
+3. **CUDA Toolkit** (version 11.0+ recommended)
+
+**Check your system:**
+```bash
+# Check NVIDIA driver
+nvidia-smi
+
+# Check CUDA version (if installed)
+nvcc --version
+```
+
+**Installing NVIDIA drivers (if needed):**
+```bash
+# Ubuntu/Debian
+sudo apt update
+sudo apt install nvidia-driver-535  # or latest version
+
+# Fedora
+sudo dnf install akmod-nvidia
+```
+
+**Installing CUDA Toolkit:**
+- Download from [NVIDIA CUDA Downloads](https://developer.nvidia.com/cuda-downloads)
+- Or use your distribution's package manager
+
+> **Note:** The package works without a GPU (CPU fallback), but simulations will be significantly slower.
+
+#### Python Environment
+
+- Python >= 3.13
+- pip, conda, or mamba
+
+### Install from PyPI
+
+```bash
+pip install lsurf
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/tobi-h/lsurf.git
+cd lsurf
+pip install -e .
+```
+
+### Verifying GPU Setup
+
+After installation, verify everything works:
+
+```python
+from numba import cuda
+
+# Check CUDA availability
+print(f"CUDA available: {cuda.is_available()}")
+
+if cuda.is_available():
+    gpu = cuda.get_current_device()
+    print(f"GPU: {gpu.name}")
+    print(f"Compute Capability: {gpu.compute_capability}")
+    print(f"Memory: {gpu.total_memory / 1e9:.1f} GB")
+```
+
+### Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| `CUDA not available` | Install NVIDIA drivers and CUDA toolkit |
+| `conda: PackagesNotFoundError` | Update conda: `conda update -n base conda` |
+| `numba.cuda import error` | Ensure CUDA_HOME is set and nvcc is in PATH |
+| `Out of memory` | Reduce `num_rays` or use batched processing |
+
+## Quick Start
+
+### Using the CLI (Recommended)
+
+The **command-line interface** is the recommended way to run simulations:
+
+```bash
+# Build a configuration interactively
+lsurf build -o my_simulation.yaml
+
+# Or use a built-in template
+lsurf build --template ocean -o ocean_sim.yaml
+
+# Validate the configuration
+lsurf run my_simulation.yaml --dry-run
+
+# Run the simulation
+lsurf run my_simulation.yaml --progress
+
+# Run with custom parameters
+lsurf run my_simulation.yaml --num-rays 100000 --output-dir ./results
+```
+
+### Using the GUI
+
+For interactive exploration and visualization, use the **graphical interface**:
+
+```bash
+# Launch the GUI
+lsurf gui
+
+# Or load an existing configuration
+lsurf gui my_simulation.yaml
+```
+
+The GUI provides:
+- Interactive 3D visualization of geometry
+- Configuration editor with live preview
+- One-click simulation execution
+- Built-in result visualization and analysis
+
+### Python API
+
+For custom workflows and advanced use cases, use the Python API with `GeometryBuilder`:
+
+```python
+import lsurf as sr
+from lsurf.geometry import GeometryBuilder
+from lsurf.simulation import Simulation, SimulationConfig
+from lsurf.surfaces import SphereSurface, PlaneSurface, SurfaceRole
+
+# Define constants
+EARTH_RADIUS = 6.371e6  # meters
+
+# Create materials
+atmosphere = sr.ExponentialAtmosphere(n_sea_level=1.000293)
+
+# Create surfaces
+ocean = SphereSurface(
+    center=(0, 0, -EARTH_RADIUS),
+    radius=EARTH_RADIUS,
+    role=SurfaceRole.OPTICAL,
+    name="ocean",
+)
+
+detector = PlaneSurface(
+    point=(0, 0, 35000),
+    normal=(0, 0, 1),
+    role=SurfaceRole.DETECTOR,
+    name="detector_35km",
+)
+
+# Build geometry with named media
+geometry = (
+    GeometryBuilder()
+    .register_medium("atmosphere", atmosphere)
+    .register_medium("ocean", sr.WATER)
+    .set_background("atmosphere")  # Ray propagation medium
+    .add_surface(ocean, front="atmosphere", back="ocean")
+    .add_detector(detector)
+    .build()
+)
+
+# Configure simulation
+config = SimulationConfig(
+    step_size=100.0,           # Max step size in meters
+    max_bounces=5,             # Maximum surface interactions
+    adaptive_stepping=True,    # Use smaller steps near surfaces
+    min_step_size=3e-4,        # 0.3mm for ~1ps time resolution
+)
+
+# Create simulation and run
+sim = Simulation(geometry, config)
+
+# Generate rays from a source
+source = sr.CollimatedBeam(
+    center=(0, 0, 1000),
+    direction=(0.17, 0, -0.98),  # ~10° grazing angle
+    radius=10.0,
+    num_rays=10000,
+    wavelength=532e-9,
+)
+rays = source.generate()
+
+# Run simulation
+result = sim.run(rays)
+print(f"Detected: {result.statistics.rays_detected}")
+print(f"Absorbed: {result.statistics.rays_absorbed}")
+```
+
+### Simple Surface Interaction
+
+For quick tests without the full simulation framework:
+
+```python
+import lsurf as sr
+
+# Create a water surface
+surface = sr.PlaneSurface(
+    point=(0, 0, 0),
+    normal=(0, 0, 1),
+    material_front=sr.AIR_STP,
+    material_back=sr.WATER,
+    role=sr.SurfaceRole.OPTICAL,
+    name="water_surface",
+)
+
+# Create a collimated beam
+source = sr.CollimatedBeam(
+    center=(0, 0, 0.1),
+    direction=(0.707, 0, -0.707),  # 45° incidence
+    radius=0.01,
+    num_rays=1000,
+    wavelength=532e-9,
+)
+rays = source.generate()
+
+# Process reflection/refraction
+reflected, refracted = sr.process_surface_interaction(
+    rays, surface,
+    wavelength=532e-9,
+    generate_reflected=True,
+    generate_refracted=True,
+)
+
+print(f"Reflected rays: {reflected.num_rays}")
+print(f"Refracted rays: {refracted.num_rays}")
+```
+
+## Example Scripts
+
+The `scripts/` directory contains **educational example scripts** that demonstrate specific features and techniques. These are provided as learning resources and references for custom workflows.
+
+> **Note:** For standard simulations, use the CLI (`lsurf run`) or GUI (`lsurf gui`) instead of writing custom scripts. The CLI/GUI handle configuration management, validation, and output automatically.
+
+| Script                                 | Description                                    |
+| -------------------------------------- | ---------------------------------------------- |
+| `01_basic.py`                          | Basic raytracing setup                         |
+| `02_sources.py`                        | Different ray source types                     |
+| `03_visualization.py`                  | Visualization capabilities                     |
+| `04_glass_reflection.py`               | Fresnel reflection at glass interface          |
+| `05_water_brewster.py`                 | Brewster angle validation                      |
+| `06_detector_scan.py`                  | Detector position scanning (planar)            |
+| `07_detector_scan_waves.py`            | Detector scanning with wave surface            |
+| `08_detector_scan_waves_largescale.py` | Large-scale ocean simulation                   |
+| `09_full_3d_curved_ocean.py`           | Full 3D ray tracing with curved ocean surface  |
+| `10_time_spread_estimate.py`           | Geometric time spread estimation               |
+
+Run an example:
+
+```bash
+cd scripts
+python 01_basic.py
+```
+
+## Dependencies
+
+| Category | Packages |
+|----------|----------|
+| **Core** | numpy >= 1.24, matplotlib >= 3.7, pydantic >= 2.0 |
+| **GPU** | numba >= 0.58, CUDA toolkit >= 11.0 |
+| **Optional** | h5py >= 3.8 (HDF5 support), astropy-healpix (spherical analysis) |
+| **Dev** | pytest, black, ruff, mypy, pre-commit |
+
+All dependencies are automatically installed via `environment.yml` or `pip install -e ".[dev]"`.
+
+## Project Structure
+
+```
+lsurf/
+├── src/
+│   └── lsurf/                     # Main package
+│       ├── geometry/              # GeometryBuilder and Geometry
+│       ├── simulation/            # Simulation, SimulationConfig, results
+│       ├── propagation/           # Ray propagation engines and GPU kernels
+│       ├── materials/             # Material definitions (homogeneous, atmosphere)
+│       ├── sources/               # Ray source generators
+│       ├── surfaces/              # Surface geometries (cpu/ and gpu/)
+│       ├── detectors/             # Detection and analysis
+│       ├── utilities/             # Ray data, fresnel, recording
+│       ├── visualization/         # Plotting functions
+│       └── interactions.py        # Surface interaction processing
+├── scripts/                       # Example scripts
+├── tests/                         # Test suite
+├── docs/                          # Sphinx documentation
+├── pyproject.toml                 # Python packaging config
+└── environment.yml                # Development environment
+```
+
+## Testing
+
+```bash
+pytest tests/ -v
+```
+
+## License
+
+Clear BSD License - see [LICENSE](LICENSE) for details.
+
+Copyright (c) 2026 Tobias Heibges. All rights reserved.