sysloss.system

sysloss.system#

System is the primary class for power analysis.

Classes#

System

System to be analyzed.

Module Contents#

class System(name: str, source: sysloss.components.Source, *, group: str = '', rail: str = '')#

System to be analyzed.

The first component of a system must always be a Source.

Parameters:

  • name (str) – System name.

  • source (Source) – Source component.

  • group (str, optional) – Group name, for grouping components together.

  • rail (str, optional) – Voltage rail name of output voltage.

Raises:

ValueError – If source is not a Source class.

Examples

>>> sys = System("System name", Source("Vin", vo=12.0))
classmethod from_file(fname: str)#

Load system from .json file.

The .json file must previously have been saved with save().

Parameters:

fname (str) – File name.

Returns:

A new System instance.

Return type:

System

Raises:

ValueError – If file was created by a newer version of sysLoss.

Examples

>>> sys = System.from_file("my_system.json")
add_comp(parent: str | list, *, comp, group: str = '', rail: str = '')#

Add component to system.

Parameters:

  • parent (str | list) – Name of parent component(s) or power rail(s) to connect to.

  • comp (component) – Component (from components).

  • group (str, optional) – Group name, for grouping components together.

  • rail (str, optional) – Voltage rail name of output voltage (not applicable on loads). Must be unique.

Raises:

ValueError – If parent does not allow connection to component, or name is already used.

Examples

>>> sys.add_comp("Vin", comp=Converter("Buck", vo=1.8, eff=0.87), rail="IO_1V8")
>>> sys.add_comp("Buck", comp=PLoad("MCU", pwr=0.015), group="Main")
>>> sys.add_comp(["Vbatt", "USB_5V"], comp=PMux("Power mux", rs=[0.35, 0.4]))
add_source(source: sysloss.components.Source, *, group: str = '', rail: str = '')#

Add an additional Source to the system.

Parameters:

  • source (Source) – Source component.

  • group (str, optional) – Group name, for grouping components together.

  • rail (str, optional) – Voltage rail name of output voltage. Must be unique.

Raises:

ValueError – If source is not a Source class or name is already used.

Examples

>>> sys.add_source(Source("5V", vo=5.0, limits={"io": [0.0, 0.5]}))
change_comp(name: str, *, comp, group: str = '', rail: str = '')#

Replace component.

The new component can be of same type (parameter change), or a new type given that the parent component accepts the connection.

Parameters:

  • name (str) – Name of component to be changed.

  • comp (component) – Component (from components).

  • group (str, optional) – Group name, for grouping components together.

  • rail (str, optional) – Voltage rail name of output voltage (not applicable on loads). Must be unique.

Raises:

ValueError – If trying to change a source component to a different type, or if the target component does not exist or if the parent does not accept a connection to the new component or if the name is already used.

Examples

>>> sys.change_comp("Buck", comp=LinReg("LDO", vo=1.8))
del_comp(name: str, *, del_childs: bool = True)#

Delete component.

Deleting the last component (Source) in a system is not allowed. In a system with multiple sources, a source can only be deleted together with its child components.

Parameters:

  • name (str) – Name of component to delete.

  • del_childs (bool, optional) – Delete all child components as well., by default True

Raises:

ValueError – If the component does not exist, is the last source or a source with del_childs set to False.

Examples

>>> sys.del_comp("Buck", del_childs=True)
tree(name='')#

Print the tree structure of the system.

The tree object is generated with Rich.

Parameters:

name (str, optional) – Name of component to start with. If not given, print the entire system., by default “”

Raises:

ValueError – If the component name is invalid.

Examples

>>> sys.tree()
>>> sys.tree("5V")
solve(*, vtol: float = 1e-06, itol: float = 1e-06, maxiter: int = 10000, quiet: bool = True, phase: str = '', energy: bool = False, ta: float = 25.0, tags: dict = {}) → pandas.DataFrame#

Analyze steady-state of system.

Parameters:

  • vtol (float, optional) – Voltage tolerance., by default 1e-6

  • itol (float, optional) – Current tolerance., by default 1e-6

  • maxiter (int, optional) – Maximum number of iterations., by default 10000

  • quiet (bool, optional) – Do not print # of iterations used., by default True

  • phase (str, optional) – Load phase to analyze (all if not specified), by default “”

  • energy (bool, optional) – Show energy consumption per 24h., by default False

  • ta (float, optional) – Ambient temperature, by default 25.0°C

  • tags (dict, optional) – Tag-value pairs that will be added to the results table

Returns:

Analysis result.

Return type:

pd.DataFrame

Raises:

  • ValueError – If the specified phase is not defined. See set_phases().

  • RuntimeError – If a steady-state solution has not been found after maxiter iterations.

Examples

>>> sys.solve()
>>> sys.solve(energy=True)
>>> sys.solve(itol=1.0e-7, tags={"Column name": value})
rail_rep(*, vtol: float = 1e-06, itol: float = 1e-06, maxiter: int = 10000, quiet: bool = True, phase: str = '', energy: bool = False, ta: float = 25.0, tags: dict = {}) → pandas.DataFrame#

Voltage rail report.

The rail report first calls .solve(), then summarizes current, power and losses per voltage rail.

Parameters:

* – Parameters are identical to solve().

Returns:

Analysis result. If no voltage rails have been defined, the result is identical to that returned by solve().

Return type:

pd.DataFrame

Raises:

  • ValueError – If the specified phase is not defined. See set_phases().

  • RuntimeError – If a steady-state solution has not been found after maxiter iterations.

Examples

>>> sys.rail_rep()
params(limits: bool = False) → pandas.DataFrame#

Return component parameters.

Parameters:

limits (bool, optional) – Include limits., by default False

Returns:

System component parameters.

Return type:

pd.DataFrame

Examples

>>> sys.params()
>>> sys.params(limits=True)
limits() → pandas.DataFrame#

Return component limits.

A blank cell in the returned Pandas dataframe indicates that default limits apply.

Returns:

System component limits.

Return type:

pd.DataFrame

Examples

>>> sys.limits()
set_sys_phases(phases: dict)#

Define system level load phases.

Parameters:

phases (dict) – A dict defining the system level load phases. Each entry in the form ‘“name”: duration(s)’.

Raises:

ValueError – If the dict contains less than two load phases or ‘N/A’ is used as a phase name.

Examples

>>> sys.set_sys_phases({"sleep": 120.0, "transmit": 0.1, "move": 5.5})
get_sys_phases() → dict#

Get the system level load phases.

Returns:

System load phases. Empty dict if no phases have been defined.

Return type:

dict

Examples

>>> sys.get_sys_phases()
{"sleep": 120.0, "transmit": 0.1, "move": 5.5}
set_comp_phases(name: str, phase_conf: dict | list)#

Define component load phases.

Components that have no load phases defined are always active.

The Source, Converter, Linreg, PSwitch and PMux components support a list of active phases, and go into sleep mode if not active. In sleep mode, all components connected to the output are automatically turned off.

The load components supports a dict with specific load values for each phase. If a phase is not included in the dict, the load is turned off in that phase.

Parameters:

  • name (str) – Component name.

  • phase_conf (dict | list) – Phase configuration.

Raises:

ValueError – Component does not exist, or phase configuration is invalid.

Examples

>>> sys.set_comp_phases("Buck", ["transmit", "move"])
>>> sys.set_comp_phases("MCU", {"sleep":1e-6, "transmit":0.15, "move":0.085})
phases() → pandas.DataFrame#

Return load phases and parameters for all system components.

Returns:

DataFrame with parameters and load phases.

Return type:

pd.DataFrame

Examples

>>> sys.phases()
save(fname: str, *, indent: int = 4)#

Save system as a .json file.

Parameters:

  • fname (str) – Filename.

  • indent (int, optional) – Indentation to use in .json file, by default 4

Examples

>>> sys.save("System 42.json", indent=3)
plot_interp(name: str, *, cmap: matplotlib.colors.Colormap = 'viridis', inpdata: bool = True, plot3d: bool = False) → matplotlib.figure.Figure | None#

Plot 1D or 2D interpolation data.

If a component has a parameter defined as either 1D or 2D interpolation data, a figure is returned with linear interpolation shown. 1D data is plotted as an interpolated line. 2D data can be shown as 2D color map or 3D surface. The interpolated data is extended to +/-15% outside of input data points.

Parameters:

  • name (str) – Name of component.

  • cmap (matplotlib.colors.Colormap, optional) – Colormap to use for 3D-plot., by default “viridis”

  • inpdata (bool, optional) – Show input data (as red dots)., by default True

  • plot3d (bool, optional) – Plot 3D surface (for 2D data), by default False

Returns:

Interpolated parameter data figure. If the component does not have interpolation data, None is returned.

Return type:

matplotlib.figure.Figure | None

Raises:

ValueError – If component name is not found.

Examples

>>> fig1 = sys.plot_interp("Buck", cmap="magma")
>>> fig2 = sys.plot_interp("Buck", inpdata=False, plot3d=True)
batt_life(battery: str, *, cutoff: float, pfunc: Callable[[], tuple[float, float, float]], dfunc: Callable[[float, float], tuple[float, float, float]], tags: dict = {}) → pandas.DataFrame#

Estimate battery life.

Battery life estimation requires an external battery model. The battery model is accessed using two callback functions - one for battery probing and one for battery depletion. If system load phases have been defined, the estimation process loops through the phases until the battery is depleted or the cutoff voltage has been reached. In a system without load phases the process depletes the battery in ~1000 time steps.

Parameters:

  • battery (str) – Name of battery (source) to be depleted

  • cutoff (float) – End simulation when battery voltage reaches cutoff or capacity is depleted, whichever comes first.

  • pfunc (Callable[[], tuple[float, float, float]]) – Battery probe callback function, must return tuple with remaining capacity (Ah), battery voltage (V) and battery impedance (Ohm)

  • dfunc (Callable[[float, float], tuple[float, float, float]]) – Battery deplete callback function. Function arguments are time (s) and current (A). Must return tuple with same format as pfunc.

  • tags (dict, optional) – Tag-value pairs that will be added to the results table

Returns:

Battery depletion data.

Return type:

pd.DataFrame

Raises:

ValueError – If battery name is not found or component is not a source.

Examples

>>> sys.batt_life("LiPo 3.7V", cutoff=2.9, pfunc=my_probe_func, dfunc=my_deplete_func)