ahkab.results

This module provides classes for easy, dictionary-like access to simulation results.

Simulation results are typically returned upon successful simulation of a circuit and the user is not expected to use their constructor, but rather to use the methods they provide to access their data set.

Overview of the data interface

The solution classes define special methods according to their simulation type but they all subclass solution, which provides the shared data interface.

The interface allows for accessing the values as:

>>> ac_sol.keys()
['f', 'Vn1', 'Vn2', 'I(V1)', 'I(L1)', 'I(L2)']

Where ac_sol is a generic example instance of ac_solution.

Checking with the in construct:

>>> 'Vn1' in ac_sol
True

Access any variable in the solution object:

>>> ac_sol['f']
array([ 6098.38572827,  6102.08394991,  6105.78441425,  6109.48712265,
        6113.19207648,  6116.89927708,  6120.60872583,  6124.32042408,

        [... omissis ...]

        6463.83880528,  6467.75864729,  6471.68086639])

Iterate over the results:

>>> for var in ac_sol:
...     # do something with ac_sol[var]
...     pass

Convenience methods are available to identify and access the independent, swept variable, when it is available:

>>> ac_sol.get_xlabel()
'f'
>>> ac_sol.get_x()
array([ 6098.38572827,  6102.08394991,  6105.78441425,  6109.48712265,
        6113.19207648,  6116.89927708,  6120.60872583,  6124.32042408,

        [... omissis ...]

        6463.83880528,  6467.75864729,  6471.68086639])

Index of the solution classes

ac_solution(circ, start, stop, points, ...)	AC results
dc_solution(circ, start, stop, sweepvar, ...)	DC results
op_solution(x, error, circ, outfile[, ...])	OP results
pss_solution(circ, method, period, outfile)	PSS results
pz_solution(circ, poles, zeros, outfile)	PZ results
symbolic_solution(results_dict, ...[, ...])	Symbolic results
tran_solution(circ, tstart, tstop, op, ...)	Transient results

Module reference

class ac_solution(circ, start, stop, points, stype, op, outfile)

Bases: ahkab.results.solution, ahkab.results._mutable_data

AC results

Parameters:

circ : circuit instance

the circuit instance of the simulated circuit

start : float

the AC sweep frequency start value, in Hz.

stop : float

the AC sweep frequency stop value, in Hz.

points : int

the AC sweep total points.

stype : str

the type of sweep, "LOG", "LIN" or arb. "POINTS".

op : op_solution

the linearization Operating Point used to compute the results.

outfile: str

the file to write the results to. Use "stdout" to write to the standard output.

add_line(frequency, x)

asarray()

Return all data as a (possibly huge) python matrix.

get(name, default=None)

Get a solution by variable name.

get_x()

get_xlabel()

has_key(name)

Determine whether the result set contains a variable.

items()

keys()

Get all of the results set’s variables names.

next()

values()

Get all of the results set’s variables values.

class case_insensitive_dict

Bases: object

A dictionary that uses case-insensitive strings as keys.

get(name, default=None)

Given the case-insensitive string key name, return its corresponding value.

If not found, return default.

has_key(name)

Determine whether the result set contains the variable name.

items()

Get all keys and values pairs

keys()

Get all keys

update(adict)

Update the dictionary contents with the mapping in the dictionary adict.

values()

Get all values

class dc_solution(circ, start, stop, sweepvar, stype, outfile)

Bases: ahkab.results.solution, ahkab.results._mutable_data

DC results

Parameters:

circ : circuit instance

the simulated circuit.

start : float

the DC sweep start value.

stop : float

the DC sweep stop value.

sweepvar : str

the swept variable part_id.

stype : str

the type of sweep, "LOG", "LIN" or arb. "POINTS".

outfile : str

the filename of the file where the results will be written. Use "stdout" to write to std output.

add_op(sweepvalue, op)

A DC sweep is made of a set of OP points.

This method adds an OP solution and its corresponding sweep value to the results set.

asarray()

Return all data.

Note

This method loads to memory a possibly huge data matrix.

get(name, default=None)

Get a solution by variable name.

get_x()

get_xlabel()

has_key(name)

Determine whether the result set contains a variable.

items()

keys()

Get all of the results set’s variables names.

next()

values()

Get all of the results set’s variables values.

class op_solution(x, error, circ, outfile, iterations=0)

Bases: ahkab.results.solution, ahkab.results._mutable_data

OP results

Parameters:

x : ndarray

the result set

error : ndarray

the residual error after solution,

circ : circuit instance

the circuit instance of the simulated circuit

outfile: str

the file to write the results to. Use “stdout” to write to std output.

iterations, int, optional

The number of iterations needed for convergence, if known.

asarray()

Get all data as a numpy array

get(name, default=None)

Get a solution by variable name.

get_table_array()

static gmin_check(op2, op1)

Checks the differences between two sets of OP results.

It is assumed that one set of results is calculated with Gmin, the other without.

Parameters:

op1, op2: op_solution instances

the results vectors, interchangeable

Returns:

test_fail_variables : list

The list of the variables that did not pass the test. They are extracted from the op_solution objects. If the check was passed, this is an empty list.

has_key(name)

Determine whether the result set contains a variable.

items()

keys()

Get all of the results set’s variables names.

next()

print_short()

Print a short, essential representation of the OP results

values()

Get all of the results set’s variables values.

write_to_file(filename=None)

class pss_solution(circ, method, period, outfile)

Bases: ahkab.results.solution, ahkab.results._mutable_data

PSS results

Parameters:

circ : circuit instance

the circuit instance of the simulated circuit.

method : str

the PSS algorithm employed.

period : float

the solution period.

outfile : str

the filename of the save file. Use “stdout” to write to the std output.

Note

Instantiating pss_solution creates an empty data set. Call set_results() to initialize its data.

asarray()

get(name, default=None)

Get a solution by variable name.

get_x()

get_xlabel()

has_key(name)

Determine whether the result set contains a variable.

items()

keys()

Get all of the results set’s variables names.

next()

set_results(t, x)

Set the results in the data set

Note

• All the data are set at the same time for a PSS results set.
• Instantiating pss_solution creates an empty data set.
• This method should be called as soon as the data is available.

Parameters:

t : ndarray

The time. The array should be 2D with shape (1, N).

x : ndarray

The data corresponding to the variables. The array should be 2D with shape (M, N), where M is the number of variables in the data set.

values()

Get all of the results set’s variables values.

class pz_solution(circ, poles, zeros, outfile)

Bases: ahkab.results.solution, ahkab.results._mutable_data

PZ results

Parameters:

circ : circuit instance

the circuit instance of the simulated circuit.

poles : sequence

the circuit zeros

zeros : sequence

the circuit poles

outfile : str

the filename of the save file.

asarray()

Return all data.

Note

This method loads to memory a possibly huge data matrix.

get(name, default=None)

has_key(name)

Determine whether the result set contains a variable.

items()

keys()

Get all of the results set’s variable’s names.

next()

values()

Get all of the results set’s variable’s values.

class solution(circ, outfile)

Bases: object

Base class storing a set of generic simulation results.

This class is not meant to be accessed directly, rather it is subclassed by the classes for the specific simulation solutions.

Parameters:

circ : circuit instance

the circuit instance of the simulated circuit.

outfile : string

the filename of the save file

asarray()

Return all data.

Note

This method loads to memory a possibly huge data matrix.

get(name, default=None)

Get a solution by variable name.

has_key(name)

Determine whether the result set contains a variable.

items()

keys()

Get all of the results set’s variables names.

next()

values()

Get all of the results set’s variables values.

class symbolic_solution(results_dict, substitutions, circ, outfile=None, tf=False)

Bases: object

Symbolic results

Parameters:

results_dict : dict

the results dict returned by sympy.solve(),

substitutions : dict

the substitutions (dictionary) employed before solving,

circ : circuit instance

the circuit instance of the simulated circuit.

outfile : str, optional

the filename of the save file. Use "stdout" to write to the standard output.

tf : bool, optional

Transfer function flag: set this to True if this set of results corrsponds to a transfer function. Defaults to False.

as_symbol(variable)

Converts a string to the corresponding symbolic variable.

This symbol may then be used by the user as an atom to construct new expressions, modify the results expressions or it can be passed to Sympy’s functions.

Parameters:

variable : string

The string that identifies the variable. Eg. 'R1' for the variable corresponding to the resistance of the resistor R1. Note that the case is disregarded and that the first letter defines the type of the element (resistor, capacitor...).

Returns:

symbol : Sympy symbol

The corresponding symbol, if it exists in the result set.

Raises:

ValueError : exception

In case no such symbol is found.

as_symbols(spacedstr)

Convenience function to call as_symbol() multiple times.

Parameters:

spacedstr : string,

A string containing several symbol identifiers separated by spaces. Eg. 'R1 C2 L3'.

Returns:

(s1, s2, ...) : tuple of Sympy symbol instances

The symbols corresponding to the identifiers in the string supplied, ordered as the identifiers in the string.

Raises:

ValueError : exception

In case any corresponding symbol is not found.

get(name, default=None)

Get the solution corresponding to a variable.

has_key(name)

Determine whether the result set contains a variable.

items()

Get all solutions.

keys()

Get all of the results set’s variable’s names.

static load(filename)

Static method to load a symbolic solution from disk.

Parameters:

filename : str

The filename corresponding to the file to load from.

Returns:

sol : symbolic solution instance

The solution instance loaded from disk.

Warning

This method employs pickle.load, which is to be used exclusively on trusted data. Only load trusted simulation files!

next()

save()

Write the results to disk.

It is necessary first to set the filename attribute, indicating which file to write to.

Raises:

RuntimeError : exception

If the filename attribute is not set.

values()

Get all of the results set’s variable’s values.

class tran_solution(circ, tstart, tstop, op, method, outfile)

Bases: ahkab.results.solution, ahkab.results._mutable_data

Transient results

Parameters:

circ : circuit instance

the circuit instance of the simulated circuit.

tstart : float

the transient simulation start time.

tstop : float

the transient simulation stop time.

op : op_solution instance

the Operating Point (OP) used to start the transient analysis.

method : str

the differentiation method employed.

outfile : str

the filename of the save file. Use “stdout” to write to the standard output.

add_line(time, x)

This method adds a solution and its corresponding time value to the results set.

asarray()

Return all data.

Note

This method loads to memory a possibly huge data matrix.

get(name, default=None)

Get a solution by variable name.

get_x()

get_xlabel()

has_key(name)

Determine whether the result set contains a variable.

items()

keys()

Get all of the results set’s variables names.

lock()

next()

values()

Get all of the results set’s variables values.