PSIM Python API Documentation

File: Psim_Class.py
Author: Altair Engineering Inc.
Requires: PSIM 2026.0 or above (some functions available from earlier versions as noted)

Overview
Installation & Setup
Data Classes
PSIM Class — Main API
Version Compatibility Reference
Usage Examples

Overview

Psim_Class.py is a Python wrapper around PSIM's native DLL (psim2.dll on Windows, psim2.so on Linux). It allows you to automate PSIM simulations, manipulate schematics, read/write graph files, run scripts, and more — all from Python.

Installation & Setup

Requirements

Python 3.x
PSIM 2026.0 or above installed (some features work with 2023.1+)
Windows or Linux

Importing

from Psim_Class import PSIM, PSIM_SimulateData

Creating the PSIM object

# Auto-detect PSIM path from Windows registry
psim = PSIM("")

# Or specify path explicitly
psim = PSIM(r"C:\Altair\PSIM2026\")

# With a custom stdout callback
def my_callback(message, msg_type, thread_id):
    print(f"[{thread_id}] {message.decode()}")

psim = PSIM(r"C:\Altair\PSIM2026\", callback_func1=my_callback)

Note: On Windows, if PsimPath is empty (""), the path is read automatically from the registry key HKCU\SOFTWARE\POWERSIM\Folders64\LASTPATH.

Data Classes

PSIM_curve

Represents a single simulation curve (waveform).

Attribute	Type	Description
`Name`	`str`	Name of the curve/probe
`Rows`	`int`	Number of data points
`Values`	`ctypes pointer`	Raw array of `double` values
`Validate`	`ctypes pointer`	Validity flags per sample (`0`=missing, `1`=valid, `2`=invalid)

Accessing values:

curve = result.Graph[0]          # by index
curve = result.Graph['V_out']     # by name
value = curve[10]                 # 10th sample value
is_valid = curve.is_valid(10)     # check validity
count = len(curve)                # number of samples

PSIM_Graph

Container for all curves from a simulation or graph file.

Attribute	Type	Description
`curves`	`list[PSIM_curve]`	Ordered list of all curves
`Result`	`int`	Result code
`IsError`	`int`	Error flag
`ErrorMessage`	`str`	Error description

Accessing curves:

graph = result.Graph
curve0 = graph[0]           # by position
curve  = graph['Ia']        # by name
exists = 'Vbus' in graph    # membership check
val    = graph.get_value('Ia', 5, require_valid=True)

PSIM_result

Returned by all simulation and graph-reading functions.

Attribute	Type	Description
`Result`	`int`	`1` = success, `0` = failure
`IsError`	`int`	`1` if an error occurred
`ErrorMessage`	`str`	Error text if `IsError == 1`
`Graph`	`PSIM_Graph`	Graph data (populated on success)

result = psim.PsimSimulate("circuit.psimsch", "output.smv")
if result.IsError == 0:
    time_curve = result.Graph['Time']
    v_out = result.Graph['V_out']

PSIM_Element & PSIM_param

Returned by PsimGetElementList.

PSIM_Element attributes:

Attribute	Type	Description
`Type`	`str`	Element type (e.g., `"Resistor"`, `"Simulation Control"`)
`Name`	`str`	Element instance name
`Index`	`int`	Element index within the schematic
`Params`	`list[PSIM_param]`	List of parameters

PSIM_param attributes:

Attribute	Type	Description
`Name`	`str`	Parameter name
`Value`	`str`	Parameter value (as string)

PSIM_schematic

A handle to an open schematic file. Returned by PsimFileOpen and PsimFileNew. Automatically closes the file when garbage collected.

sch = psim.PsimFileOpen("circuit.psimsch")
# ... use sch with other functions ...
sch.free()   # explicitly close (optional)

PSIM_SimulateData

A data container used to describe one simulation job for PsimASimulate (asynchronous batch simulation).

sd = PSIM_SimulateData(
    SchFilePath="circuit.psimsch",
    GraphFilePath="output.smv",
    SimviewFlag=1,             # 0=write+open simview, 1=write only, 5=don't write
    NameValueList=["R1", "10", "C1", "1e-6"]
)

You can also build it from helper methods on the PSIM object:

sd = psim.SimulateData_from_dict("circuit.psimsch", "output.smv", {"R1": 10, "simview": 0})
sd = psim.SimulateData_from_kwargs("circuit.psimsch", "output.smv", R1=10, simview=0)

PSIM Class — Main API

Constructor

PSIM(PsimPath: str, callback_func1=None)

Parameter	Type	Description
`PsimPath`	`str`	Path to PSIM installation folder. Pass `""` to auto-detect on Windows.
`callback_func1`	`callable` or `None`	Optional callback for DLL stdout messages. Signature: `(bytes, int, int) -> None`.

Returns: A PSIM instance. Call psim.IsValid() to confirm loading succeeded.

Version Functions

`get_psim_version()`

Returns the PSIM version as a tuple.

version = psim.get_psim_version()
# Returns: (major, minor, patch, build)  e.g. (2026, 0, 0, 0)

`get_psim_version2()`

Like get_psim_version() but also returns the vertical (platform) code.

ver = psim.get_psim_version2()
# Returns: (major, minor, patch, build, vertical)
# vertical: 564=Windows GUI, 864=Windows Solver, 800=Linux Solver

`get_psim_version_name()`

Returns a human-readable version string.

name = psim.get_psim_version_name()
# e.g. "PSIMSolver 2026.0.0.0 (Windows)"

Simulation Functions

`PsimSimulate(schFilePath_or_Obj, graphFilePath, **kwargs) -> PSIM_result`

Runs a PSIM simulation.

Parameter	Type	Description
`schFilePath_or_Obj`	`str` or `PSIM_schematic`	Path to `.psimsch` file or an open schematic handle
`graphFilePath`	`str`	Path for the output graph file (`.smv`)
`**kwargs`	—	Optional parameter overrides and Simview flag

Special kwargs:

Kwarg	Value	Meaning
`simview`	`1` (default)	Write graph and launch Simview
`simview`	`0`	Write graph, do not launch Simview
`simview`	`-1`	Do not write graph, do not launch Simview
Any other key	string/number	Overrides a schematic parameter by name

result = psim.PsimSimulate("boost.psimsch", "boost.smv", simview=0, L1="1e-3", C1="100e-6")
if result.IsError == 0:
    print("Simulation OK")
    print(result.Graph['V_out'][100])

`PsimSimulate_HyperSpice(schFilePath_or_Obj, graphFilePath, **kwargs) -> PSIM_result`

Same as PsimSimulate but uses the HyperSpice engine.

result = psim.PsimSimulate_HyperSpice("circuit.psimsch", "output.smv", simview=0)

`PsimSimulate_LTSpice(schFilePath_or_Obj, graphFilePath, **kwargs) -> PSIM_result`

Same as PsimSimulate but uses the LTSpice engine.

result = psim.PsimSimulate_LTSpice("circuit.psimsch", "output.smv", simview=0)

`PsimASimulate(maxThread, simList) -> list[PSIM_result]`

Runs multiple simulations asynchronously (in parallel). Useful for parameter sweeps.

Parameter	Type	Description
`maxThread`	`int`	Maximum number of concurrent simulation threads. `0` or greater than `len(simList)` means all run concurrently.
`simList`	`list[PSIM_SimulateData]`	List of simulation jobs to run

Returns: A list of PSIM_result objects in the same order as simList.

jobs = [
    PSIM_SimulateData("circuit.psimsch", "out1.smv", 1, ["R1", "10"]),
    PSIM_SimulateData("circuit.psimsch", "out2.smv", 1, ["R1", "20"]),
    PSIM_SimulateData("circuit.psimsch", "out3.smv", 1, ["R1", "30"]),
]
results = psim.PsimASimulate(maxThread=2, simList=jobs)
for i, r in enumerate(results):
    print(f"Job {i}: {'OK' if r.IsError == 0 else r.ErrorMessage}")

Graph File Functions

`PsimReadGraphFile(graphFilePath) -> PSIM_result`

Reads an existing PSIM graph file (.smv, .txt, etc.) and returns all curves.

result = psim.PsimReadGraphFile("output.smv")
if result.IsError == 0:
    for curve in result.Graph.curves:
        print(curve.Name, curve.Rows)

`PsimWriteGraphFile(graphFilePath, ColCount, RowCount, Names, Curves) -> int`

Writes data curves to a PSIM graph file.

Parameter	Type	Description
`graphFilePath`	`str`	Output file path
`ColCount`	`int`	Number of columns (curves)
`RowCount`	`int`	Number of rows (samples) per curve
`Names`	`list[str]`	Curve name for each column
`Curves`	`list`	Data for each column: `list`, `PSIM_curve`, or ctypes double pointer

Returns: 1 on success, 0 on failure.

import numpy as np
t = list(np.linspace(0, 0.01, 1000))
v = [np.sin(2 * np.pi * 50 * ti) for ti in t]
psim.PsimWriteGraphFile("sine.smv", 2, 1000, ["Time", "V_out"], [t, v])

Schematic File Functions

`PsimFileOpen(SchematicFilePath) -> PSIM_schematic`

Opens a schematic file and returns a handle.

sch = psim.PsimFileOpen("circuit.psimsch")

If SchematicFilePath is None or "", a new empty schematic is created (equivalent to PsimFileNew).

`PsimFileNew() -> PSIM_schematic`

Creates a new empty schematic.

sch = psim.PsimFileNew()

`PsimFileSave(SchematicObj, New_SchematicFilePath) -> int`

Saves the schematic to a file.

Parameter	Type	Description
`SchematicObj`	`PSIM_schematic`	Open schematic handle
`New_SchematicFilePath`	`str`	Destination `.psimsch` path

Returns: 1 on success, 0 on failure.

psim.PsimFileSave(sch, "modified_circuit.psimsch")

`PsimIsSubcircuit(schFilePath_or_Obj) -> int`

Checks if the schematic is a subcircuit.

Returns: 1 if subcircuit, 0 otherwise.

is_sub = psim.PsimIsSubcircuit("my_block.psimsch")

Element Manipulation Functions

`PsimGetElementList(SchematicObj, flag) -> list[PSIM_Element]`

Returns a list of all elements in the schematic. The "Simulation Control" element is always placed first in the list.

Parameter	Type	Description
`SchematicObj`	`PSIM_schematic`	Open schematic handle
`flag`	`int`	Filter flag (`0` = all elements)

sch = psim.PsimFileOpen("circuit.psimsch")
elements = psim.PsimGetElementList(sch, 0)
for elm in elements:
    print(elm.Type, elm.Name)
    for p in elm.Params:
        print(f"  {p.Name} = {p.Value}")

`PsimSetElmValue(SchematicObj, psimElm, varName, varValue) -> bool`

Sets a parameter value on an element identified by a PSIM_Element object.

Parameter	Type	Description
`SchematicObj`	`PSIM_schematic`	Open schematic handle
`psimElm`	`PSIM_Element` or `None`	Target element (pass `None` to match by variable name alone)
`varName`	`str`	Parameter name
`varValue`	`str`	New value

elements = psim.PsimGetElementList(sch, 0)
r1 = next(e for e in elements if e.Name == "R1")
psim.PsimSetElmValue(sch, r1, "Resistance", "47")

`PsimSetElmValue2(SchematicObj, ElmType, ElmName, varName, varValue) -> bool`

Sets a parameter value using the element type and name strings directly.

psim.PsimSetElmValue2(sch, "Resistor", "R1", "Resistance", "47")

`PsimSetElmValue3(SchematicObj, ElmIndex, varName, varValue) -> bool`

Sets a parameter value using the element's integer index (from PSIM_Element.Index).

psim.PsimSetElmValue3(sch, 5, "Resistance", "100")

`PsimEnableElm(SchematicObj, psimElm, enable) -> bool`

Enables or disables an element using a PSIM_Element object.

Parameter	Type	Description
`enable`	`int`	`1` = enable, `0` = disable

psim.PsimEnableElm(sch, r1, 0)  # disable R1

`PsimEnableElm2(SchematicObj, ElmType, ElmName, enable) -> bool`

Enables or disables an element by type and name strings.

psim.PsimEnableElm2(sch, "Resistor", "R1", 0)

`PsimEnableElm3(SchematicObj, ElmIndex, enable) -> bool`

Enables or disables an element by its integer index.

psim.PsimEnableElm3(sch, 5, 0)

`PsimCreateNewElement(SchematicObj, szType, szName, **kwargs) -> int`

Creates a new element in the schematic.

Parameter	Type	Description
`SchematicObj`	`PSIM_schematic`	Open schematic handle
`szType`	`str`	Element type name
`szName`	`str`	Instance name to assign
`**kwargs`	—	Parameter name/value pairs

Returns: Element index on success, -1 on failure.

Note: The .FILE parameter cannot be set with this function; use PsimSetElmValue2 instead.

idx = psim.PsimCreateNewElement(sch, "Resistor", "R5", Resistance="100", x="200", y="300")

`PsimConvertToPython(SchematicFilePath, PythonFilePath) -> int`

(Requires PSIM 2024 or above)

Converts a schematic file to a Python script.

psim.PsimConvertToPython("circuit.psimsch", "circuit_script.py")

Design Suite (DS) Functions

These functions work with Design Suite schematics and require PSIM 2025 or above.

`Psim_DS_UpdateParameters(schFilePath_or_Obj, parameters) -> (int, str)`

Updates Design Suite parameters in a schematic.

Parameter	Type	Description
`schFilePath_or_Obj`	`str` or `PSIM_schematic`	Schematic path or handle
`parameters`	`dict`, `str`, or `list`	Parameters to update

Returns: (result, error_message) — result is 1 on success, 0 on failure.

res, err = psim.Psim_DS_UpdateParameters("design.psimsch", {"Kp": "0.5", "Ki": "10"})

The parameters argument can be:

a dict: {"Kp": "0.5", "Ki": "10"}
a str: "Kp = 0.5;\nKi = 10;\n"
a list: ["Kp = 0.5", "Ki = 10"]

`Psim_DS_GetParameters(schFilePath_or_Obj) -> (int, str, int, str)`

Retrieves Design Suite parameters from a schematic.

Returns: (result, parameters_string, param_count, error_message)

res, params_str, count, err = psim.Psim_DS_GetParameters("design.psimsch")
print(params_str)  # "Kp=0.5\nKi=10\n..."

`Psim_DS_RunScript(schFilePath_or_Obj, ScriptIndex, parameters) -> (int, str)`

Runs a Design Suite script by index.

Parameter	Type	Description
`ScriptIndex`	`int`	Zero-based index of the script to run
`parameters`	`dict`, `str`, or `list`	Input parameters

Returns: (result, error_message)

res, err = psim.Psim_DS_RunScript("design.psimsch", 0, {"x": "1.5"})

`Psim_GetUndefinedParameters(schFilePath_or_Obj) -> (int, str, int, str)`

Returns a list of parameters that are used in the schematic but not yet defined.

Returns: (result, parameters_string, param_count, error_message)

res, params, count, err = psim.Psim_GetUndefinedParameters("circuit.psimsch")

Script Functions

These functions require PSIM 2026 or above.

`Psim_RunScriptFile(strFilePath, dictIn=None) -> (dict, str)`

Runs a PSIM script from a file.

Parameter	Type	Description
`strFilePath`	`str`	Path to the script file
`dictIn`	`dict` or `None`	Input variables passed to the script

Returns: (dictOut, error_message) where dictOut is a dict of output variables from the script.

outputs, err = psim.Psim_RunScriptFile("my_script.txt", {"R": "10", "L": "1e-3"})
print(outputs)  # e.g. {"Vout": "24.5"}

`Psim_RunScript(strScriptText, dictIn=None) -> (dict, str)`

Runs a PSIM script from a string.

script = "Vout = Vin * (R2 / (R1 + R2));"
outputs, err = psim.Psim_RunScript(script, {"Vin": "12", "R1": "10", "R2": "20"})

`Psim_RunScriptInfo(strScriptText, dictIn=None) -> (dict, str, int, int)`

Runs a script and also returns type and status information.

Returns: (dictOut, error_message, scriptType, returnValue)

Return	Description
`dictOut`	Output variables
`error_message`	Error string (empty if OK)
`scriptType`	Bitmask of features used
`returnValue`	`1`=success, `-1`=error, `10`=depends on external objects

scriptType bitmask:

Bit	Hex	Meaning
0	`0x01`	Assignments
1	`0x02`	Arithmetic (`+`, `-`, `*`, `/`, `pow`)
2	`0x04`	Basic math functions (`sin`, `cos`, `log`, …)
3	`0x08`	Control flow (`if`, `while`)
4	`0x10`	Function or Formula
5	`0x20`	Conditional
8	`0x100`	Advanced functions (`ReadGraph`, `ReadFile`, …)

dictOut, err, stype, retval = psim.Psim_RunScriptInfo("x = sin(a);", {"a": "1.57"})
print(f"returnValue={retval}, scriptType=0x{stype:02X}")

Probe Functions

`Psim_GetProbes(schFilePath_or_Obj) -> (int, str, int, str)`

(Requires PSIM 2026 or above)

Returns the list of probe names in a schematic.

Returns: (result, probe_names_string, probe_count, error_message)

res, probes_str, count, err = psim.Psim_GetProbes("circuit.psimsch")
print(f"{count} probes: {probes_str}")

Simview Function

`RunSimview(szGraphFilePath, *colNames, **name_value_pairs)`

Opens Simview with a graph file and optionally selects curves to display.

Parameter	Type	Description
`szGraphFilePath`	`str`	Path to the `.smv` graph file
`*colNames`	`str`	Curve names to display
`**name_value_pairs`	—	Additional name/value display options

psim.RunSimview("output.smv", "V_out", "I_L")

Version Compatibility Reference

Function	Min PSIM Version
`get_psim_version`, `PsimSimulate`, `PsimASimulate`, `PsimReadGraphFile`, `PsimWriteGraphFile`, `PsimFileOpen`, `PsimFileSave`, `PsimFileNew`, `PsimIsSubcircuit`, `PsimGetElementList`, `PsimSetElmValue`, `PsimSetElmValue2`, `PsimEnableElm`, `PsimEnableElm2`, `PsimCreateNewElement`, `RunSimview`, `PsimSimulate_HyperSpice`, `PsimSimulate_LTSpice`	PSIM 2023.1
`PsimConvertToPython`, `PsimEnableElm3`, `PsimSetElmValue3`	PSIM 2024
`Psim_DS_UpdateParameters`, `Psim_DS_GetParameters`, `Psim_DS_RunScript`, `Psim_GetUndefinedParameters`	PSIM 2025
`Psim_GetProbes`, `Psim_RunScriptFile`, `Psim_RunScript`, `Psim_RunScriptInfo`, `get_psim_version_name`	PSIM 2026

Usage Examples

Basic Simulation

from Psim_Class import PSIM

psim = PSIM("")
if not psim.IsValid():
    raise RuntimeError("PSIM failed to load")

result = psim.PsimSimulate("boost_converter.psimsch", "boost_output.smv", simview=0)
if result.IsError == 0:
    time   = result.Graph['Time']
    v_out  = result.Graph['V_out']
    print(f"Final Vout = {v_out[v_out.Rows - 1]:.3f} V")
else:
    print("Error:", result.ErrorMessage)

Parameter Sweep with Async Simulation

from Psim_Class import PSIM, PSIM_SimulateData

psim = PSIM("")
jobs = []
for r_val in [10, 20, 50, 100]:
    sd = PSIM_SimulateData(
        SchFilePath="circuit.psimsch",
        GraphFilePath=f"output_R{r_val}.smv",
        SimviewFlag=1,
        NameValueList=["R_load", str(r_val)]
    )
    jobs.append(sd)

results = psim.PsimASimulate(maxThread=2, simList=jobs)
for i, r in enumerate(results):
    if r.IsError == 0:
        v = r.Graph['V_out']
        print(f"R={[10,20,50,100][i]}: Vout_final = {v[v.Rows-1]:.3f}")

Modifying a Schematic and Simulating

from Psim_Class import PSIM

psim = PSIM("")
sch = psim.PsimFileOpen("filter.psimsch")

# Change component values
psim.PsimSetElmValue2(sch, "Resistor", "R1", "Resistance", "1000")
psim.PsimSetElmValue2(sch, "Capacitor", "C1", "Capacitance", "10e-6")

# Save modified schematic
psim.PsimFileSave(sch, "filter_modified.psimsch")

# Simulate
result = psim.PsimSimulate(sch, "filter_output.smv", simview=0)

Running a Script

from Psim_Class import PSIM

psim = PSIM("")

script = """
omega = 2 * 3.14159 * f;
Xc = 1 / (omega * C);
Vout = Vin * Xc / sqrt(R*R + Xc*Xc);
"""

result, err = psim.Psim_RunScript(script, {"f": "1000", "C": "10e-6", "R": "100", "Vin": "12"})
print(f"Vout = {result.get('Vout', 'N/A')}")
if err:
    print("Error:", err)

Reading an Existing Graph File

from Psim_Class import PSIM

psim = PSIM("")
result = psim.PsimReadGraphFile("previous_sim.smv")
if result.IsError == 0:
    print(f"Number of curves: {len(result.Graph)}")
    for curve in result.Graph.curves:
        print(f"  {curve.Name}: {curve.Rows} points")

Table of Contents​

Overview​

Installation & Setup​

Requirements​

Importing​

Creating the PSIM object​

Data Classes​

PSIM_curve​

PSIM_Graph​

PSIM_result​

PSIM_Element & PSIM_param​

PSIM_schematic​

PSIM_SimulateData​

PSIM Class — Main API​

Constructor​

Version Functions​

get_psim_version()​

get_psim_version2()​

get_psim_version_name()​

Simulation Functions​

PsimSimulate(schFilePath_or_Obj, graphFilePath, **kwargs) -> PSIM_result​

PsimSimulate_HyperSpice(schFilePath_or_Obj, graphFilePath, **kwargs) -> PSIM_result​

PsimSimulate_LTSpice(schFilePath_or_Obj, graphFilePath, **kwargs) -> PSIM_result​

PsimASimulate(maxThread, simList) -> list[PSIM_result]​

Graph File Functions​

PsimReadGraphFile(graphFilePath) -> PSIM_result​

PsimWriteGraphFile(graphFilePath, ColCount, RowCount, Names, Curves) -> int​

Schematic File Functions​

PsimFileOpen(SchematicFilePath) -> PSIM_schematic​

PsimFileNew() -> PSIM_schematic​

PsimFileSave(SchematicObj, New_SchematicFilePath) -> int​

PsimIsSubcircuit(schFilePath_or_Obj) -> int​

Element Manipulation Functions​

PsimGetElementList(SchematicObj, flag) -> list[PSIM_Element]​

PsimSetElmValue(SchematicObj, psimElm, varName, varValue) -> bool​

PsimSetElmValue2(SchematicObj, ElmType, ElmName, varName, varValue) -> bool​

PsimSetElmValue3(SchematicObj, ElmIndex, varName, varValue) -> bool​

PsimEnableElm(SchematicObj, psimElm, enable) -> bool​

PsimEnableElm2(SchematicObj, ElmType, ElmName, enable) -> bool​

PsimEnableElm3(SchematicObj, ElmIndex, enable) -> bool​

PsimCreateNewElement(SchematicObj, szType, szName, **kwargs) -> int​

PsimConvertToPython(SchematicFilePath, PythonFilePath) -> int​

Design Suite (DS) Functions​

Psim_DS_UpdateParameters(schFilePath_or_Obj, parameters) -> (int, str)​

Psim_DS_GetParameters(schFilePath_or_Obj) -> (int, str, int, str)​

Psim_DS_RunScript(schFilePath_or_Obj, ScriptIndex, parameters) -> (int, str)​

Psim_GetUndefinedParameters(schFilePath_or_Obj) -> (int, str, int, str)​

Script Functions​

Psim_RunScriptFile(strFilePath, dictIn=None) -> (dict, str)​

Psim_RunScript(strScriptText, dictIn=None) -> (dict, str)​

Psim_RunScriptInfo(strScriptText, dictIn=None) -> (dict, str, int, int)​

Probe Functions​

Psim_GetProbes(schFilePath_or_Obj) -> (int, str, int, str)​

Simview Function​

RunSimview(szGraphFilePath, *colNames, **name_value_pairs)​

Version Compatibility Reference​

Usage Examples​

Basic Simulation​

Parameter Sweep with Async Simulation​

Modifying a Schematic and Simulating​

Running a Script​

Reading an Existing Graph File​

Table of Contents