Python library for interfacing to the NL5 DLL based circuit simulator

nl5py is a Python interface for modifying, simulating, and extracting data from NL5 schematics using the NL5 DLL circuit simulator. There are plans in the future to also support the HTTP API for interfacing to open schmatics in the regular NL5 program.

NL5 DLL can be used without a license, but will be limited to 20 components for tansient simulations. If your schematic has more than 20 components and no license is detected, the following exception will be raised when you attempt to run a transient simulation.

Exception: NL5_Simulate: Too many components for Demo version

There are two ways to include a license file. Either simple place an nl5.nll file in the same directory as the schematic file you are loading/simulating, or use the load_license() function.

from nl5py import load_license
license_info = load_license("nl5.nll")

The Schematic class is the primary interface class. You initialize the class with a path to an existing NL5 schematic file, which will load this into the NL5 DLL.

from nl5py import Schematic
schematic = Schematic("analog.nl5")

You can modify the properties of circuit elements using the set_value method.

schematic.set_value("C1", 2.1)  # change C1 to 2.1 Farads
schematic.set_value("C1.IC", 5.2) # Set the initial voltage of C1 to 5.2V

The library will verify that commands are recieved by the NL5 DLL without errors. If an error is detected, it gets converted into an Exception and raised.

schematic.set_value("C100", 2.1)  # C100 does not exist

Since C100 does not exist in the schematic, it will throw the following exception:

Exception: NL5_SetValue: parameter C100 not found

If you want to modify elements in a subcircuit, you must do so using the set_text method and send all of the value changes as a string of comma deliminted commands.

# Change C1 and C2 in the subcircuit inside X1
commands = ["C1 = 1", "C2 = 2"]
schematic.set_text("X1.Cmd", ",".join(commands))

If you want to set a value that needs to be comma deliminited, such as a PWL value, the PWL section should be in quotes.

# C1 is a PWL capacitor
commands = ['C1.PWL = "1, 1, 2"', "C2 = 2"]
schematic.set_text("X1.Cmd", ",".join(commands))

Before a transient simulation is run, the user must ensure that the circuit includes all the traces (voltages, currents, powers, etc) that they want to observe. Traces can be added programmatically using the add_trace method.

schematic.add_trace(name="C1", trace_type="V")  # add the voltage on C1
schematic.add_trace(name="C1", trace_type="I")  # add the current on C1

All of the NL5 trace types are supported via the following "trace_type" strings:

If no trace type is specified, it defaults to "Function".

schematic.add_trace(name="V(C2)")  		 # add the voltage on C1 via a function trace
schematic.add_trace(name="V(C1)+V(C2)")  # add the sum of voltages on C1 and C2 via a function trace

You can get a current list of traces using the "get_trace_names" method.

traces = schematic.get_trace_names()
print(traces)

You can clear all existing traces using the "clear_traces" method.

schematic.clear_traces()
print(traces)

Running a transient simulation is done using the simulate_transient method.

schematic.simulate_transient(screen=20, step=1e-3)

After a simulation has completed, data can be extracted using get_data.

data = schematic.get_data(traces=["V(1)", "V(2)", "V(3)", "V(4)", "V(5)"])

If you simply want the data from all traces, you can run "get_data" with no arguments and traces will default to all traces currently added.

data = schematic.get_data()

The data is returned in the form of a pandas dataframe.

print(data.head())

              V(1)      V(2)      V(3)      V(4)      V(5)
0.000000  0.000000  0.000000  0.000000  0.000000  0.000000
0.000250  0.015708  0.005236  0.005236  0.005236  0.005236
0.000500  0.031416  0.010472  0.010472  0.010472  0.010472
0.000667  0.041888  0.013963  0.013963  0.013963  0.013963
0.000833  0.052360  0.017453  0.017453  0.017453  0.017453

The Schematic class also supports AC simulations, which work in much the same way as the transient simulations.

# set the AC source
schematic.set_ac_source("I1")

# add AC traces
# TODO: Does not yet appear to be supported by DLL API

# run simulation
schematic.simulate_ac(start_frequency=1e3, stop_frequency=1e6, num_points=5000)

# extract data
data = schematic.get_ac_data(traces=["V(1)", "V(2)"])

The data returned from get_ac_data is a hierarchical index'd data frame with magnitude and phase info for each signal.

print(data.head())

            V(1)                       V(2)                               
            magnitude       phase      magnitude       phase
1000.000000  0.009758  179.121846       0.009758  179.121846
1199.839968  0.014131  178.946299       0.014131  178.946299
1399.679936  0.019365  178.770721       0.019365  178.770721
1599.519904  0.025496  178.595105       0.025496  178.595105
1799.359872  0.032566  178.419447       0.032566  178.419447