Python API Reference¶

SurfCalc can be driven from Python in three ways:

• GUISurfCalcAPI (section 1) — the in-app Engineering Console API, driving a currently loaded/running SurfCalc session (accessed as surfcalc.<method>(...) from View > Engineering Console). Use this to script actions against the project you already have open in the GUI.
• Headless RPC mode (section 2) — for driving SurfCalc from your own external Python process (e.g. an optimization loop) with no GUI window open at all — SurfCalc.exe --serve-stdio plus the companion surfcalc_client package.
• Macro recording (section 3) — GUI actions captured as a replayable script you can re-run later.

Recorded load/calculation actions for the covered modules generate calls into GUISurfCalcAPI, so a recorded macro and a Console command use identical code paths.

Covered modules: Load Case Combination, Influence Matrix, Surface Deformation, Active Optics, and Bending Modes. Image Motion is unreleased and not covered.

1. GUISurfCalcAPI (Engineering Console)¶

Accessed from View > Engineering Console as surfcalc.<method>(...), scripting the currently loaded GUI session rather than an external file.

surfcalc.switch_tab("surface_def")
surfcalc.import_file("csv", "displacements.csv", target="surface_def")
surfcalc.auto_detect_hole_diameter()  # optional; enables mask + fills hole_diam
surfcalc.calculate()

1a. Load Case Combination (switch_tab("load_cases"))¶

Combining a STOP load-case set (gravity + thermal + wind), then fitting it:

surfcalc.switch_tab("load_cases")
surfcalc.import_file("csv", "gravity.csv", target="load_cases")
surfcalc.add_load_case("csv", "thermal.csv")
surfcalc.update_load_case(1, "scale", 0.6)
surfcalc.add_load_case("csv", "wind.csv")
surfcalc.set_combine_mode("rss")
surfcalc.calculate()  # forces a recombine -- the GUI itself recombines live
surfcalc.send_to_surface_deformation()
surfcalc.calculate()  # fits the newly created Surface Deformation instance

2. Headless RPC Mode (--serve-stdio)¶

For driving SurfCalc from your own external Python process — e.g. an optimization loop that calls run_active_optics many times over varying parameters — with no GUI window needed, start SurfCalc in headless RPC mode:

SurfCalc.exe --serve-stdio

This starts no local web server, browser, or webview — it reads one JSON request per line from stdin and writes one JSON response per line to stdout, then exits cleanly on EOF. It is meant to be launched as a subprocess and kept alive for an entire session, not invoked once per call.

Use the companion surfcalc_client package rather than talking to the pipe directly:

from surfcalc_client import SurfCalcSession

with SurfCalcSession(exe_path=r"C:\Program Files\SurfCalc\SurfCalc.exe") as session:
    result = session.run_active_optics(inf_path, target_path, alpha=0.05)
    print(result["rms_residual"])

A failed call raises surfcalc_client.SurfCalcRPCError without ending the session, so one bad call in a parameter sweep doesn't cost you the whole run. One SurfCalcSession = one dedicated SurfCalc subprocess = one warm session (its own startup cost is paid once, not per call); it does not support multiple concurrent clients sharing a single running server. See the package's own README for the full install/usage guide, including a scipy.optimize example.

Licensing in headless mode¶

A headless session enforces the same entitlement gate as the GUI (see Software Licensing), and gets its licence from one of two places.

If you activated SurfCalc through the GUI on this machine, there is nothing to configure. The stored activation is restored automatically at startup, exactly as it is for the desktop app.

That store is per-user, though, so it is often absent on the hosts headless mode is actually for — a service account, a container, a CI runner, or any machine where nobody has opened the GUI. Supply the key through the environment there:

SURFCALC_LICENSE_KEY takes precedence if both are set.

export SURFCALC_LICENSE_KEY="key/eyJhbGci...signature"
python -c "from surfcalc_client import SurfCalcSession; ..."

Three things worth knowing:

• The key is used for that session only. Unlike clicking Activate in the GUI, nothing is written to disk — the environment is already the durable source of the key in a headless deployment, and this avoids leaving a licence file on shared runners.
• Licensing messages go to stderr, never stdout, which belongs exclusively to the JSON protocol. If a session comes up unexpectedly limited, read the subprocess's stderr — it will say why.
• A rejected key never revokes a working activation. If the machine already had a valid stored licence and the variable is wrong, the session keeps its entitled status and logs a warning, rather than dropping to Unlicensed because of a typo.

If neither source yields a valid licence the session still starts — the UI/RPC shell is available — but import and calculate raise with "An active SurfCalc license or trial is required."

session.run_surface_deformation(solver_type, filepath, **kwargs)¶

Reproduces the GUI's surface deformation fit: loads a surface (CSV or FEA result), rotates it into the local surface-normal frame, optionally masks a hole, optionally subtracts rigid body motion (RBM), then runs the selected fit method. Requires an active license or trial (same entitlement gate as the GUI).

Parameters:

[!NOTE] surface_roc's declared unit is genuinely different per function — check the table for whichever one you're calling before assuming it matches another: * run_surface_deformation — units_disp_in * run_active_optics — target_units_coords_in * run_influence_matrix — units_coords_in * run_load_case_sweep — SI meters, always (no unit parameter at all)

surface_conic is always dimensionless.

Returns a dict (shape varies slightly by fit_method, but always includes):

• coefficients — list of {idx, name, value} per fitted term
• z_fit, z_residual — fitted and residual scalar surfaces (as plain lists)
• metrics_fit, metrics_residual — each {pv, rms, mean, std}
• rbm — {tx, ty, tz, rx, ry, rz} fitted rigid body motion
• deform_quantity — "nd" or "uz", matching the argument above
• radial_correction — "none", "linear", or "nonlinear", matching the argument above; when not "none", surface_roc and surface_conic are also echoed back

result = session.run_surface_deformation(
    "csv", "displacements.csv",
    fit_method="circular_zernike",
    zernike_selection="1-15",
    subtract_rbm=True,
)

print(f"Fit RMS: {result['metrics_fit']['rms']}")
print(f"Residual RMS: {result['metrics_residual']['rms']}")
print(f"Fitted RBM: {result['rbm']}")

The input CSV must contain X, Y, Z, UX, UY, UZ columns (optionally NX, NY, NZ, Area).

session.detect_hole_diameter(x, y, *, area=None, units_disp_in="mm") / detect_hole_diameter_from_file(...)¶

Headless twin of the GUI Mask Inner Hole → Auto button. Returns {"diameter", "radius_m", "center", "units_disp_in"} where diameter is in units_disp_in (0.0 when no central hole is found). Pass that diameter into run_surface_deformation(..., mask_hole=True, hole_diam=...) or run_load_case_combination(..., mask_hole=True, hole_diam=...).

hole = session.detect_hole_diameter_from_file("csv", "displacements.csv", units_disp_in="mm")
result = session.run_surface_deformation(
    "csv", "displacements.csv",
    units_disp_in="mm",
    mask_hole=hole["diameter"] > 0,
    hole_diam=hole["diameter"],
)

session.run_load_case_combination(cases, mode="superpose", output_path=None, **kwargs)¶

Combines several load cases into one field — data preparation, not fitting — the headless counterpart of the Load Case Combination module. Fitting the combined result is a separate run_surface_deformation() call (see below); combination and fitting are independent steps, matching the app's own module split.

cases is a list of dicts; only solver_type and filepath are required:

mode is "superpose" (signed vector sum — a realizable deformation state) or "rss" (root-sum-square envelope of the normal displacements — a statistical bound, not a realizable state).

Cases need not share a mesh: the most refined mesh becomes the reference, and every other case is recentred on its own area-weighted centroid and interpolated onto it. The result is a _data-shaped dict (x/y/z/ux/uy/uz/nx/ny/nz/area) plus a provenance key recording the mode, the reference case, and each case's scale, node count, and whether it was interpolated. Pass output_path to also write it as a re-importable CSV (in SI metres).

mask_hole / hole_diam mirror the module's Mask Inner Hole control. hole_diam must be > 0 in units_disp_in (no silent auto-detect; the GUI Auto button fills that field first). Surface nodes are never deleted — only bridging triangles are excluded from area/normals. (hole_points / hole_method / hole_boundary_xyz remain accepted for back-compat and are ignored.)

combined = session.run_load_case_combination(
    [
        {"solver_type": "csv", "filepath": "gravity.csv", "scale": 1.0, "name": "gravity"},
        {"solver_type": "csv", "filepath": "thermal.csv", "scale": 0.6, "name": "thermal"},
    ],
    mode="superpose",
    output_path="combined.csv",
)
print(combined["provenance"])

result = session.run_surface_deformation("csv", "combined.csv", units_disp_in="m", zernike_selection="1-15")
print(f"Residual RMS: {result['metrics_residual']['rms']}")

Load Case Combination requires an active license or trial; the gate is enforced identically here and in the GUI. license_manager is resolved from the process's own licence state and is ignored if sent by a client.

SurfCalcAPI.run_load_case_sweep(cases, *, variables, swept_vars, **kwargs)¶

The headless counterpart of the sidebar's Grid Sweep (from SurfCalcAPI import run_load_case_sweep — reachable over the RPC protocol's raw JSON dispatch too, but not yet wrapped by SurfCalcSession, so it is not available as session.run_load_case_sweep(...) through the shipped client).

cases is shaped like run_load_case_combination's. variables is the full name → value map (fixed values for anything not swept); swept_vars is a list of {"name", "min", "max", "step"} — the Cartesian product is the grid. Every grid point reports combined_rms and combined_pv of the combined field's normal displacement (area-weighted, the same convention Surface Deformation uses for fit residuals). Rows are sorted worst-first by combined_rms; display-side ranking is free to re-sort by any other column.

evaluate ("combined" default, "surface_fit", "active_optics") adds a further analysis step at each grid point — load magnitude and combination are the genuine unknown in a STOP analysis, so this is how a grid point gets judged by what survives a fit or a correction rather than by the raw mechanical deformation:

ao_over_budget is True when at least one actuator command saturates at its configured fmin/fmax — the honest signal that this load case needs more than the actuator can give, since a constrained solve otherwise clips silently and a bare force number would not show the shortfall.

radial_correction, surface_roc, surface_conic ("none", 0.0, 0.0) — see run_surface_deformation's radial_correction entry above for what this does. Applied to the combined field's own normal displacement before either metric is computed, so it affects combined_rms/combined_pv and (for the "active_optics" evaluate stage only — see the unit-convention note below) the corrected result. surface_roc here is SI METERS, not units_disp_in — the combined field this operates on is always metric internally, and there is no separate coordinate-unit parameter on this function to declare it against.

Every grid point's own mesh geometry is identical (only the scale factors, and so ux/uy/uz, vary), so the "active_optics" stage's rigid registration onto the influence matrix mesh runs once for the whole sweep, not once per point.

from SurfCalcAPI import run_load_case_sweep

# Which gravity-angle case needs the biggest actuator command?
result = run_load_case_sweep(
    [{"solver_type": "csv", "filepath": "gravity_case.csv", "scale": 1.0, "scale_expr": "g"}],
    variables={"g": 1.0}, units_disp_in="m",
    swept_vars=[{"name": "g", "min": 0.5, "max": 1.5, "step": 0.25}],
    evaluate="active_optics", ao_inf_filepath="influence_matrix.csv",
    ao_kwargs={"enable_limits": True, "fmin": -0.5, "fmax": 0.5},
)
print(result["rows"][0])  # worst case first

session.run_influence_matrix(checked_entries, optical_set, **kwargs)¶

Reproduces the GUI's influence matrix compile step: compiles an influence matrix from checked FEA result "steps" and requires entitlement, exactly as the GUI does.

Parameters:

Returns a dict shaped like the influence-matrix CSV loader's output: inf_matrix, x, y, z, actuator_ids, n_actuators, n_points. When radial_correction != "none", also includes radial_correction, surface_roc, surface_conic, units_coords_in matching the arguments above.

Raises if the mesh/actuator counts exceed the active tier's limits (see Software Licensing).

session.run_active_optics(inf_filepath, target_filepath, **kwargs)¶

Reproduces the GUI's active optics correction: loads the influence matrix and target, requires entitlement, registers the target onto the influence matrix's mesh frame and resamples it there (raising on incompatible meshes — there's no interactive override in headless mode), then solves.

Parameters:

Returns a dict with:

• forces — actuator forces
• z_fit, z_residual — corrected surface and residual
• radial_correction — matching the argument above; when not "none", surface_roc and surface_conic are also echoed back
• rms_original, pv_original, rms_residual, pv_residual — before/after surface metrics
• correction_factor — % reduction in RMS
• afi — Actuator Fighting Index
• rbm — fitted RBM dict or None
• mesh_compatibility, alignment — diagnostics from the target-registration step

session.run_bending_modes_extract(filepath, **kwargs)¶

Headless twin of Bending Modes Extract Modes (including the FEA load-all-modes step the GUI exposes as Load & Preview Set).

Parameters:

Returns a dict with x, y, z, nx, ny, nz, area, modes, n_modes_extracted, mode_normalization (and mode_labels when the FEA importer provides them).

session.run_sensitivity_matrix(rows, **kwargs)¶

Headless twin of the Sensitivity Matrix tab's Compute Sensitivity Matrix: builds a real first-order (paraxial) rigid-body tilt/decenter → line-of-sight sensitivity matrix from an ordered optical prescription. First-order/paraxial only — no aberration, no despace/clocking sensitivity (both are zero at this order for a rotationally symmetric surface), object at infinity, unfolded train.

Parameters:

Returns a dict with matrix, output_labels (["LOS_X", "LOS_Y"]), surface_labels ("Name:Dof" columns, Dof one of Tx/Ty/Rx/Ry), surface_names, dof_labels, b_coefficients_m, efl_m, back_focal_distance_m, output_units, and prescription (the resolved rows).

session.load_optical_prescription(filepath, *, fmt=None)¶

Headless twin of the Sensitivity Matrix tab's Import from Zemax/CODE V: parses a real Zemax OpticStudio (.zmx) or CODE V (.seq/.len) optical prescription into rows directly passable to run_sensitivity_matrix(). Not licence-gated — a pure parse, same trust boundary as loading a prescription CSV by hand.

Parameters:

Returns (rows, warnings). rows are run_sensitivity_matrix()-ready dicts; check each row's "needs_review" before computing — set when an imported field couldn't be fully resolved (currently: a refractive element, whose focal length isn't derivable from the prescription alone). warnings are human-readable notes about anything reduced during import (e.g. how many mirror-reflection segments were unfolded). Raises ValueError for a non-sequential/NSC file, a coordinate-break/decenter card, or a finite object distance — SurfCalc's paraxial engine supports on-axis, sequential, object-at-infinity trains only.

session.run_image_motion(surfaces, sensitivity_matrix_filepath)¶

Headless twin of the Image Motion tab's Calculate LOS Budget: combines each surface's real deformation with a sensitivity matrix (normally run_sensitivity_matrix()'s output, exported to CSV) into a line-of-sight error budget. Three input shapes are auto-detected from the matrix's own row/column labels: the recommended run_sensitivity_matrix() output ("rigid_body", 2 x 4·n_surfaces, columns Name:Tx/Name:Ty/Name:Rx/Name:Ry); a 6-row per-mirror matrix ("external_6dof", 6 x n_surfaces, rows labeled with the 6 rigid-body DOFs Tx/Ty/Tz/Rx/Ry/Rz or a recognized synonym) as typically exported by a full ray-traced optical model (Zemax/CODE V perturbation analysis) rather than this app's own first-order engine — unlike "rigid_body", this path also reads Tz/Rz (piston/clocking), which a real model can have genuine sensitivity to; and a legacy hand-authored (LOS_X/LOS_Y) x (bare surface name) matrix ("legacy_inplane_rms"), which falls back to reading raw UX/UY RMS for backward compatibility and cannot see a pure rigid-body tilt.

Parameters:

Returns a dict with mode ("rigid_body", "external_6dof", or "legacy_inplane_rms"), contributions (per-surface name, rms_x/rms_y/pv_x/pv_y, signed_x/signed_y, rbm), total_rms_x/total_rms_y/total_rms (RSS across surfaces — a statistical tolerance-budget figure), and total_signed_x/total_signed_y/total_signed (the algebraic sum — the deterministic answer for one FEA load case; None in "legacy_inplane_rms" mode). "external_6dof" has only one output axis (the row axis already IS the 6 DOF, not an output pair), so its rms_y/signed_y/total_rms_y/total_signed_y are always 0.0/None/0.0/None — the real number is carried in the _x fields.

Console / GUI-replay form:

session.run_random_response_budget(mode_basis_filepath, modal_sigma, **kwargs)¶

Headless twin of Random Response Budget's Compute Budget (Modal Random-Response Zernike Budget — see docs/THEORY_MANUAL.md §17 for the math). Unlike a Prepare-stage extraction call, this module performs no mode extraction of its own: mode_basis_filepath is a SurfCalc mode-basis CSV (export_modes_csv's format — typically Bending Modes' own Export Modes CSV output, or run_bending_modes_extract(..., output_path=...)'s). It fits Zernikes to each mode in that basis individually and RSS-combines them using the caller-supplied per-mode σ. SurfCalc never derives σ itself — see the User Guide's Random Response Budget Module for how to obtain it from Nastran/Abaqus/Ansys.

Parameters:

Returns a dict with coefficients (per-term 1-sigma budget), rms_total, rms_captured, rms_residual, orthogonality_closure, envelope_field, monte_carlo (pv_median, pv_p95, pv_over_rms_total, worst_case_shape, seed_used), n_modes_used, and mode_normalization (echoed from the basis, None if it declares none).

Console / GUI-replay form:

surfcalc.compute_random_response_budget()  # <instance label>

session.write_surface_deformation_report(result, filepath, **kwargs)¶

Render a run_surface_deformation() result as a self-contained HTML report — the GUI-free twin of the Surface Deformation tab's Analysis Report (.html) export, using the same renderer (core/report.py) so both writers lay out fit setup, metrics, RBM and coefficients identically. Returns the path written.

Two differences from the GUI export. This function receives only the numeric result dict, not a live 3D viewport, so the report it writes has no Original/Fit/Residual pane images — those only exist in the GUI export, which screenshots the actual on-screen plotters. And it never opens a browser: a script running unattended (a batch job, --serve-stdio) must not pop a window on whatever machine happens to be running it, so launching the file (or not) is left to the caller. The SurfCalc-branded header and everything else match.

res = session.run_surface_deformation("abaqus", "M1_gravity.odb", node_set="OPTICAL")
session.write_surface_deformation_report(res, "M1_gravity_report.html",
                                         units="nm", source="M1_gravity.odb (Abaqus)")

The output is a single file with its CSS inlined, so it survives being mailed on its own. SurfCalc bundles no PDF engine by design — a browser's Print to PDF is the supported route to a PDF deliverable, and the report carries print stylesheet rules for it.

session.write_active_optics_report(result, filepath, **kwargs)¶

Render a run_active_optics() result as a self-contained HTML report — the GUI-free twin of the Active Optics tab's Analysis Report (.html) export, using the same renderer (core/report.py) as write_surface_deformation_report(). Returns the path written.

Same two differences from the GUI export as the Surface Deformation writer: no Target/Fit/Residual/Overlay pane images (this function has no live viewport to screenshot), and it never opens a browser (a script running unattended must not pop a window on whatever machine happens to be running it).

res = session.run_active_optics("inf_matrix.csv", "target.odb", target_solver_type="abaqus")
session.write_active_optics_report(res, "M1_correction_report.html",
                                   units="nm", actuator_type="force", actuator_unit="N")

surfcalc.switch_tab("bending_modes")
surfcalc.import_file("csv", "modes.csv", target="bending_modes", units_coords="m")
surfcalc.calculate()  # Extract Modes
# FEA path: calculate() auto-loads a keyword-matched optical node set.
# Call load_bm_preview_set() first only when the selected set is Default
# (All nodes) or otherwise unmatched.
# surfcalc.load_bm_preview_set()
# surfcalc.calculate()

3. Macro Recording¶

Macro > Record Macro... captures GUI actions as a replayable Python script calling into GUISurfCalcAPI, that you can re-run later via Macro > Run Script... or the Engineering Console. See Macro Recording & Automation Script Export in the User Guide for how to record, edit, and re-run one.