{"sections":[{"heading":"Before starting","paragraphs":["Use a compiled josimpro extension matching your Python version, architecture and JoSIM-Pro installation, plus a valid licence and complete writable example. The checked path used Windows x64, CPython 3.13.11 and NumPy 2.5.4.","NumPy is needed for these array operations. It was installed in an isolated workspace environment; global Python and licence configuration were preserved. Copy the complete supplied JTL example before running."]},{"code":"python -m venv .venv\n.venv\\Scripts\\python.exe -m pip install numpy\n.venv\\Scripts\\python.exe read_jtl.py","heading":"Windows environment example","paragraphs":["Use a compatible installed Python for the environment below, then run your saved script with that environment’s interpreter. The Python example uses the default Windows application bin directory; adjust it for a custom install."]},{"code":"import os\nimport sys\nfrom pathlib import Path\n\n# Windows default install: this changes only the current Python process.\nif os.name == \"nt\":\n    bin_dir = Path(os.environ[\"ProgramFiles\"]) / \"SUN Magnetics\" / \"JoSIM-Pro\" / \"bin\"\n    dll_directory = os.add_dll_directory(str(bin_dir))\n    sys.path.insert(0, str(bin_dir))\n\nimport josimpro as jp\nimport numpy as np\n\nprint(jp.VERSION, jp.BUILD_TIMESTAMP, jp.GIT_HASH)\n# Set jp.Settings.license to your issued licence filename only if required.\ninp = jp.Input(\"JTL_Example.cir\")\nmat = jp.Matrix(inp)\nmat.validate_simulation_ready()\nsim = jp.Simulation(mat)\nsim.simulate(mat)\nif not sim.isSimOK:\n    raise RuntimeError(\"Read the simulation diagnostic before using results\")\n\nraw_time = sim.results.get_time()\nraw_state = sim.results.get_x_full(mat)\nout = jp.Output(inp, mat)\nout.format_time_vector(sim.results, mat)\nout.compute_all_print_values(mat)\noutput_time = np.asarray(out.time, dtype=float)\ntraces = {p.name: np.asarray(p.values, dtype=float)\n          for p in out.plist if not p.hidden}\nassert all(values.shape == output_time.shape for values in traces.values())\nprint(\"Raw shapes:\", raw_time.shape, raw_state.shape)\nprint(\"Named shapes:\", {name: values.shape for name, values in traces.items()})\nout.print_CSV_DAT(',', \"jtl_python.csv\", mat)\n","heading":"Read arrays and write named output","steps":["Load the saved JTL circuit, validate the matrix and run the simulation.","For raw state, keep results.get_time() with results.get_x_full(matrix). Rows follow internal matrix ordering and need their own quantity interpretation.","Build Output, format its time vector and compute the print list. Use out.time with the visible out.plist values; do not assume the formatted output axis is always the accepted-solver time axis.","Write CSV to a separate filename and inspect its headers, units, finite values and time coverage."]},{"heading":"Check the result","paragraphs":["For the checked packaged JTL, raw time and formatted output time each had 1,001 samples over 0–250 ps. The raw state shape was (12, 1001); four visible named traces each had 1,001 finite values. These dimensions describe that example and run settings, not every circuit.","The same current CLI and Python paths produced exactly equal parsed CSV for the unchanged JTL example. This is same-engine interface agreement, not an independent physical-accuracy or convergence check.","Time is in seconds. Preserve the named signal quantities: the JTL V(...) traces are voltages and P(...) traces are physical phase in radians. Do not label every raw state row as voltage or treat phase values as cycles."]},{"heading":"Keep independent array snapshots","paragraphs":["In the reviewed maintained Python binding, results.get_time() and results.get_x_full(matrix) allocate owning, writable float64 NumPy arrays and copy the native samples. Changing these arrays does not edit the native result. A returned snapshot remains independent of a later rerun or owner destruction; keep the native objects alive while making the call itself.","Each call copies its selected data, so repeated snapshots consume additional memory. get_x_full(matrix) uses matrix.relevant when pruning is active; its first dimension is the exposed subset, not necessarily every matrix column. Keep the matching quantity/index interpretation or use the named print-list route.","This ownership explanation follows the current binding implementation and method contract. The earlier VAL-012 numerical comparison retains its recorded review-module identity; no current-module owner-destruction or rerun test is added by this source review."]},{"heading":"If the problem remains","paragraphs":["If NumPy is missing, install it in the environment that runs the script. If josimpro cannot import, check the interpreter/extension compatibility and intended module/DLL directory before running a simulation.","Use jp.core_identity_json() to inspect the actually loaded core when versions or library paths are uncertain. Keep native owners valid while making native calls; do not replace a loaded binary during the process.","For missing dependencies or a licence failure, use the exact diagnostic and compare the same saved circuit with the matching CLI. Use a new output filename and preserve the source files."]},{"heading":"Choose the analysis-specific result type","paragraphs":["The worked array/output example here is transient and uses seconds. OP results are scalars, DC uses its swept source values and volts or amperes as the horizontal axis, and AC retains complex values against frequency in hertz. Use the dedicated static/DC and AC guides for those output contracts. Match values to their declared axis metadata before processing or plotting them."]}],"canonical_url":"https://www.sun-magnetics.com/knowledge-base/josim-api-output","url":"/knowledge-base/josim-api-output","known_issues":[],"search_record":{"execution":true,"relatedProducts":[],"version_tags":["JoSIM-Pro 2.9 target"],"text":"Read named waveform arrays and export CSV from Python Use Results for stored solver-state arrays and Output for named traces and their formatted time axis. Keep each set of values with its matching axis before exporting or plotting. JoSIM-Pro 2.9.0 release target; bounded Windows CLI/Python evidence How to python numpy arrays waveform raw state matrix named traces formatted time csv output Before starting Use a compiled josimpro extension matching your Python version, architecture and JoSIM-Pro installation, plus a valid licence and complete writable example. The checked path used Windows x64, CPython 3.13.11 and NumPy 2.5.4. NumPy is needed for these array operations. It was installed in an isolated workspace environment; global Python and licence configuration were preserved. Copy the complete supplied JTL example before running.  Windows environment example Use a compatible installed Python for the environment below, then run your saved script with that environment’s interpreter. The Python example uses the default Windows application bin directory; adjust it for a custom install. python -m venv .venv\n.venv\\Scripts\\python.exe -m pip install numpy\n.venv\\Scripts\\python.exe read_jtl.py Read arrays and write named output Load the saved JTL circuit, validate the matrix and run the simulation. For raw state, keep results.get_time() with results.get_x_full(matrix). Rows follow internal matrix ordering and need their own quantity interpretation. Build Output, format its time vector and compute the print list. Use out.time with the visible out.plist values; do not assume the formatted output axis is always the accepted-solver time axis. Write CSV to a separate filename and inspect its headers, units, finite values and time coverage. import os\nimport sys\nfrom pathlib import Path\n\n# Windows default install: this changes only the current Python process.\nif os.name == \"nt\":\n    bin_dir = Path(os.environ[\"ProgramFiles\"]) / \"SUN Magnetics\" / \"JoSIM-Pro\" / \"bin\"\n    dll_directory = os.add_dll_directory(str(bin_dir))\n    sys.path.insert(0, str(bin_dir))\n\nimport josimpro as jp\nimport numpy as np\n\nprint(jp.VERSION, jp.BUILD_TIMESTAMP, jp.GIT_HASH)\n# Set jp.Settings.license to your issued licence filename only if required.\ninp = jp.Input(\"JTL_Example.cir\")\nmat = jp.Matrix(inp)\nmat.validate_simulation_ready()\nsim = jp.Simulation(mat)\nsim.simulate(mat)\nif not sim.isSimOK:\n    raise RuntimeError(\"Read the simulation diagnostic before using results\")\n\nraw_time = sim.results.get_time()\nraw_state = sim.results.get_x_full(mat)\nout = jp.Output(inp, mat)\nout.format_time_vector(sim.results, mat)\nout.compute_all_print_values(mat)\noutput_time = np.asarray(out.time, dtype=float)\ntraces = {p.name: np.asarray(p.values, dtype=float)\n          for p in out.plist if not p.hidden}\nassert all(values.shape == output_time.shape for values in traces.values())\nprint(\"Raw shapes:\", raw_time.shape, raw_state.shape)\nprint(\"Named shapes:\", {name: values.shape for name, values in traces.items()})\nout.print_CSV_DAT(',', \"jtl_python.csv\", mat)\n Check the result For the checked packaged JTL, raw time and formatted output time each had 1,001 samples over 0–250 ps. The raw state shape was (12, 1001); four visible named traces each had 1,001 finite values. These dimensions describe that example and run settings, not every circuit. The same current CLI and Python paths produced exactly equal parsed CSV for the unchanged JTL example. This is same-engine interface agreement, not an independent physical-accuracy or convergence check. Time is in seconds. Preserve the named signal quantities: the JTL V(...) traces are voltages and P(...) traces are physical phase in radians. Do not label every raw state row as voltage or treat phase values as cycles.  Keep independent array snapshots In the reviewed maintained Python binding, results.get_time() and results.get_x_full(matrix) allocate owning, writable float64 NumPy arrays and copy the native samples. Changing these arrays does not edit the native result. A returned snapshot remains independent of a later rerun or owner destruction; keep the native objects alive while making the call itself. Each call copies its selected data, so repeated snapshots consume additional memory. get_x_full(matrix) uses matrix.relevant when pruning is active; its first dimension is the exposed subset, not necessarily every matrix column. Keep the matching quantity/index interpretation or use the named print-list route. This ownership explanation follows the current binding implementation and method contract. The earlier VAL-012 numerical comparison retains its recorded review-module identity; no current-module owner-destruction or rerun test is added by this source review.  If the problem remains If NumPy is missing, install it in the environment that runs the script. If josimpro cannot import, check the interpreter/extension compatibility and intended module/DLL directory before running a simulation. Use jp.core_identity_json() to inspect the actually loaded core when versions or library paths are uncertain. Keep native owners valid while making native calls; do not replace a loaded binary during the process. For missing dependencies or a licence failure, use the exact diagnostic and compare the same saved circuit with the matching CLI. Use a new output filename and preserve the source files.  Choose the analysis-specific result type The worked array/output example here is transient and uses seconds. OP results are scalars, DC uses its swept source values and volts or amperes as the horizontal axis, and AC retains complex values against frequency in hertz. Use the dedicated static/DC and AC guides for those output contracts. Match values to their declared axis metadata before processing or plotting them. ","id":"josim-api-output","keywords":"python numpy arrays waveform raw state matrix named traces formatted time csv output","kind":"How to","title":"Read named waveform arrays and export CSV from Python","product":"JoSIM-Pro"},"version":"2.9.0 release target; bounded Windows CLI/Python evidence","id":"josim-api-output","related":["/knowledge-base/josim-python-first-run","/knowledge-base/josim-cli-output","/knowledge-base/josim-runtime-precedence","/knowledge-base/josim-dc-op","/knowledge-base/josim-ac-analysis"],"downloads":[],"publication_status":"published","numerical_output":null,"provenance":{"execution_checks":[{"routes":["cli","python-api"],"scope":"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","result":"passed","articles":["josim-first-jtl","josim-cli-output","josim-python-first-run","josim-api-output"],"purpose":"python-first-run-and-output","version":"JoSIM-Pro 2.9.0 Windows review runtime; CPython 3.13.11 and NumPy 2.5.4 in an isolated environment","id":"VAL-012","records":["python-jtl-first-run","python-parity-cli"],"limit":"Execution, finite data, shape/time coverage and same-engine interface agreement. No independent physical reference, convergence, GUI, other interpreter/platform or final-release qualification.","observed":{"named_csv_shape_and_time_coverage":true,"samples":1001,"time_start_seconds":0,"named_traces":4,"documented_first_run_completed":true,"raw_state_shape":[12,1001],"accepted_steps_reported":true,"installed_inputs_module_and_core_unchanged":true,"time_end_seconds":2.5e-10,"four_finite_named_trace_arrays":true,"formatted_axis_matches_named_trace_lengths":true,"cli_and_python_csv_exactly_agree":true,"raw_time_and_state_arrays":true,"intended_loaded_core":true,"intended_python_module":true}}],"figure_evidence":[],"review_notes":["The maintained Python binding explicitly exposes Output.time and plist. VAL-012 checked these paths on the recorded Windows review runtime. Final distributed 2.9 package and other-platform/interpreter acceptance remain pending.","4 November targeted UTF-8 path delta review: current binding/input changes preserve this guide's ASCII named-output or subcircuit/default claims. Retained execution predates these changes; Unicode input/path and final-package execution are not qualified. Evidence: validation/source-review-python-paths-20261104.json."],"scope":"Recorded inputs/builds only. Complete walkthrough and final-package acceptance remain separate.","verification_requirements":{"gui_method":"not-required-for-this-answer","illustrations":"not-required-for-this-answer","required":["technical-review","release-applicability","execution","numerical-interpretation"],"status":"review-incomplete"},"sources":[{"id":"josim-pro:docs/manual_source/sections/python.tex","section":"Reading raw arrays; named traces; explicit output writers"},{"id":"josim-pro:lib/python/bindings.cpp","section":"Output format_time_vector, compute_all_print_values, print_CSV_DAT, plist and time"},{"id":"validation:windows-workflows-20261103","section":"VAL-012: arrays, time axes, named traces and CLI/Python CSV agreement"},{"id":"josim-pro:docs/manual_source/sections/syntax.tex","section":"Static operating point, Circuit DC sweeps and Small-signal AC result/axis contracts; separate from the transient recipe"}]},"title":"Read named waveform arrays and export CSV from Python","type":"How to","markdown_url":"/_functions/kbResource?path=markdown%2Fjosim-api-output.md","summary":"Use Results for stored solver-state arrays and Output for named traces and their formatted time axis. Keep each set of values with its matching axis before exporting or plotting.","product":"JoSIM-Pro"}