zero.solution module

Plotting functions for solutions to simulations

exception zero.solution.NoDataException

Bases: Exception

class zero.solution.Solution(frequencies, name=None)

Bases: object

Represents a solution to the simulated circuit

DEFAULT_GROUP_NAME = '__default__'

DEFAULT_REF_GROUP_NAME = 'reference'

NOISE_GROUPS_ALL = 'all'

NOISE_LABELS_ALL = 'all'

NOISE_SINKS_ALL = 'all'

NOISE_SOURCES_ALL = 'all'

NOISE_TYPES_ALL = 'all'

RESPONSE_GROUPS_ALL = 'all'

RESPONSE_LABELS_ALL = 'all'

RESPONSE_SINKS_ALL = 'all'

RESPONSE_SOURCES_ALL = 'all'

add_noise(spectral_density, default=False, group=None)

Add a noise spectral density to the solution.

Parameters

• spectral_density (NoiseDensity) – The noise spectral density to add.

• default (bool, optional) – Whether this noise spectral density is a default.

• group (str, optional) – The function group. If None, the default is used.

Raises

ValueError – If the specified noise spectral density is incompatible with this solution or not single-source or single-sink.

add_noise_reference(*args, reference=None, **kwargs)

add_noise_sum(noise_sum, default=False, group=None)

Add a noise sum to the solution.

Parameters

• noise_sum (MultiNoiseDensity) – The noise sum to add.

• default (bool, optional) – Whether this noise sum is a default.

• group (str, optional) – The function group. If None, the default is used.

Raises

ValueError – If the specified noise sum is incompatible with this solution or not multi-source.

add_response(response, default=False, group=None)

Add a response to the solution.

Parameters

• response (Response) – The response to add.

• default (bool, optional) – Whether this response is a default.

• group (str, optional) – Group name.

Raises

ValueError – If the specified response is incompatible with this solution.

add_response_reference(*args, reference=None, **kwargs)

combine(*others, name=None, merge_groups=False)

Combine this solution with the specified other solution(s).

The groups of each solution are copied to a new, combined solution. By default, the group names have the source solution’s name appended as a suffix in the form “group name (solution name)”, unless the group is the default group, in which case the functions are placed in a group with the solution name only. When the merge_groups flag is True, in cases where groups from each solution have the same name, their functions are combined into a single new group as long as none of the functions are present in both source groups.

To be able to be combined, the two solutions must have equivalent frequency vectors, and cannot have the same name.

Parameters

• *others (sequence of Solution) – The solution(s) to combine.

• name (str, optional) – The name to give to the combined solution. Defaults to the “A + B + …” where “A”, “B”, etc. are the source solutions.

Returns

Solution – The combined solution.

Raises

• ValueError – If the solutions have the same name.

• ValueError – If the solutions have different frequency vectors.

• ValueError – If an identical function with an identical group is present in both solutions.

property component_noise

property default_functions

Default responses and noise spectra

difference(other, **kwargs)

Get table containing the difference between this solution and the specified one.

equivalent_to(other, **kwargs)

Checks if the specified other solution has equivalent, identical functions to this one.

Parameters

other (Solution) – The other solution to compare to.

Other Parameters

• defaults_only (bool, optional) – Whether to check only the default functions, or everything. Defaults to everything.

• meta_only (bool, optional) – Whether to check only meta data, not function data, when comparing. Defaults to False.

Returns

bool – True if equivalent, False otherwise.

filter_noise(group=None, groups=None, source=None, sources=None, sink=None, sinks=None, label=None, labels=None, type=None, types=None)

Filter for noise spectra.

This does not include sums.

filter_noise_sums(group=None, groups=None, sink=None, sinks=None, label=None, labels=None, type=None, types=None)

Filter for noise sums.

filter_responses(group=None, groups=None, source=None, sources=None, sink=None, sinks=None, label=None, labels=None)

function_group(function)

Get function group

get_group_functions(group=None)

Get functions by group

get_noise(source=None, sink=None, group=None, label=None)

Get noise spectral density from specified source to specified sink.

This is a convenience method for filter_noise() for when only a single noise spectral density is required.

Parameters

• source (str or Noise, optional) – The noise source element.

• sink (str or Node or Component, optional) – The noise sink element.

• group (str, optional) – The noise group. If None, the default group is assumed.

• label (str, optional) – The noise label.

Returns

NoiseDensity – The matched noise spectral density.

Raises

ValueError – If no noise spectral density is found, or if more than one matching noise spectral density is found.

Examples

Get noise arising from op-amp op1’s voltage noise at node nout using string specifiers:

>>> get_noise("V(op1)", "nout")

Get noise arising from op-amp op1’s voltage noise at component op2 using objects:

>>> get_noise(op1.voltage_noise, op2)

Get noise arising from op-amp op1’s voltage noise at node nout, searching only in group b:

>>> get_noise("V(op1)", "nout", group="b")

get_noise_sink(sink_name)

get_noise_source(source_name)

get_noise_sum(sink=None, group=None, label=None)

Get noise sum with the specified label.

Parameters

• sink (str or Node or Component, optional) – The noise sink element.

• group (str, optional) – The noise group. If None, the default group is assumed.

• label (str, optional) – The noise label.

Returns

MultiNoiseDensity – The matched noise sum.

Raises

ValueError – If no noise sum is found.

get_response(source=None, sink=None, group=None, label=None)

Get response from specified source to specified sink.

This is a convenience method for filter_responses() for when only a single response is required.

Parameters

• source (str or Node or Component, optional) – The response source element.

• sink (str or Node or Component, optional) – The response sink element.

• group (str, optional) – The response group. If None, the default group is assumed.

• label (str, optional) – The response label.

Returns

Response – The matched response.

Raises

ValueError – If no response is found, or if more than one matching response is found.

Examples

Get response from node nin to node nout using string specifiers:

>>> get_response("nin", "nout")

Get response from node nin to component op1 using objects:

>>> get_response(Node("nin"), op1)

Get response from node nin to node nout, searching only in group b:

>>> get_response("nin", "nout", group="b")

get_response_sink(sink_name)

get_response_source(source_name)

property groups

property has_noise

property has_noise_sums

property has_responses

is_default_noise(noise, group=None)

is_default_noise_sum(noise_sum, group=None)

is_default_response(response, group=None)

merge_group(source_group, target_group)

Merge functions from source group into target group.

The source group cannot contain any functions in the target group.

Raises

• ValueError – If the source or target group is the reference group.

• ValueError – If a function in the source group matches one already present in the target group.

move_default_group_functions(new_group)

Move the default group’s functions to a new group.

The default group will still be used for any new functions added to the solution with no explicit group, as usual.

property n_frequencies

property name

property noise

property noise_sinks

property noise_sources

Get noise sources.

Returns

noise sources

property noise_sums

property opamp_noise

plot()

plot_noise(figure=None, group=None, groups=None, source=None, sources=None, sink=None, sinks=None, type=None, types=None, show_individual=True, show_sums=True, xlabel=None, ylabel=None, **kwargs)

Plot noise.

Note: if only some of “groups”, “sources”, “sinks”, “types” are specified, the others default to “all” as per the behaviour of filter_noise().

Parameters

• figure (Figure, optional) – Figure to plot to. If not specified, a new figure is created.

• group, groups (str or list of str, optional) – The noise group(s) to plot. If None, the default group is assumed.

• source, sources (str or list of str or Noise, optional) – The noise source(s) to plot at the specified sinks. If None, all matched sources are plotted.

• sink, sinks (str or list of str, Component or Node, optional) – The sink(s) to plot noise at. If None, all matched sinks are plotted.

• type, types (str or list of str, optional) – The noise type(s) to plot. If None, all matched noise types are plotted.

• show_individual (bool, optional) – Plot any individual noise spectra contained in this solution.

• show_sums (bool, optional) – Plot any sums contained in this solution.

• xlabel, ylabel (str, optional) – The x- and y-axis labels.

Other Parameters

• legend (bool, optional) – Display legend.

• legend_loc (str, optional) – Legend display location. Defaults to “best”.

• legend_groups (bool, optional) – Display function group names in legends, if the group is not the default.

• title (str, optional) – The plot title.

• xlim, ylim (sequence of float, optional) – The lower and upper limits for the x- and y-axes.

Returns

BasePlotter – The plotter object.

plot_responses(figure=None, group=None, groups=None, source=None, sources=None, sink=None, sinks=None, xlabel=None, ylabel_mag=None, ylabel_phase=None, scale_db=True, **kwargs)

Plot responses.

Note: if only one of “sources” or “sinks” is specified, the other defaults to “all” as per the behaviour of filter_responses().

Parameters

• figure (Figure, optional) – Figure to plot to. If not specified, a new figure is created.

• group, groups (str or list of str, optional) – The response group(s) to plot. If None, the default group is assumed.

• source, sources, sink, sinks (str or list of str, Component) – or Node The source(s) and sink(s) to plot responses between. If None, all matched sources and sinks are plotted.

• xlabel, ylabel_mag, ylabel_phase (str, optional) – The x- and y-axis labels for the magnitude and phase plots.

• scale_db (bool, optional) – Scale the magnitude y-axis values in decibels. If False, absolute scaling is used.

Other Parameters

• legend (bool, optional) – Display legend.

• legend_loc (str, optional) – Legend display location. Defaults to “best”.

• legend_groups (bool, optional) – Display function group names in legends, if the group is not the default.

• title (str, optional) – The plot title.

• xlim, mag_ylim, phase_ylim (sequence of float, optional) – The lower and upper limits for the x- and y-axes for the magnitude and phase plots.

• db_tick_major_step, db_tick_minor_step (float, optional) – The magnitude y axis tick step sizes when scale_db is enabled. Defaults to 20 and 10 for the major and minor steps, respectively.

• phase_tick_major_step, phase_tick_minor_step (float, optional) – The phase y axis tick step sizes when scale_db is enabled. Defaults to 30 and 15 for the major and minor steps, respectively.

Returns

BasePlotter – The plotter object.

rename_group(source_group, new_group)

Rename the specified group, moving all of its functions to the new group.

The new group must not already exist. If it does, merge_group() should be used instead.

Raises

ValueError – If the new group already exists.

replace(current_function, new_function, group=None)

Replace existing function with the specified function.

property resistor_noise

property response_sinks

property response_sources

property responses

scale_noise(scale, include_singular=True, include_sums=True, **kwargs)

Apply a scaling to noise matching the specified filters.

Supports the keyword arguments of filter_noise().

Parameters

• scale (number or BaseFunction) – The scaling to apply to the matched noise.

• include_singular (bool, optional) – Scale single noise functions.

• include_sums (bool, optional) – Scale noise sums.

scale_responses(scale, **kwargs)

Apply a scaling to responses matching the specified filters.

Supports the keyword arguments of _apply_response_filters().

Parameters

scale (number or BaseFunction) – The scaling to apply to the matched responses.

set_noise_as_default(spectral_density, group=None)

Set the specified noise spectral density as a default

set_noise_sum_as_default(noise_sum, group=None)

Set the specified noise sum as a default

set_response_as_default(response, group=None)

Set the specified response as a default.

Parameters

• response (Response) – The response to set as default.

• group (str, optional) – The function group. If None, the default is used.

Raises

ValueError – If response is not part of this solution or already set as a default.

show()

Show plot(s).

sort_functions(key_function, default_only=False)

Sort functions using specified callback.

Parameters

• key_function (callable) – Function that yields a key given a BaseFunction.

• default_only (bool, optional) – Whether to sort only the default functions.

zero.solution.matches_between(sol_a, sol_b, defaults_only=False, meta_only=False)

Finds matching functions in the specified solutions. Ignores groups.

Parameters

• sol_a, sol_b (Solution) – The solutions to compare.

• defaults_only (bool, optional) – Whether to check only the default functions, or everything. Defaults to everything.

• meta_only (bool, optional) – Whether to check only meta data, not function data, when comparing. Defaults to False.

Returns

• matches (list) – Matching pairs from each solution.

• residuals_a, residuals_b (list) – Functions only present in the first or second solutions, respectively.