Metadata-Version: 2.5
Name: scatterworks
Version: 0.1.0
Summary: Python package for building and solving scattering-network models
Project-URL: Documentation, https://gitlab.kwant-project.org/qt/scatterworks
Project-URL: Repository, https://gitlab.kwant-project.org/qt/scatterworks
Project-URL: Bug Tracker, https://gitlab.kwant-project.org/qt/scatterworks/-/issues
Author: ScatterWorks developers
License-Expression: BSD-2-Clause
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: numpy>=1.25
Requires-Dist: packaging>=22.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scipy>=1.11
Provides-Extra: plot
Requires-Dist: bokeh<4,>=3.7; extra == 'plot'
Provides-Extra: solver
Requires-Dist: python-mumps<0.1,>=0.0.3; extra == 'solver'
Provides-Extra: symbolic
Requires-Dist: sympy<2,>=1.13.3; extra == 'symbolic'
Description-Content-Type: text/markdown

# ScatterWorks

`scatterworks` is a Python package for building and solving scattering-network
models. It keeps the directed network geometry separate from the local
scattering matrices, then assembles them into global operators for spectra,
transport, and finite-device calculations.

The same network object can represent periodic unit cells and finite systems.
Its explicit link basis makes local scattering templates and the flow of wave
amplitudes straightforward to inspect.

## Installation

ScatterWorks requires Python 3.11 or newer. Install the core package with:

```bash
pip install scatterworks
```

Install the optional Bokeh plotting support with:

```bash
pip install "scatterworks[plot]"
```

Install symbolic scattering support with:

```bash
pip install "scatterworks[symbolic]"
```

Install the optional MUMPS-backed sparse solver with:

```bash
pip install "scatterworks[solver]"
```

Optional features can be installed together. For example, to install all
three extras, run:

```bash
pip install "scatterworks[plot,symbolic,solver]"
```

For an editable source checkout, run `pip install -e .`. The repository uses
[Pixi](https://pixi.sh/) for development. Build the documentation
from the repository root with:

```bash
pixi run docs-build
```

## Quick start

A network is defined by integer rows containing a source node and a sink node:

```python
import numpy as np
import scatterworks as sw

links = np.array(
    [
        [0, 1],
        [1, 0],
    ],
    dtype=int,
)

network = sw.Network(links)
print(network.links)
```

For a periodic model, append one integer unit-cell shift per lattice dimension
to each row:

```python
unit_cell_links = np.array(
    [
        [0, 1, 0, 0],
        [0, 1, -1, -1],
        [1, 0, 1, 0],
        [1, 0, 0, 1],
    ],
    dtype=int,
)

unit_cell = sw.Network(unit_cell_links)
```

After defining the topology, use
`scatterworks.scattering.scattering_equations` to assemble local scattering
matrices into a global operator. Lead-to-lead problems can be solved with
`scatterworks.scattering.solve_scattering_equations` or
`scatterworks.scattering.schur_solve`.

## Documentation

- Start with the [network model basics](https://gitlab.kwant-project.org/qt/scatterworks/-/blob/main/docs/source/basics.md).
- Work through the [Fabry-Perot interferometer](https://gitlab.kwant-project.org/qt/scatterworks/-/blob/main/docs/source/fabry_perot_interferometer.md)
  for a small finite example.
- See the [Chalker-Coddington network](https://gitlab.kwant-project.org/qt/scatterworks/-/blob/main/docs/source/chalker_coddington.md) for a
  periodic unit cell.
- Follow the [Kagome ribbon tutorial](https://gitlab.kwant-project.org/qt/scatterworks/-/blob/main/docs/source/relink_kagome.md) to cut and
  relink a finite strip.
- Browse the [package reference](https://gitlab.kwant-project.org/qt/scatterworks/-/blob/main/docs/source/packagereference.md) for the Python
  API.
