Skip to main content

SIMBA Python API

The Simba Python Module (aesim.simba) is a Python package that contains hundreds of functions providing direct access to SIMBA such as creating a circuit, modifying parameters, running a simulation, and retrieving results. aesim.simba is independent and does not require to have SIMBA installed to be used.

Installation

The easiest way to install the Python API is using pip:

pip install aesim.simba

Requirements

The current version of aesim.simba is compatible with Windows, macOS and Linux (64-bit).

Activation

The deployment key available on your account profile page must be used to activate aesim.simba. Two methods are available:

Using Environment Variable

The easiest way to activate pysimba is to set the environment variable SIMBA_DEPLOYMENT_KEY value to your deployment key. To add a new environment variable in Windows:

  • Open the Start Search, type in “env”, and choose “Edit the system environment variables”:
  • Click the “Environment Variables…” button.
  • Set the environment variables as needed. The New button adds an additional variable.

Code-based Activation

The License API can be also used to activate aesim.simba.

from aesim.simba import License
License.Activate('*** YOUR DEPLOYMENT KEY ***')

Background License Validation

Desktop and Python use the same background validation policy. With SIMBA_OFFLINE_MODE enabled, automatic server checks are limited to once per hour for multi-user licenses and once per 24 hours for individual online licenses. These intervals also apply after failed checks. Explicit activation and forced validation remain available at any time. Without offline mode, multi-user checks run every five minutes, individual online checks run daily with earlier renewal near expiration, and failed checks can be retried after five minutes.

Offline mode is enabled only by an explicit user or administrator environment setting (SIMBA_OFFLINE_MODE=true or 1) before process startup. SIMBA never enables it automatically after a network failure or when loading an offline file.

Routine checks and network failures are silent; explicit account revocations remove the rights as usual. Individual offline licenses are checked locally only; signed offline multi-user files are checked with the server without replacing their signed duration. SIMBA_OFFLINE_MODE disables telemetry, including usage reports and crash reporting, and version update checks. It does not prohibit license network requests. Machine permissions, firewall rules or lack of connectivity may still prevent a request. Existing signed rights remain usable only until their original expiration; no offline grace period is added. Python starts checking after a license has been loaded, using one timer per process. The timer is stopped at interpreter exit without waiting for a network request.

Containers

Every license request states whether aesim.simba runs in a container (Docker, Podman, Kubernetes; a yes/no flag only). Since 2026-10-26 the license server refuses a standard license in a container, unless Powersys has allowed containers for that license: use a Compute license (below) for containers and clusters.

Compute License (cloud and cluster workers)

A Compute license runs aesim.simba on servers, cloud instances or containers without binding it to a machine. Powersys creates a separate Compute license and links the accounts allowed to manage it. A linked account creates keys on the Compute licenses page of the simba.io profile and stores each secret in a secret manager (it is shown only once). Each worker process then obtains a short lease from the license server, renews it in the background and releases it at exit; a permanent connection to the license server is required.

Like regular license checks, acquiring, renewing and releasing Compute leases require network access regardless of SIMBA_OFFLINE_MODE.

Compute mode is selected for the process lifetime when either Compute credential variable is present; both nonempty credentials are required. A failed acquisition, expired lease or call to License.StopCompute() never falls back to a stored regular license. To use a regular license, stop the worker, unset SIMBA_COMPUTE_KEY_ID and SIMBA_COMPUTE_SECRET, then start a new process with the usual licensing configuration. Changing these variables in a running process does not change its license mode.

Network failures, HTTP 408 timeouts, exhausted slots, rate limits and temporary server errors are retried with exponential delays from 15 seconds up to five minutes, with jitter to spread worker retries. A server-provided retry_after_seconds or Retry-After delay takes precedence, even if the current lease expires while waiting. Renewals are scheduled no later than half the native remaining lifetime, measured in milliseconds. Retries after errors also take the remaining lifetime into account, with a minimum one-second interval; in the final second or after expiry they use normal backoff to avoid busy-polling. Two leases issued in the same second can collide with replay protection: a rejected acquisition is released and retried after two seconds; an existing lease keeps its original expiry. The signed lease's expiry is never extended locally. A response received after its signed expiry is rejected natively but retried automatically with normal backoff. A rejected acquisition is released before retrying; a rejected renewal retains the rotated renewal token and does not release any previous valid allocation. An invalid or consumed renewal token, or a missing, expired or released lease, triggers a new acquisition within the slot quota. An early renewal retains its lease and token and waits before retrying.

Permanent refusals suspend automatic attempts and report the cause: invalid credentials, disabled or expired license/key, IP restriction, invalid license configuration, or a request exceeding the configured slot limit. For the latter, reduce SIMBA_COMPUTE_SLOTS or ask for a higher quota; waiting for free slots cannot fix it. An expired Compute license returns LicenseExpired; native version validation alone can return UnsupportedSimbaVersion. Correct the reported problem and call License.ActivateCompute again, or restart the worker. Existing signed rights remain valid until their own expiry. Keys attached to classic licenses must be replaced with keys from the separate Compute license; changing the server deployment does not migrate them.

Compute leases renew in the background while calculations run. A temporary renewal failure does not interrupt work while the last signed lease remains valid. If that lease expires before a renewal succeeds, running calculations fail with a license error at the next solver checkpoint and new calculations are blocked. This also applies to AC sweep workers and FMI steps. A late acquisition authorizes new work; it cannot resume calculations whose lease already expired. Regular-license calculations retain their existing behavior and can finish after license expiry. Stopping Compute cancels renewals, prevents new calculations immediately and interrupts running Compute calculations at their next solver checkpoint. The native expiry watchdog is shared by active Compute calculations and checks the suspend-aware clock every 100 ms. It signals normal cooperative cancellation; time-step loops do not read the licensing clock or lock license state. A blocking external model call must return before its solver can finish stopping.

Without a valid lease, a calculation fails at once with an exception whose text starts with No valid Compute license lease is available. (or The Compute license lease has expired.), followed by the cause (the same text as the client message) and what to do. To wait for a lease instead, set SIMBA_COMPUTE_WAIT_SECONDS: while all slots are in use or the server is unreachable, the calculation waits up to that number of seconds for a lease. A refused key never waits. A service can also read the cause directly:

from aesim.simba import License
License.ComputeState                 # NotStarted, Active, WaitingForSlot, Retrying, Rejected or Stopped
License.ComputeLeaseRemainingSeconds  # seconds left on the current lease (0 without lease)

WaitingForSlot and Retrying are retried automatically: retry the calculation later. Rejected is a permanent refusal (credentials, disabled or expired license or key, IP restriction, slot limit, solver validation): automatic retries are suspended and the problem must be corrected, usually by the license administrator.

On Linux, lease expiration uses CLOCK_BOOTTIME, which includes host suspend time. Resuming a suspended host does not restore the lifetime of a lease that has expired.

Compute rights belong to one process. After a POSIX fork(), the child discards the inherited rights and uses a new nonce. It must explicitly acquire its own lease and never renew or release the parent's allocation. Prefer starting a fresh worker process and initializing SIMBA there: this protection does not make an already initialized .NET runtime safe to reuse after fork().

Diagnostic messages are written in English to standard error. They identify the failure, the retry delay (or suspended retries), and whether the current lease still allows new calculations. Repeated messages for the same condition are limited to one per minute; recovery is reported immediately. Credentials and raw server error bodies are never included.

Licensing Environment Variables

Variable Default Meaning
SIMBA_DEPLOYMENT_KEY not set Deployment key of a regular license (see above)
SIMBA_COMPUTE_KEY_ID not set Compute license key ID; with SIMBA_COMPUTE_SECRET, selects the Compute license
SIMBA_COMPUTE_SECRET not set Secret of the Compute license key (keep it in a secret manager)
SIMBA_COMPUTE_SLOTS 1 Simultaneous simulations of one Python process with a Compute license
SIMBA_COMPUTE_WAIT_SECONDS 0 Seconds a calculation waits for a Compute lease while all slots are in use or the server is unreachable (0: fail at once)

License Usage Data

With an online license, aesim.simba reports the use of the license to the SIMBA license server, like SIMBA Desktop: one session per Python process and, every 12 hours, a report with totals per simulation type (transient, AC sweep, FMI): number of simulations, results (completed, error, aborted), refusals and their reason, cumulated and longest durations, highest number of simultaneous simulations, and the JMAG / detailed switch model tokens used. Individual simulations are not reported. The session also describes the environment: operating system, processor count, whether it runs in a container or a continuous integration service, and the host and user names as SHA-256 hashes (never in clear). Circuits, parameters and results are never sent. At process exit the final report is saved in the existing local queue for the next start, without an additional network wait. Network failures remain eligible for retry; invalid reports rejected with HTTP 400 are discarded silently. The shared telemetry queue keeps at most five reports and 1 MiB on disk, removing the oldest reports first. A report exceeding 1 MiB on its own is discarded silently.

Environment variable Default Meaning
SIMBA_LICENSE_USAGE_REPORT_INTERVAL_HOURS 12 Hours between two usage reports; the final report is queued at exit
SIMBA_LICENSE_USAGE_DRAIN_SECONDS 60 Seconds between two local reads of the solver usage journal (no network)
SIMBA_OFFLINE_MODE not set Disables all telemetry, including usage reports and crash reporting; license checks remain enabled

Missing, invalid or out-of-range interval settings use the defaults above without console messages or startup errors. After lost journal events, the running count is resynchronized from the native drain snapshot. The incomplete period retains its lost-event count and reports a peak of zero, rather than an unreliable peak.

Deferred review items: concurrent event ordering can still overstate peaks in periods without loss. Server-side recovery of identity alerts for future reports, durable alert scheduling, and historical quota attribution for delayed reports are tracked separately and are not changed here.

API Documentation

The API documentation is available here.

The installed package also provides API docstrings and type annotations. In an interactive Python session, use help(aesim.simba.DFTCalculatorJob) or your editor's hover help to discover constructor overloads, properties, and supported analysis jobs.

Performance

Running a simulation using the Python API is significantly faster than using the SIMBA User Interface because there is no overhead.

Quick Example

The following example opens the Flyback Converter Example available in SIMBA, runs it, and plots the output voltage.

#%% Load modules
from aesim.simba import DesignExamples
import matplotlib.pyplot as plt

#%% Load project
flybackConverter = DesignExamples.DCDC_Flyback()

#%% Get the job object and solve the system
job = flybackConverter.TransientAnalysis.NewJob()
status = job.Run()

#%% Get results
t = job.TimePoints
Vout = job.GetSignalByName('R2 - Instantaneous Voltage').DataPoints

#%% Plot Curve
fig, ax = plt.subplots()
ax.set_title(flybackConverter.Name)
ax.set_ylabel('Vout (V)')
ax.set_xlabel('time (s)')
ax.plot(t,Vout)

# %%

DFT Example

The following example computes the magnitude spectrum of the flyback output over the final ten switching periods. DFTSettings(frequency, periods, harmonics) includes the DC component and the requested harmonics in the resulting signal.

from aesim.simba import DFTCalculatorJob, DFTSettings, DesignExamples, Status
import matplotlib.pyplot as plt

design = DesignExamples.DCDC_Flyback()
transient_job = design.TransientAnalysis.NewJob()
if transient_job.Run() != Status.OK:
    raise RuntimeError("Transient simulation failed")

vout = transient_job.GetSignalByName("R2 - Instantaneous Voltage")
dft_job = DFTCalculatorJob(DFTSettings(100e3, 10, 20), [vout])
if dft_job.Run() != Status.OK:
    raise RuntimeError("DFT calculation failed")

spectrum = dft_job.Signals[0]
fig, ax = plt.subplots()
ax.stem(spectrum.TimePoints, spectrum.DataPoints)
ax.set(xlabel="Frequency (Hz)", ylabel=f"Amplitude ({vout.Unit})")
ax.grid()
plt.show()

More Examples

A collection of simple Python script examples using the SIMBA Python API is available on this GitHub repository

Copyright (c) 2019-2020 AESIM.tech

Metadata

Release files for aesim.simba 2026.10.28

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for aesim.simba 2026.10.28
File Actions
aesim_simba-2026.10.28-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for aesim_simba-2026.10.28-py3-none-win_amd64.whl
aesim_simba-2026.10.28-py3-none-manylinux2014_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for aesim_simba-2026.10.28-py3-none-manylinux2014_aarch64.whl
aesim_simba-2026.10.28-py3-none-manylinux1_x86_64.whl Python 3 none Linux glibc 2.5+ x86-64 Details for aesim_simba-2026.10.28-py3-none-manylinux1_x86_64.whl
aesim_simba-2026.10.28-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for aesim_simba-2026.10.28-py3-none-macosx_11_0_arm64.whl

Total release size: 288.5 MB

Release files / aesim_simba-2026.10.28-py3-none-win_amd64.whl

Download URL aesim_simba-2026.10.28-py3-none-win_amd64.whl
Size 94.6 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
05f284c5bdc2e970193e9a4e849a74c47844d114d559b0e3aae9067396df9e88
BLAKE2b-256 checksum
How to use checksums
f7c1f4989b69af46526636588ed3051c648aa63c772bd7815ce8ec4b73341406
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.9

Release files / aesim_simba-2026.10.28-py3-none-manylinux2014_aarch64.whl

Download URL aesim_simba-2026.10.28-py3-none-manylinux2014_aarch64.whl
Size 66.4 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
17304d55ce33517d151e3b1fff345628cd19a1a02e7f4a39c78e3d6824077a2e
BLAKE2b-256 checksum
How to use checksums
b7a308ac5dc04b3aa17a9f1abe5764a1ebbb4b055857e04f1a7b1f0386631388
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.9

Release files / aesim_simba-2026.10.28-py3-none-manylinux1_x86_64.whl

Download URL aesim_simba-2026.10.28-py3-none-manylinux1_x86_64.whl
Size 72.0 MB
Tags Linux glibc 2.5+ x86-64 Python 3
SHA-256 checksum
How to use checksums
5e8ad4b8bdf4f230b5a2b80af7266b7fcade0e8cc85edbad7553e8b30e20d218
BLAKE2b-256 checksum
How to use checksums
11a663e1cda19207e124b2b9ec9cb39de6716c908ef87ded77d921d84be750eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.9

Release files / aesim_simba-2026.10.28-py3-none-macosx_11_0_arm64.whl

Download URL aesim_simba-2026.10.28-py3-none-macosx_11_0_arm64.whl
Size 55.4 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
1e4f9476905459b0efe4f1045738dd6e095f7d5d8abab37aad1e853bae30647c
BLAKE2b-256 checksum
How to use checksums
2cb2049c45e1550a6a7e1053358a17a85828816deb9fb87228d69bfd08ffbf28
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.9

Security for aesim.simba 2026.10.28

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page