Optical design, simulation, and a path to real hardware.
English · 简体中文
Build optical systems, simulate light propagation, and explore the results on your own computer. OS Optics combines a catalog of optical components, deterministic physics, structured scientific results, and an interactive 3D view in one Python package. Use it directly or through your own coding agent.
When a design is ready, continue to OpenSci for optical components, assembly configurations, and hardware orders.
Agent guide · Get started · User guide · PyPI · Website · Feedback
| Name | Where | Contents |
|---|---|---|
os-optics |
PyPI | The engine: optical catalog, simulation, results and 3D view |
os-optics-kit |
PyPI | Tools, cases and agent skills built on the engine |
os-optics |
GitHub | This repository: product documentation and feedback |
os-optics-kit |
GitHub | Community repository: tools, cases, skills and contributions |
Install the engine with python -m pip install "os-optics[protected]". Browse worked cases
and tools in os-optics-kit. This documentation
describes os-optics 0.13.0, the release recorded in engine-baseline.json.
| Design | Simulate | Explore | Build |
|---|---|---|---|
| Find optics and define positions, sources, and targets | Trace rays, propagate Gaussian beams, evaluate polarization and interference, and analyze image quality, ghosts and cavities | Inspect a 3D scene, compare target values, and export scientific data | Select components and request a hardware configuration and order |
- Local computation: run on Windows, macOS, or Linux with Python 3.11+.
- Reproducible projects: preserve engine identity, catalog versions, numerical settings, and result hashes.
- Scientific outputs: examine observation planes, beam states, ray paths, power budgets, and wavefront data.
- Optical analyses: vector focal fields, point spread function and MTF, ghost images, cavity modes, and several configurations of one design side by side.
- Python and CLI: integrate into notebooks, scripts, parameter studies, and agent workflows.
- Connected hardware workflow: continue from local design to purchasing and assembly through OpenSci.
python -m pip install "os-optics[protected]"
os-optics doctorPrefer an isolated command-line tool? Use uv tool install "os-optics[protected]".
See the installation guide for virtual environments and upgrades.
Tools, cases and agent skills install with python -m pip install os-optics-kit.
Up to 0.9.0 the package was published as opensci-engine; an installation under that name
takes the same python -m pip install --upgrade "os-optics[protected]", then uses the
os-optics command and import os_optics. A uv tool installation under the earlier name
installs the new one with uv tool install "os-optics[protected]", then uses os-optics.
os-optics catalog sync
os-optics project example --kind beam_expander > project.json
os-optics project run project.json --out-dir run
os-optics view runThe first command downloads the current optical catalog. The example creates a two-lens beam expander; the run produces simulation results, a Local Validation record, and a 3D scene. The viewer opens locally in your browser.
For Windows PowerShell 5.1, create the JSON file with os-optics project example --kind beam_expander | Out-File -Encoding utf8 project.json.
Inspect and export the same run:
os-optics results describe run
os-optics export arrivals run --format csv --out arrivals.csv
os-optics project verify runfrom os_optics.local import example_project_of_kind, run_optical_project
from os_optics.results import load_run
project = example_project_of_kind("beam_expander")
run = run_optical_project(project, output_dir="run-python")
print(run.status.value)
results = load_run("run-python")
print(results.power_budget())Worked cases such as the beam expander and ideal-lens focus are in os-optics-kit, each with its Project, verified target outcomes and run instructions.
| Guide | English | 简体中文 |
|---|---|---|
| Installation and upgrades | Read | 阅读 |
| Your first optical design | Read | 阅读 |
| Catalog and reproducible projects | Read | 阅读 |
| Results, visualization, and export | Read | 阅读 |
| From design to hardware | Read | 阅读 |
| Design studies: edits, sweeps, comparisons, sensitivity, tolerance, and three optical workflows (os-optics-kit) | Read | 阅读 |
| Measurement cleaning, fitting, and reference normalization (os-optics-kit) | Read | 阅读 |
| External scientific tools (os-optics-kit) | Read | 阅读 |
Each case in os-optics-kit states the engine and catalog releases it was verified with; the external-tool cases cover optimization, diffraction, quantum photonics and metasurface components. Find available package versions in the PyPI release history.
Questions, bug reports, and documentation improvements are welcome in English or Chinese. Open an issue or send a documentation pull request. Share cases, tools and skills through os-optics-kit, where your agent can package a finished design as a case pull request.
The documentation and scripts in this repository are available under the MIT License. The OpenSci and OS Optics names are trademarks; the logo and brand artwork in assets/ are also trademarks and are excluded from that licence (assets/LICENSE, TRADEMARK.md). The os-optics engine distributed on PyPI remains under the OpenSci Engine License, and os-optics-kit remains under the MIT License.