netSALT

KO | EN

gitlite — search

#javascript #ai #typescript #llm #golang #go #rust #deep-learning #kubernetes #security #pytorch #mcp #ios #open-source

(★ 9)

Simulation of lasing networks with quantum graphs and SALT theory.

netSALT 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![DOI](https://zenodo.org/badge/171305314.svg)](https://zenodo.org/badge/latestdoi/171305314)

Code simulating quantum graphs. 
================================

Doc: https://arnaudon.github.io/netSALT/

This code simulates network lasers with the SALT approximation and quantum graphs.

This is the code accompanying the following publications:
```
Sensitivity and spectral control of network lasers
Dhruv Saxena, Alexis Arnaudon, Oscar Cipolato, Michele Gaio, Alain Quentel, Sophia Yaliraki, Dario Pisignano, Andrea Camposeo, Mauricio Barahona, Riccardo Sapienza
```
available on arxiv: https://arxiv.org/abs/2203.16974
and Nat. Comm.: https://www.nature.com/articles/s41467-022-34073-3

## Installation

We recommend [uv](https://docs.astral.sh/uv/) for managing the environment.
From a checkout:
```bash
uv venv
uv pip install -e .
```
or from pypi:
```bash
uv pip install netsalt
```

Plain `pip` still works if you prefer:
```bash
pip install -e .
# or
pip install netsalt
```

## Usage

The code is accessible directly, or via a plain-Python pipeline
(`netsalt.pipeline`) driven by YAML config files, see `examples/`.

### Quickstart

**The object API.** `QuantumGraph` is a thin `networkx.Graph` subclass that
carries the quantum-graph state and exposes the build/solve helpers as methods,
so you set up physics and build matrices on one object instead of threading a
bare graph through free functions:

```python
import networkx as nx
import numpy as np
from netsalt import QuantumGraph
from netsalt.physics import dispersion_relation_dielectric

g = nx.path_graph(20)
positions = np.array([[float(i), 0.0] for i in range(20)])

qg = QuantumGraph.from_networkx(
    g,
    params={
        "open_model": "open",
        "c": 1.0,
        "dielectric_params": {
            "method": "uniform",
            "inner_value": 4.0,
            "loss": 0.0,
            "outer_value": 1.0,
        },
    },
    positions=positions,
)
qg.set_dispersion_relation(dispersion_relation_dielectric)
qg.set_dielectric_constant()

L = qg.laplacian(2.0 + 0.0j)        # quantum Laplacian L(k)
quality = qg.mode_quality([2.0, 0.0])  # how close [Re(k), -Im(k)] is to a mode
pumped = qg.with_pump(0.7)          # a copy at pump D0 = 0.7, original untouched
```

Every method delegates to the matching module-level function (`construct_laplacian`,
`mode_quality`, …), so the procedural API keeps working unchanged and the class is
purely opt-in. `load_graph("graph.json", as_class=True)` returns a `QuantumGraph`.

**The pipeline.** For a full passive/lasing/controllability run, drive the
pipeline from a YAML config:

```bash
python -m netsalt lasing config.yaml          # passive | lasing | controllability
```

Each step caches to disk and is skipped when its output exists (pass `--force`
to recompute). See `examples/` for ready-to-run configs and `MIGRATION.md` if
you are coming from the old Luigi workflow.

### Mode search

Modes inside a complex-`k` rectangle can be located three different
ways. The pipeline picks one via
`params["mode_search_method"]` (default `"contour"`); direct callers
can pick by importing the function they want.

| entry point | when to use | wired into the pipeline? |
|---|---|---|
| `find_modes_contour` | the production search; takes an `n_k × n_alpha` cell layout | **yes** — used by `find_passive_modes(method="contour")`, the pipeline default |
| `find_modes_contour_adaptive` | parameter discovery — you don't know the mode count yet | no — direct API only |
| `tune_contour_parameters` | batches of similar-density randomized graphs | no — direct API only |

**`find_modes_contour` is the recommended production entry point.**
`find_modes_contour_adaptive` is intended for exploration: its
saturation-driven recursion can drop a small fraction of modes near
cell edges (1–5% on 300–500-mode workloads in the benchmarks). For
runs where every mode matters, use `find_modes_contour` with an
explicit `n_k`, picked either by hand from the rule
`n_k ≥ ⌈expected_modes / (0.65 · probe_dim)⌉` or by
`tune_contour_parameters`.

#### The pipeline default

`config.yaml` has `mode_search_method = contour`, which routes
`step_find_passive_modes` (`netsalt/pipeline.py`) through
`netsalt.find_passive_modes(method="contour")` →
`find_modes_contour`. Sensible defaults are picked from
`graph.graph["params"]`:

- `n_k` ≈ `round(k_max - k_min)` (one cell per unit `k` — fine for
  the small ranges netsalt typically scans)
- `n_alpha = 2`
- `n_quad = 80`
- `probe_dim` defaults to `min(40, n_nodes)`

The legacy `mode_search_method = grid` path is still available;
it runs `scan_frequencies` + `peak_local_max` + per-mode
`refine_mode_root` and ignores the contour helpers.

#### Using `find_modes_contour_adaptive` directly (with caveat)

When you don't know how many modes are in your rectangle, the
adaptive variant subdivides on demand: each cell is bisected when
it returns either `≥ saturation_factor · probe_dim` modes (genuine
saturation) or `0` modes at low depth (over-capacity collapse,
empirically the dominant failure mode at high mode count). It does
not need a manual `n_k`.

```python
from netsalt import find_modes_contour_adaptive

modes = find_modes_contour_adaptive(
    graph,
    bounds=(k_min, k_max, alpha_min, alpha_max),
    n_quad=200,
    probe_dim=40,         # or None for min(40, n_nodes)
    max_depth=6,          # 8 for >300 modes
    saturation_factor=0.7,
    rng=np.random.default_rng(0),
)
```

**Caveat — coverage is not guaranteed.** On the 500-mode stress
benchmark, adaptive recovers 472–502 modes depending on `probe_dim`
and `max_depth`; the saturation heuristic plus boundary dedup at
deep recursion can drop modes near cell edges. If 100% coverage
matters, use `find_modes_contour` with an explicit `n_k` instead —
preferably one that `tune_contour_parameters` picked for you.

The adaptive search is not currently wired into
`step_find_passive_modes`; if you want it inside a pipeline run, call
it directly and write the resulting modes to the passive-modes output.

#### Batch processing similar graphs (`tune_contour_parameters`)

If you have many graphs of the same topology and density (for
instance a sweep over RNG seeds), `tune_contour_parameters` runs
the adaptive search once on a representative graph, then returns
parameter values sized for the (more reliable) non-adaptive path:

```python
from netsalt import tune_contour_parameters, find_modes_contour

# Step 1: tune once on a representative graph.
params, info = tune_contour_parameters(
    representative_graph,
    bounds=bounds,
    probe_dim=40,
    n_quad=200,
)
# info["discovered_modes"] = 150
# params = {"n_k": 9, "n_alpha": 1, "n_quad": 200, "probe_dim": 40}

# Step 2: batch-process similar graphs — full coverage on each.
for seed in seeds:
    g = make_graph(seed)
    modes = find_modes_contour(g, bounds=bounds, **params)
```

`tune_contour_parameters` picks `n_k` so each cell has at most
`0.65 · probe_dim / safety_factor` modes (default
`safety_factor=1.5` leaves 50% headroom for instance variation).
The `safety_factor` matters: even if adaptive's discovery
under-counts a few modes, the non-adaptive call sized with the
recommended `n_k` recovers them all (the stress workload in
`benchmark/bench_contour.py` is a worked example at ~300 modes).

#### When to choose what

- **Default pipeline run** (`mode_search_method = contour`) is fine
  for most workloads — it picks `n_k ≈ k_range` and the netsalt
  scan rectangles are small enough that this is well-sized.
- **Use `tune_contour_parameters`** when running the same search
  over many randomized similar graphs, or when you want to lock in
  fast and reliable non-adaptive parameters for a production run.
- **Use `find_modes_contour_adaptive` directly** only as a
  one-shot exploration tool on an unfamiliar graph; **do not**
  rely on it for production where every mode matters.

See `benchmark/README.md` for the empirical study behind
`n_k`-vs-`probe_dim` sizing.

### Mode refinement

`refine_mode` exposes two algorithms: `"root"` (default,
MINPACK `hybr`) and `"brownian"` (legacy ratchet). Pick via
`params["refine_method"]`. `root` is 4–5× faster than `brownian`
across every graph size benchmarked; brownian stays available for
reproducibility with pre-2026 results.

netSALT

netSALT 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

netSALT

netSALT 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README