{
    "cells": [
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "# System Diagnostics Demo"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "`optiland.diagnostics.check_system` inspects an `Optic` and reports the mistakes newcomers hit most often — a missing wavelength, an undefined aperture, a stop that was never marked — each with the offending object and a runnable fix. It never modifies the lens it inspects, so it is safe to call at any point while building a system.\n",
                "\n",
                "See the [Conventions](../../conventions.rst) page for the concepts these checks refer to."
            ]
        },
        {
            "cell_type": "code",
            "execution_count": 1,
            "metadata": {},
            "outputs": [],
            "source": [
                "from optiland.diagnostics import check_system\n",
                "from optiland.optic import Optic"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "### A lens with a few surfaces, but nothing else defined yet"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": 2,
            "metadata": {},
            "outputs": [
                {
                    "data": {
                        "text/html": [
                            "<table><thead><tr><th>Severity</th><th>Code</th><th>Where</th><th>Message</th><th>Fix</th></tr></thead><tbody><tr><td style=\"color:#c0392b;font-weight:bold;\">error</td><td>OPT001</td><td></td><td>No wavelengths are defined on the optical system.</td><td><code>lens.wavelengths.add(value=0.55, is_primary=True)</code> &middot; <a href=\"https://www.optiland.org/docs/conventions.html#opt001\">docs</a></td></tr><tr><td style=\"color:#c0392b;font-weight:bold;\">error</td><td>OPT003</td><td></td><td>No aperture is defined on the optical system.</td><td><code>lens.set_aperture(aperture_type=\"EPD\", value=25)</code> &middot; <a href=\"https://www.optiland.org/docs/conventions.html#opt003\">docs</a></td></tr><tr><td style=\"color:#c0392b;font-weight:bold;\">error</td><td>OPT004</td><td></td><td>No stop surface is defined.</td><td><code>lens.surfaces.add(..., is_stop=True) on the aperture surface</code> &middot; <a href=\"https://www.optiland.org/docs/conventions.html#opt004\">docs</a></td></tr><tr><td style=\"color:#c0392b;font-weight:bold;\">error</td><td>OPT006</td><td></td><td>No fields are defined on the optical system.</td><td><code>lens.fields.add(y=0)</code> &middot; <a href=\"https://www.optiland.org/docs/conventions.html#opt006\">docs</a></td></tr></tbody></table>"
                        ],
                        "text/plain": [
                            "DiagnosticReport(errors=4, warnings=0)"
                        ]
                    },
                    "execution_count": 2,
                    "metadata": {},
                    "output_type": "execute_result"
                }
            ],
            "source": [
                "lens = Optic()\n",
                "lens.surfaces.add(index=0, thickness=100)\n",
                "lens.surfaces.add(index=1, radius=20, thickness=10, material=\"N-SF11\")\n",
                "lens.surfaces.add(index=2, thickness=40)\n",
                "lens.surfaces.add(index=3)\n",
                "\n",
                "report = check_system(lens)\n",
                "report"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "Each finding names the fix as a runnable line of code. `report.ok` is `False` while any error-severity finding remains:"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": 3,
            "metadata": {},
            "outputs": [
                {
                    "data": {
                        "text/plain": [
                            "False"
                        ]
                    },
                    "execution_count": 3,
                    "metadata": {},
                    "output_type": "execute_result"
                }
            ],
            "source": [
                "report.ok"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "### Applying the suggested fixes"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": 4,
            "metadata": {},
            "outputs": [
                {
                    "data": {
                        "text/html": [
                            "<p><strong>DiagnosticReport:</strong> no issues found.</p>"
                        ],
                        "text/plain": [
                            "DiagnosticReport(errors=0, warnings=0)"
                        ]
                    },
                    "execution_count": 4,
                    "metadata": {},
                    "output_type": "execute_result"
                }
            ],
            "source": [
                "lens.surfaces.surfaces[1].is_stop = True\n",
                "lens.set_aperture(aperture_type=\"EPD\", value=25)\n",
                "lens.fields.add(y=0)\n",
                "lens.wavelengths.add(value=0.55, is_primary=True)\n",
                "\n",
                "report = check_system(lens)\n",
                "report"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": 5,
            "metadata": {},
            "outputs": [
                {
                    "data": {
                        "text/plain": [
                            "True"
                        ]
                    },
                    "execution_count": 5,
                    "metadata": {},
                    "output_type": "execute_result"
                }
            ],
            "source": [
                "report.ok"
            ]
        }
    ],
    "metadata": {
        "kernelspec": {
            "display_name": ".venv",
            "language": "python",
            "name": "python3"
        },
        "language_info": {
            "codemirror_mode": {
                "name": "ipython",
                "version": 3
            },
            "file_extension": ".py",
            "mimetype": "text/x-python",
            "name": "python",
            "nbconvert_exporter": "python",
            "pygments_lexer": "ipython3",
            "version": "3.13.2"
        }
    },
    "nbformat": 4,
    "nbformat_minor": 2
}