Add pydeserver --twin: serve frames from the de-twin digital twin

[CSSFrancis]

Adds an option to the simulated DE Server to serve frames from de-twin (on PyPI as de-twin 0.1.0), a digital twin of a Direct Electron camera on a TEM.

pip install "deapi[twin]"
pydeserver --port 13241 --twin --camera DE16 --specimen "Dense Au on holey C"

What changes

• Launcher: pydeserver --twin hands the server to de-twin's deapi face. Any other options go to the twin (--camera, --specimen, --seed, --holder, --soap-port, …).
• What clients get: realistic frames instead of the built-in fake data: a detector model with dark, gain and noise, working references, images that follow a simulated column and specimen, and Instrument … metadata. Clients connect exactly as before (usingMmf = False).
• Packaging: de-twin is a new optional twin extra, limited to Python ≥ 3.10 (de-twin's minimum), so the default install and deapi's Python 3.8 support are unchanged. Without the extra, --twin prints how to install it and exits with code 2.
• The twin can call back into deapi's own server loop (its --deapi-loop option), so --twin is stripped from sys.argv before handing over, to avoid recursion.
• Docs (doc/help/pyDEServer.rst) are updated, and the changelog entries are towncrier fragments (upcoming_changes/59.new_feature.rst, 59.doc.rst).

Tests

New file deapi/tests/test_fake_server/test_twin_server.py:

• Missing twin: without de-twin installed, the flag explains how to get it.
• With de-twin installed: starts python -m deapi.simulated_server.initialize_server <port> --twin --camera DESim, connects a real Client, and checks the sensor size, a rendered (non-constant) 1024² frame and the instrument metadata. It skips when de-twin isn't installed; CI installs only --extra tests, so it skips there unless the CI install adds the twin extra.

Locally with .[tests,twin] on Python 3.12: the full suite as CI runs it gives 51 passed and 128 skipped (the skips need a real DE-Server). test_fake_server alone gives 8 passed.

Example: imaging holes with the digital twin

examples/digital_twin/imaging_holes_with_the_digital_twin_sgskip.py drives the microscope and the camera together:

1. take an atlas at 2000×;
2. find the holes in the holey carbon;
3. move the stage to each hole with de_microscope (the DE-TEM-Channel client) and image it at 8000×.

It runs against pydeserver --twin --soap-port 5002. Against a real instrument only the addresses change.

de_microscope isn't on PyPI, so the gallery shows this example without executing it (_sgskip). The figure it produces is included as doc/_static/digital_twin_holes.png. When I ran it, 9 holes were found and the 4 visited were centred to within about 20 px of a 4096 px frame.

This commit also fixes a bug in the first one: --twin dropped every all-digit option, including the value of --soap-port. Only the leading positional port is removed now, and a new test covers the pass-through.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 57.97101% with 29 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
deapi/tests/test_fake_server/test_twin_server.py	49.09%	28 Missing ⚠️
deapi/simulated_server/initialize_server.py	92.85%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!