# Run a circuit from Python with josimpro

Make the matching josimpro extension importable, construct Input and Matrix from a saved circuit, validate readiness and execute Simulation.

## Compatibility

2.9.0 release target; source-documentation evidence

Published guidance with release-applicability limits. Confirm package applicability before following this guide.

## Before starting

Matching compiled Python module/interpreter, valid licence and complete writable circuit/dependencies

## Steps

1. Use the compiled josimpro module from the intended installation and a compatible Python environment. The supplied install helper creates a user-site .pth entry; custom layouts can use PYTHONPATH.
2. Inspect jp.VERSION, jp.BUILD_TIMESTAMP and jp.GIT_HASH, and use jp.core_identity_json() when you need the actually loaded core identity. The 2.9 version label alone does not identify a particular module/core payload.
3. Configure the issued licence path through jp.Settings.license when the default is unsuitable; never embed licence contents in a script or report.
4. Load a copied complete circuit using Input, construct Matrix, validate simulation readiness and execute Simulation as below.
5. Check sim.isSimOK, run feedback and the requested outputs before consuming numerical results.

## Documented example

```text
import os
import sys
from pathlib import Path

# Windows default install: this changes only the current Python process.
if os.name == "nt":
    bin_dir = Path(os.environ["ProgramFiles"]) / "SUN Magnetics" / "JoSIM-Pro" / "bin"
    dll_directory = os.add_dll_directory(str(bin_dir))
    sys.path.insert(0, str(bin_dir))

import josimpro as jp

print(jp.VERSION, jp.BUILD_TIMESTAMP, jp.GIT_HASH)
# Set jp.Settings.license to your issued licence path if required.
inp = jp.Input("JTL_Example.cir")
mat = jp.Matrix(inp)
mat.validate_simulation_ready()
sim = jp.Simulation(mat)
sim.simulate(mat)
print("Simulation OK:", sim.isSimOK)
print("Accepted steps:", sim.stepCount)
```

## Check the result

The loaded module is the intended build, readiness succeeds and sim.isSimOK reports success for the intended circuit.

VAL-012 exercised the documented file-based run on the recorded Windows review module. Other interpreter/platform combinations, final-package applicability and physical accuracy remain to be checked.

## If the problem remains

If import fails, check the interpreter compatibility and module directory. If simulation fails, retain the traceback and relevant diagnostic, then check the same circuit/dependencies with the matching CLI.

## Sources and verification details

Recorded inputs/builds only. Complete walkthrough and final-package acceptance remain separate.

- VAL-012: JoSIM-Pro 2.9.0 Windows review runtime; CPython 3.13.11 and NumPy 2.5.4 in an isolated environment. Packaged JTL through Python Input/Matrix/Simulation, raw and named arrays, formatted output axis and CSV writer; the same current CLI produced exactly matching parsed CSV Execution, finite data, shape/time coverage and same-engine interface agreement. No independent physical reference, convergence, GUI, other interpreter/platform or final-release qualification.


- josim-pro:docs/manual_source/sections/python.tex: Making the module available; Process-wide settings and licensing; Smallest useful file-based run
- owner:technical-review-20261102: Owner selected 2.9 as the publication target; final package checks remain required
- validation:windows-workflows-20261103: VAL-011/VAL-012; exact route, runtime and evidence limits

- The Windows process-local module/DLL search setup and file-based simulation were exercised without changing global Python or licence configuration. The default installation path must be adjusted for a custom install.
- The installed module and loaded core identities were checked. This is one CPython/platform combination, not all Python or final-release qualification.

## Related guides

- [Run JoSIM®-Pro from the command line and save numerical output](/knowledge-base/josim-cli-output)
- [Understand Python Runtime defaults and netlist overrides](/knowledge-base/josim-runtime-precedence)
- [JoSIM®-Pro reports a licensing problem or degraded mode](/knowledge-base/josim-licensing-unavailable)