Metadata-Version: 2.4
Name: cwt3d
Version: 1.3.1
Summary: Independent numerical core for three-dimensional coupled-wave theory
License-Expression: MIT
Project-URL: Homepage, https://github.com/maple367/3D-CWT
Project-URL: Documentation, https://github.com/maple367/3D-CWT/blob/latest/docs/api.md
Project-URL: Issues, https://github.com/maple367/3D-CWT/issues
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.6; extra == "plot"
Provides-Extra: numba
Requires-Dist: numba>=0.61; extra == "numba"
Dynamic: license-file

# cwt3d

A Python implementation of three-dimensional coupled-wave theory for
square-lattice photonic-crystal surface-emitting lasers (PCSELs).

The package calculates normalized vertical TE waveguide modes, Fourier
coupling coefficients, and finite-cavity envelopes using sparse staggered-grid
eigenproblems. Runtime dependencies are NumPy and SciPy.

## Install

```bash
python -m pip install cwt3d
```

Matplotlib is optional:

```bash
python -m pip install "cwt3d[plot]"
```

## Examples and Python interfaces

The [source repository](https://github.com/maple367/3D-CWT) includes a complete
70 × 70 µm² circular-hole example based on Chapter 4 of Yong Liang's thesis.
It contains the layer stack, runnable calculation and plotting scripts, and
numerical refinement results.

![70 µm PCSEL envelope](https://raw.githubusercontent.com/maple367/3D-CWT/latest/docs/images/liang-70um.png)

The [Python API guide](https://github.com/maple367/3D-CWT/blob/latest/docs/api.md)
shows how to construct a different geometry, calculate its coupling matrix,
solve a finite cavity, and access the complex fields. Examples are included
in the source distribution and repository; the wheel installs the `cwt3d`
library.

## Scope

Reciprocal Green-value reuse is enabled by default. Pass `reciprocity=False`
to `build_coupling(...)` to use the original two-evaluation formula. The
repository examples also accept `--no-reciprocity`. Both settings keep the
same precision and integration orders; selected settings are recorded and
separated in the optional cache. The optimization does not require geometric
symmetry within the supported scalar TE model. See the
[validation and benchmark notes](https://github.com/maple367/3D-CWT/blob/latest/docs/validation/reciprocal-green-overlap/README.md).

The current model uses lossless scalar TE waves on a square lattice.
It returns modes near a selected complex shift, not the complete cavity
spectrum. The example's auxiliary-harmonic refinement is still finite, as
reported in its notes. Carrier transport and above-threshold dynamics from
the historical application are not part of this package.

The code is distributed under the MIT license. The formulation follows
[Yong Liang's doctoral thesis](https://doi.org/10.14989/doctor.k18283);
references and conventions are listed in the repository documentation.
