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: multi-user licenses are checked every five minutes, and individual online licenses once every 24 hours while the process runs. Online activations nearing their expiration can be renewed earlier. Failed checks can be retried after five minutes without extending the signed license's validity. Routine checks and network failures are silent; explicit account revocations remove the rights as usual. Individual offline licenses are checked locally only, and SIMBA_OFFLINE_MODE disables all server checks. 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.

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.

Compute lease requests take precedence over SIMBA_OFFLINE_MODE: acquiring, renewing and releasing Compute leases still require network access when that variable is enabled.

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

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.

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