Metadata-Version: 2.4
Name: blaze2d
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Requires-Dist: numpy>=1.20
Requires-Dist: matplotlib>=3.5 ; extra == 'plot'
Requires-Dist: matplotlib>=3.5 ; extra == 'all'
Requires-Dist: pandas>=1.3 ; extra == 'all'
Provides-Extra: plot
Provides-Extra: all
Summary: BLAZE - Band-structure LOBPCG Accelerated Zone Eigensolver for 2D Photonic Crystals
Keywords: photonic-crystals,band-structure,eigensolver,LOBPCG,physics,simulation,computational-physics,materials-science
Author-email: RnLe <rene.marcel.lehner@gmail.com>
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# BLAZE - Band-structure LOBPCG Accelerated Zone Eigensolver

High-performance 2D photonic crystal band structure solver with Python bindings.

## Installation

```bash
pip install blaze2d
```

## Quick Start

```python
from blaze import BulkDriver

# Load configuration from TOML file
driver = BulkDriver("config.toml")
print(f"Will run {driver.job_count} jobs")

# Stream results as they complete (for live plotting)
for result in driver.run_streaming():
    print(f"Job {result['job_index']}: {result['num_bands']} bands")
    # result['bands'] is a 2D array [k_index][band_index]
    # result['distances'] is the k-path distance for plotting

# Or collect all results at once
results, stats = driver.run_collect()
print(f"Completed {len(results)} jobs in {stats['total_time_secs']:.2f}s")
```

## Configuration

BLAZE uses TOML configuration files. Example for a parameter sweep:

```toml
[bulk]
output_dir = "results"
output_mode = "full"

[bulk.ranges]
radius = { min = 0.2, max = 0.4, step = 0.05 }
eps_inside = { values = [9.0, 12.0, 13.0] }
polarization = ["te", "tm"]

[simulation]
resolution = 32
num_bands = 8

[lattice]
type = "square"

[[atoms]]
position = [0.5, 0.5]
radius = 0.3
epsilon = 1.0
```

## API Reference

### BulkDriver

```python
driver = BulkDriver(config_path: str, threads: int = 0)
```

- `config_path`: Path to TOML configuration file
- `threads`: Thread count (-1 = adaptive, 0 = auto, >0 = fixed)

#### Properties

- `job_count`: Number of jobs to execute
- `config_path`: Path to configuration file

#### Methods

| Method | Description |
|--------|-------------|
| `run_streaming()` | Iterator yielding results as they complete |
| `run_streaming_filtered(k_indices, band_indices)` | Filtered streaming |
| `run_collect(k_indices, band_indices)` | Collect all results into list |
| `run_batched(buffer_size_mb)` | Run with buffered disk I/O |
| `run()` | Synchronous execution |
| `dry_run()` | Count jobs without executing |

### Result Dictionary

Each result is a dictionary with:

| Key | Type | Description |
|-----|------|-------------|
| `job_index` | int | Job identifier |
| `params` | dict | Simulation parameters |
| `k_path` | list | K-points as (kx, ky) tuples |
| `distances` | list | Cumulative k-path distance |
| `bands` | list | 2D array `[k_index][band_index]` |
| `num_k_points` | int | Number of k-points |
| `num_bands` | int | Number of bands |

## Plotting Example

```python
import matplotlib.pyplot as plt
from blaze import BulkDriver

driver = BulkDriver("sweep.toml")

# Live plotting with streaming
plt.ion()
fig, ax = plt.subplots()

for result in driver.run_streaming():
    ax.clear()
    for band_idx in range(result['num_bands']):
        band = [result['bands'][k][band_idx] for k in range(result['num_k_points'])]
        ax.plot(result['distances'], band)
    ax.set_xlabel('k-path')
    ax.set_ylabel('ω (normalized)')
    ax.set_title(f"Job {result['job_index']}")
    plt.pause(0.01)

plt.ioff()
plt.show()
```

## Filtered Streaming

For large simulations, filter to only the k-points and bands you need:

```python
# Stream only Gamma (0), X (10), M (15) and first 4 bands
for result in driver.run_streaming_filtered(
    k_indices=[0, 10, 15],
    band_indices=[0, 1, 2, 3]
):
    assert result['num_k_points'] == 3
    assert result['num_bands'] == 4
```

## License

MIT


