relay-analysis

MATLAB/ZOS-API relay-screening and triage pipeline for the TCABR multichannel spectrometer upgrade.

replot-relay.m's Overlay (Comparison) output for all 10 relays bundled in examples/ — full-resolution vector version: RelayComparison.pdf (a MATLAB .fig is also included there for interactive re-exploration).

Overview

This repository contains the MATLAB/ZOS-API screening infrastructure used in "Design and Optomechanical Optimization of a High-Resolution Multichannel Spectrometer for Plasma Rotation Measurements in the TCABR Tokamak" (Novaes & Severo, submitted 2026) to evaluate candidate optical relay topologies for the TCABR multichannel spectrometer upgrade. It reproduces Table II and Figure 3 of that work: ten achromatic-doublet and singlet relays are ray-traced across all 11 detector channels and compared on throughput, spectral resolution, Doppler-shift stability and spatial crosstalk, from which the adopted design (254-Doublet-050-125) was selected.

The Problem Solved

Screening a dozen candidate relay topologies against four partly conflicting metrics — throughput, resolution, Doppler stability, crosstalk — across 11 field points each would mean re-running four separate OpticStudio analyses per relay per channel and manually transcribing the results to compare designs: slow, repetitive, and easy to get subtly wrong. run-relay.m automates that extraction (in parallel, across as many relay files as you point it at); replot-relay.m then lets you re-triage and re-plot any subset of the results as many times as you like, without touching OpticStudio again.

Requirements

To reproduce Table II / Figure 3 from the bundled examples — MATLAB only:

• MATLAB (tested version noted once pinned). No OpticStudio install or licence needed for this path — it is the one most people following the paper's citation will actually want.

To run the full screening engine (run-relay.m) against your own or the original relay files:

• MATLAB, plus a licensed Ansys Zemax OpticStudio install.
• A MATLABZOSConnection.m connector on the MATLAB path. OpticStudio generates this file itself — it is not part of this repository. In OpticStudio: open the Programming tab, arm the Interactive Extension, then Programming → ZOS-API.NET Application Builders → MATLAB → Interactive Extension. This writes MATLABZOSConnection.m to your local {Zemax}\ZOS-API Projects\MATLABZOSConnection\ folder and opens it in MATLAB — run it once per session to obtain TheApplication.

How to Use

Path A — Reproduce from the bundled examples (recommended, no OpticStudio)

1. Open MATLAB in this repository and run replot-relay.m.
2. In the file picker, navigate to examples/ and select all ten Data_S2_SEQ_*.mat files at once (multi-select).
3. Choose Overlay (Comparison) when prompted.
4. The figure above is reproduced on screen, saved as examples/Multiple_Relay_Comparison.pdf, and a master table (the numbers behind Table II) is printed to the MATLAB console, ready to paste into a spreadsheet.

Two of the ten relays also ship with their full Zemax model (.zmx/.cfg/.zda) for inspection directly in OpticStudio: the simplest screened design (254-Singlet-PlanConv-040-100) and the architecture adopted in the paper (254-Doublet-050-125).

Path B — Run the full engine (requires OpticStudio + licence)

1. Open a candidate relay's .zmx/.zos file in OpticStudio and arm the Interactive Extension (for a single interactive check), or have a folder of relay files ready (for a batch run).
2. Run run-relay.m in MATLAB and choose Interactive (Current File) to analyze the system already open in OpticStudio, or Brute Force (Parallel Batch) to recursively analyze every .zmx/.zos file under a folder you select.
3. Each relay gets a Data_<relay>.mat cache and a Resultados_<relay>.pdf four-panel figure next to its model file — feed those into Path A's replot-relay.m step to triage them.

Full .zmx models for all ten screened variants (beyond the two bundled above, ~20 MB compressed): Zenodo data deposit, DOI 10.5281/zenodo.22678687.

Repository Structure

relay-analysis/
├── run-relay.m          # Script 1: ZOS-API screening engine (needs OpticStudio)
├── replot-relay.m       # Script 2: triage/plotting from .mat caches (MATLAB only)
├── examples/
│   ├── Data_S2_SEQ_*.mat                        # results for all 10 screened relays
│   ├── RelayComparison.png / .pdf / .fig        # the Overlay figure above
│   ├── S2_SEQ_254-Singlet-PlanConv-040-100-2.5/ # full Zemax model, simplest design
│   └── S2_SEQ_254-Doublet-050-125-2.5/          # full Zemax model, adopted design
├── LICENSE
├── CITATION.cff
└── README.md

How to Cite

Please cite both the paper this code supports and the software itself.

The paper:

@article{Novaes2026_Spectrometer,
  author  = {Novaes, Douglas O. and Severo, Jos\'{e} H. F.},
  title   = {Design and Optomechanical Optimization of a High-Resolution
             Multichannel Spectrometer for Plasma Rotation Measurements
             in the TCABR Tokamak},
  journal = {Review of Scientific Instruments},
  year    = {2026},
  doi     = {[DOI of the paper — placeholder until acceptance]}
}

This software:

@software{Novaes2026_RelayAnalysis,
  author  = {Novaes, Douglas O. and Severo, Jos\'{e} H. F.},
  title   = {relay-analysis: ZOS-API relay screening pipeline for the
             TCABR spectrometer upgrade},
  year    = {2026},
  version = {v1.0.1},
  doi     = {10.5281/zenodo.22675399},
  url     = {https://github.com/dougnovaes/relay-analysis}
}

The dataset (full Zemax models for all ten screened relays):

@dataset{Novaes2026_RelayDataset,
  author  = {Novaes, Douglas O. and Severo, Jos\'{e} H. F.},
  title   = {relay-analysis screened relay dataset: ten candidate
             optical relay Zemax models and ray-trace results for the
             TCABR spectrometer upgrade},
  year    = {2026},
  doi     = {10.5281/zenodo.22678687},
  url     = {https://doi.org/10.5281/zenodo.22678687}
}

See also CITATION.cff, which GitHub and Zenodo read automatically to populate citation metadata — the author, title and version there are kept in sync with the BibTeX above.

License

MIT — see LICENSE.