maiman 0.1.0__tar.gz

maiman-0.1.0/.gitattributes

@@ -0,0 +1,8 @@
+# Normalize line endings: LF in the repository, native in the working tree.
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.gds binary
+*.npy binary
+*.npz binary

maiman-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,65 @@
+name: Bug report
+description: Something crashes, refuses valid input, or does not do what it says.
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        For a result that is *physically* wrong rather than broken, use **A model is wrong**
+        instead — it asks for the reference, which is what makes that kind of report actionable.
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: What you ran
+      description: >-
+        The smallest script that shows it. A graph with four blocks that fails is worth ten times
+        a forty-block one that also fails.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: happened
+    attributes:
+      label: What happened
+      description: The full traceback, if there is one. Do not trim it — the frames matter.
+      render: shell
+    validations:
+      required: true
+
+  - type: input
+    id: expected
+    attributes:
+      label: What you expected instead
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Commit
+      description: "`git rev-parse --short HEAD`"
+    validations:
+      required: true
+
+  - type: input
+    id: environment
+    attributes:
+      label: Python and OS
+      description: "`python -VV` and your platform"
+      placeholder: "3.12.4, Windows 11"
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: suite
+    attributes:
+      label: Before opening
+      options:
+        - label: >-
+            The suite passes on my checkout
+            (`ruff check . && ruff format --check . && mypy && pytest`), so this is not my
+            environment. Tick it or say why not — a failing suite is itself worth reporting.
+          required: false

maiman-0.1.0/.github/ISSUE_TEMPLATE/component_or_feature.yml

@@ -0,0 +1,51 @@
+name: A missing component or capability
+description: Something you need to model a link that this cannot express.
+title: "[request] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The most useful version of this issue describes **the link you are trying to build**, not
+        just the block you want. What a component has to get right is decided by what it sits
+        between, and that is usually clear from the system and rarely from the block alone.
+
+  - type: textarea
+    id: use_case
+    attributes:
+      label: What are you trying to model
+      description: >-
+        The system, the rates, the formats, what you need to read out at the end. If you currently
+        do this in another tool, saying which is useful — including if the answer is a spreadsheet.
+    validations:
+      required: true
+
+  - type: textarea
+    id: missing
+    attributes:
+      label: What is missing
+      placeholder: "A Raman amplifier with counter-propagating pumps; export of sweep results as CSV"
+    validations:
+      required: true
+
+  - type: textarea
+    id: reference
+    attributes:
+      label: A model to build it from, if you have one
+      description: >-
+        Optional, and it is what decides whether this is a weekend or a month. A component here
+        needs a published model and a closed-form result to be tested against; without a reference
+        the first work is finding one.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: offer
+    attributes:
+      label: Would you want to implement it
+      options:
+        - "No — flagging it"
+        - "Maybe, with guidance on where it goes"
+        - "Yes"
+    validations:
+      required: true

maiman-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/ehsun-sh/maiman-studio/security/advisories/new
+    about: >-
+      Privately, not in the issue tracker. See SECURITY.md for what does and does not count.
+  - name: Does this duplicate something that already exists?
+    url: https://github.com/ehsun-sh/maiman-studio/issues/new
+    about: >-
+      Open a blank issue and say so. Knowing early is worth more than most feature requests —
+      several months could go into work someone has already done better.

maiman-0.1.0/.github/ISSUE_TEMPLATE/model_is_wrong.yml

@@ -0,0 +1,54 @@
+name: A model is wrong
+description: A physics block does not agree with the literature, a standard, or measurement.
+title: "[model] "
+labels: ["model", "needs-reference"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This is the most valuable issue you can open here, and it is deliberately the first one
+        offered.
+
+        Every physics block in this project is validated against a closed-form result, and the
+        validation is only as good as the closed form it was checked against. If one of those is
+        the wrong expression, the wrong regime, or the right expression misapplied, everything
+        downstream of it inherits the error and the test suite agrees with it enthusiastically.
+
+  - type: input
+    id: block
+    attributes:
+      label: Which block or function
+      placeholder: "maiman.components.EDFA, or maiman.dsp.estimate_timing"
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What it should do, and where that comes from
+      description: >-
+        A paper with an equation number, a standard with a clause, or your own measurement.
+        This project does not accept models derived from inspection of commercial tools — not
+        because they are wrong, but because nobody without a licence can check them.
+      placeholder: |
+        Agrawal, Fiber-Optic Communication Systems, 4th ed., eq. (2.4.15) gives ...
+        ITU-T G.652 clause 8.2 specifies ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: observed
+    attributes:
+      label: What it does instead
+      description: Numbers, please. A script that produces them is better still.
+      render: python
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Commit
+      description: "`git rev-parse --short HEAD`. There are no releases yet, so the commit is the version."
+    validations:
+      required: true

maiman-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Type check
+        run: mypy
+
+      - name: Test
+        run: pytest
+
+  # Runs only where a CUDA device is actually attached. The default job above
+  # tests what would break a GPU port — that the kernels never reach for NumPy
+  # directly, against a deliberately hostile array library; this one tests that
+  # the port is not broken, on hardware.
+  #
+  # Gated on a repository *variable* rather than on the runner label alone. A job
+  # that merely asks for a label nobody provides is not skipped, it is queued —
+  # for hours, holding the whole run pending and the badge with it. Set
+  # `HAS_GPU_RUNNER` to `true` under Settings → Secrets and variables → Actions
+  # once a machine labelled `gpu` is attached, and this starts running; until
+  # then it is skipped, which costs nothing and claims nothing.
+  device:
+    if: ${{ vars.HAS_GPU_RUNNER == 'true' }}
+    runs-on: [self-hosted, gpu]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install, with CuPy
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install cupy-cuda12x
+
+      # One soliton period on the device against the same span on NumPy. Exits
+      # non-zero only if a back-end is present and disagrees.
+      - name: Cross-check the device against NumPy
+        run: maiman devices
+
+      - name: Test
+        run: pytest

maiman-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,128 @@
+# Publish to PyPI.
+#
+# **No API token anywhere.** This uses PyPI's trusted publishing: GitHub mints a
+# short-lived OIDC identity for this workflow, PyPI checks it against a publisher
+# it was told to trust, and the upload is authorised without a secret existing at
+# all. A token in repository secrets is a long-lived credential that can be
+# leaked, has to be rotated, and grants upload rights to anyone who obtains it.
+# This has none of those properties, which is why it is worth the one-time setup
+# described in RELEASING.md.
+#
+# It runs on a published GitHub release rather than on a tag push, so the release
+# notes and the artifacts are one act. The build is checked before it is
+# uploaded, and the tag has to agree with the version in pyproject.toml -- a
+# mismatch there is unrecoverable once uploaded, because PyPI never lets a
+# version number be reused.
+
+name: Release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        required: true
+        default: testpypi
+        type: choice
+        options: [testpypi, pypi]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install the build tools
+        run: python -m pip install --upgrade build twine
+
+      - name: Refuse a tag that disagrees with the version
+        if: github.event_name == 'release'
+        run: |
+          declared=$(python -c "import tomllib,pathlib;print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          tag="${GITHUB_REF_NAME#v}"
+          echo "pyproject says $declared, tag says $tag"
+          if [ "$declared" != "$tag" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match version $declared in pyproject.toml"
+            exit 1
+          fi
+
+      - name: Build
+        run: python -m build
+
+      - name: Check the metadata renders
+        run: python -m twine check --strict dist/*
+
+      - name: Install the wheel somewhere clean and run a link through it
+        run: |
+          python -m venv /tmp/fresh
+          /tmp/fresh/bin/python -m pip install --quiet dist/*.whl
+          cd /tmp
+          /tmp/fresh/bin/python - <<'PY'
+          import pathlib
+
+          import maiman
+          from maiman import Graph, SimulationContext
+          from maiman.components import CWLaser, PowerMeter
+
+          ctx = SimulationContext(bit_rate=10e9, samples_per_symbol=8, sequence_length=64)
+          graph = Graph(ctx)
+          laser = graph.add(CWLaser(power=0.0))
+          meter = graph.add(PowerMeter())
+          graph.chain(laser, meter)
+          # 1e-6, not 1e-9: converting watts to dBm and back costs a couple of
+          # parts in 1e7 on its own. The tighter bound passed when I wrote it
+          # only because I printed the number rounded to six places.
+          assert abs(graph.run()[meter].power_dbm) < 1e-6
+
+          page = pathlib.Path(maiman.__file__).parent / "studio" / "index.html"
+          assert page.exists(), "the wheel does not carry the studio page"
+          assert len(maiman.registered_names()) > 40
+          print(f"maiman {maiman.__version__}: a link ran and the page is present")
+          PY
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: distributions
+          path: dist/
+
+  testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write # the OIDC identity, and the only credential involved
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

maiman-0.1.0/.gitignore

@@ -0,0 +1,68 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.pyd
+
+# Packaging / build
+build/
+dist/
+sdist/
+wheels/
+*.egg-info/
+*.egg
+.eggs/
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing / coverage / type checking
+.pytest_cache/
+.tox/
+.nox/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.hypothesis/
+.mypy_cache/
+.pyright/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+profile_default/
+ipython_config.py
+
+# Simulation output — results are reproducible from the project file + seed,
+# so they are regenerated, never committed.
+results/
+*.npy
+*.npz
+*.h5
+*.hdf5
+
+# Node / web UI (from Phase 2 onward)
+node_modules/
+.next/
+.vite/
+*.tsbuildinfo
+
+# Editors / IDEs
+.vscode/
+.idea/
+*.swp
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Local agent/tooling config
+.claude/

maiman-0.1.0/CITATION.cff

@@ -0,0 +1,44 @@
+cff-version: 1.2.0
+title: "Maiman Studio"
+message: >-
+  If you use this software in work you publish, please cite it as below.
+  Please also cite the primary sources for whichever physics you relied on:
+  every component's docstring names the paper or standard its model comes
+  from, and those authors did the work this only implements.
+type: software
+authors:
+  - family-names: Shahmohammadi
+    given-names: Ehsan
+    email: ehsun.ca@gmail.com
+repository-code: "https://github.com/ehsun-sh/maiman-studio"
+url: "https://github.com/ehsun-sh/maiman-studio"
+abstract: >-
+  An open-source simulator for optical communication links and photonic
+  systems. Links are built as block diagrams — laser, modulator, fiber,
+  amplifier, detector, receiver DSP — and read back as eye diagrams, bit
+  error rates, OSNR figures and constellation measurements. Every physics
+  block is validated against a closed-form result in continuous
+  integration, and models are derived from published literature and
+  standards rather than from inspection of commercial tools.
+
+  The project is named after Theodore Maiman, who built the first working
+  laser at Hughes Research Laboratories in May 1960.
+keywords:
+  - photonics
+  - optical communications
+  - fiber optics
+  - simulation
+  - digital signal processing
+  - forward error correction
+  - photonic integrated circuits
+license: Apache-2.0
+version: 0.1.0
+
+# No `date-released`, deliberately. There has been no release: the version
+# above is a development version, the package is not on PyPI, and the field
+# would have to be invented to be present. Cite the repository and, if the
+# result matters, the commit you ran — `git rev-parse HEAD` — because a
+# pre-alpha tree is not a stable thing to cite by name alone.
+#
+# No ORCID and no affiliation either, for the same reason: neither is on
+# hand, and a citation file is exactly the wrong place to approximate.

maiman-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing
+
+The core is small enough that changing it is still cheap, which makes right now the most useful
+time to push back on it. The [README's Contributing section](README.md#contributing) says where
+help is most valuable; this file says how the project actually works, and what it refuses.
+
+## The one command that decides
+
+```bash
+pip install -e ".[dev]" && ruff check . && ruff format --check . && mypy && pytest
+```
+
+Run **that**, not a narrower version of it. Two red builds in this repository's short history came
+from running a subset: `mypy src tests examples` instead of bare `mypy`, and `ruff format tests`
+instead of `ruff format .`. Both passed locally and both failed in CI, because the command that
+decides is the whole one. `mypy` takes no arguments here on purpose — its configuration already
+names what to check.
+
+## What this project refuses
+
+These are not style preferences. They are the reason the simulator is worth trusting, and a change
+that breaks one will not be merged however good the code is.
+
+**Every number shown must come from the engine.** Not from a plausible-looking constant, not from
+a curve fitted to a screenshot, not from a figure remembered from a datasheet. If the interface
+displays it, a component computed it.
+
+**Every physics block ships with a test against a closed-form result.** Not "the code runs" — a
+comparison against an analytical answer the block cannot have been written to agree with by
+accident. See [`tests/test_physics.py`](tests/test_physics.py). A component without one will not be
+merged, and this is the rule most often argued with.
+
+**Models come from published literature and standards, cited in the docstring — never from
+inspection of commercial tools.** Comparing against a licensed tool is not reproducible in CI and
+proves nothing to anyone who cannot afford the licence. Name the paper, the equation number, and
+the edition.
+
+**Derive rather than transcribe, where you can.** A generator polynomial's *roots* are the claim; a
+table of its coefficients is a copy that no test can check. Where a table genuinely has to be
+present — the primitive polynomials in [`src/maiman/softfec.py`](src/maiman/softfec.py) — the code
+verifies it at construction, so the table is an assertion rather than an assumption.
+
+**Never ship a claim you cannot back.** If a model does not work, say so in the docstring, write a
+test that pins the failure, and do not tune it until a curve looks plausible. There is precedent in
+this repository for exactly that, including the commit that had to correct its own diagnosis.
+
+**The interface never shows a control it cannot back.** A parameter that moves nothing is worse
+than a missing feature, because the user cannot tell. If a model stops using a parameter, retire it
+— see `retired_parameters` in [`src/maiman/component.py`](src/maiman/component.py) — and say in the
+comment whether dropping it changes the link a saved project describes. Usually it does not. Once,
+it did, and the comment says so.
+
+**An idealisation is declared, not delivered by accident.** A laser with no intensity noise, an
+amplifier that never compresses — these are fine and useful, and they are flags with defaults, not
+silence. What is not fine is a clamp that calls itself a saturation model.
+
+## Adding a component
+
+A component is a Python class with declared parameters and typed ports. Read a few in
+[`src/maiman/components/`](src/maiman/components/) first — `CWLaser` for a source, `Fiber` for a
+channel, `TimingRecovery` for a DSP block with a diagnostics port.
+
+1. Subclass `Component`. Set `display_name`, `category`, `inputs` and `outputs`.
+2. Declare parameters with `Param` / `BoolParam`, each with its real unit and a `doc` that says
+   what it does. Units convert once, at the boundary, via `si()`; see
+   [`src/maiman/units.py`](src/maiman/units.py).
+3. Implement `run(ctx, inputs) -> dict[str, Signal]`.
+4. Export it from [`src/maiman/components/__init__.py`](src/maiman/components/__init__.py).
+5. Write the closed-form test.
+6. Regenerate the interface's baked data and splice it back into the page:
+
+```bash
+python examples/export_ui_data.py
+```
+
+Then copy `examples/ui_data.json` verbatim into the `<script id="maiman-data">` block of
+`src/maiman/studio/index.html`. The tests below will tell you if you forget.
+
+If your component emits a new kind of measurement, it also needs an encoder in
+[`src/maiman/encoding.py`](src/maiman/encoding.py) and a `case` in the studio page's `describe()`
+so the log prints a fact rather than the name of a type.
+
+## The guards, and what they mean when they fire
+
+Several tests exist only to catch drift between parts that have no other way to disagree. They are
+not obstacles; each one has caught a real mistake, most of them more than once.
+
+| Test | Fires when | Do this |
+| :--- | :--- | :--- |
+| `test_the_palette_is_the_whole_library` | A component is registered but not in the baked export | Re-run the export and splice |
+| `test_the_baked_manifests_are_the_live_ones` | A *parameter* changed since the last export | Same — this one catches what the palette test cannot |
+| `test_every_kind_the_engine_can_send_has_a_line_to_print` | A new encoded kind has no `case` in `describe()` | Give the log the fact the payload carries |
+| `test_no_metric_port_in_the_library_encodes_as_opaque` | A new metric port is never exercised | Add a graph in `tests/test_server.py` that runs it |
+| `test_every_block_in_the_project_has_somewhere_to_be_drawn` | A block in the shipped project has no canvas position | Add it to `LAYOUT` in the studio page |
+| `test_the_schematic_on_the_canvas_is_a_graph_that_runs` | The shipped project does not execute | The page is showing a link that cannot exist — fix the project |
+| The test-count floor in `test_packaging.py` | The suite shrank below what the docs claim | Either you deleted tests, or a doc needs updating |
+
+## Documentation
+
+`README.md` is the argument for the project and carries its measured results. `PRODUCT.md` is who
+it is for. `DESIGN.md` is the interface's reasoning, including a "Not done" section that is kept
+honest. `docs/ARCHITECTURE.md` is the engine's.
+
+Numbers in those files are **measured**, and several of them are pinned by tests. If you change a
+model, re-measure rather than adjusting the prose to match your intuition.
+
+## Commits
+
+Explain *why*, and what you learned. A commit here is expected to say what was measured, what was
+surprising, and what was wrong before — including when the thing that was wrong was the previous
+commit's own explanation. That is not ceremony; it is the only durable record of why a model looks
+the way it does.
+
+Open an issue before a large change, so nobody spends a weekend on something that was already
+decided against.