Storage module

class wavefronts.storage.Input_Data(**provided_input_values)

Bases: object

The storage object for the input varibles of a interface simulation. Calculates all the associated variables required for the simulaitons. Can be used to investigate network calcualted parameters based off input vairbles. It also stores and calculates all the interaction functions of the interface.

Is initialised using key-word arguments. All values with the provided keys are of type string. This each input variable is converterted to a Decimal value to be used for precision calculations. The possible parameters to change and their defualt values are as follows,

Parameters:

L_impedance (String) – Characteristic impedance of the inductor, assigned to self.Inductor_Impedance (default:’100’)
L_time (String) – The time delay of the inductor in seconds, assigned to self.Inductor_Time (default:’1’)
L_length (String) – The length of the inductor in meters, assigned to self.Inductor_Length (default:’1’)
C_impedance (String) – Characteristic impedance of the capacitor, assigned to self.Capacitor_Impedance (default:’1’)
C_time (String) – The time delay of the capacitor in seconds, assigned to self.Capacitor_Time (default:’1’)
C_length (String) – The length of the capacitor in meters, assigned to self.Capacitor_Length (default:’1’)
V_source (String) – The magnitude of the initial voltage excitation in volts, assigned to self.Voltage_Souce_Magnitude (default:’1’)
number_periods (String) – The number of periods as according to Lumped-Element LC-Osscilator solution. Used to calculate the simulation stop time if provided. Overidden if ‘Simulation_stop_time’ is provided (default:’1’)
Load_impedance (String) – The magnitude of the load resistance, if left inf the load is ignored and the interface takes form of an LC-Osscilator. If a value is provided the load is considered and the self.Is_Buck flag is set to True (default:’inf’)
Simulation_stop_time (String) – The time to which the interface will be simulated. If provided it will overwrite the ‘number_periods’ simulation stop time calculation (default:’0’)
show_about (Boolean) – Indicates information about the calcualted variabels must be printed (default:True)

Stored and Calculated Parameters:

self.Number_Periods (Decimal) - given or calcualted number of periods
self.Simulation_Stop_Time (Decimal) - given or calculated simulation stop time (s)
self.Is_Buck (bool) - if the load across the capacitor is considered or not
self.GCD (Decimal) - The greatest common denomenator of the capacitor and inductor time delays.
self.LCM (Decimal) - The lowest common multiple of the capacitor and inductor time delays.
self.Capacitor_LCM_Factor (int) - The co-factor of the capacitor time delay required to make the LCM
self.Inductor_LCM_Factor (int) - The co-factor of the inductor time delay required to make the LCM
self.is_Higher_Merging (bool) - Indicates if multiplicative merging will occur for the given simulaiton stop time
self.Number_of_Wavefronts (int) - The total number of sending and returning wavefronts calculated
self.Number_of_Layers (int) - The total number of fanout-layers simulated
self.Voltage_Souce_Magnitude (Decimal) - the magnitude of the voltage excitation (V)
self.Load_Resistance (Decimal) - the magnitude of the load resistor (Ohm)

Stored Inductor Parameters:

self.Inductor_Inductance_Per_Length (Decimal) - the per length inductance of the inductor (H/m)
self.Inductor_Capacitance_Per_Length (Decimal) - the per length capacitance of the inductor (F/m)
self.Inductor_Length (Decimal) - the total length of the inductor (m)
self.Inductor_Total_Inductance (Decimal) - the total inductance of the inductor (H)
self.Inductor_Total_Capacitance (Decimal) - the total capacitance of the inductor (F)
self.Inductor_Velocity (Decimal) - the propagation velocity of the inductor (m/s)
self.Inductor_Time (Decimal) - the one way transit time of the inductor (s)
self.Inductor_Impedance (Decimal) - the characteristic impedance of the inductor (Ohm)

Stored Capacitor Parameters:

self.Capacitor_Inductance_Per_Length (Decimal) - the per length inductance of the capacitor (H/m)
self.Capacitor_Capacitance_Per_Length (Decimal) - the per length capacitance of the capacitor (F/m)
self.Capacitor_Length (Decimal) - the total length of the capacitor (m)
self.Capacitor_Total_Inductance (Decimal) - the total inductance of the capacitor (H)
self.Capacitor_Total_Capacitance (Decimal) - the total capacitance of the capacitor (F)
self.Capacitor_Velocity (Decimal) - the propagation velocity of the capacitor (m/s)
self.Capacitor_Time (Decimal) - the one way transit time of the capacitor (s)
self.Capacitor_Impedance (Decimal) - the characteristic impedance of the capacitor (Ohm)

Dictionary for Spice simulation:

SPICE_input_values (dict) - a list of altered input parameters compatible with verification.get_Spice_Arrays().

Example use of Input_Data

from wavefronts.storage import Input_Data
from wavefronts.generation import generate_commutative_data

data_input = Input_Data(Simulation_stop_time = '100',L_impedance = '225')
print(data_input.Simulation_Stop_Time) # prints '100'
print(data_input.Capacitor_Impedance) # prints '1', assigned by default.

# generate the output wavefronts from the created Input_Data object:
data_output = generate_commutative_data(data_input)

Advanced - change the termination function to make the circuit a RC charger

from wavefronts.storage import Input_Data
from wavefronts.generation import generate_interface_data
from wavefronts.plotting import make_time_interconnect_all
from copy import copy
from decimal import Decimal 
import builtins
import matplotlib.pyplot as plt

# generate a data input array
data_input_1 = Input_Data(L_time = '1',C_time='7')
# generate interface data storage object
interface_1 = generate_interface_data(data_input_1)

# create a copy of data_1
data_input_2 = copy(data_input_1)

# setup a new termination function
R = Decimal('10')
ZL = data_input_2.Inductor_Impedance
def new_inductor_termination_func(V_arrive,I_arrive):
    V_out = I_arrive * (1/(1/R + 1/ZL)) - V_arrive*ZL/(R +ZL )
    I_out = -(V_out/ZL)

    return V_out, I_out

# replace the old termination funciton
builtins.setattr(data_input_2, 'termination_event_solver_inductor',new_inductor_termination_func)

# generate interface data storage object unsing the altered data_input
interface_2 = generate_interface_data(data_input_2)

# plot data 
fig_1, axes_1 = make_time_interconnect_all(interface_1)
fig_2, axes_2 = make_time_interconnect_all(interface_2)

fig_1.suptitle("LC - Osscilator")
fig_2.suptitle("RC - Charger")
axes_2['VL'].set_title("Resistor Votlage at Interconnect")
axes_2['IL'].set_title("Resistor Current at Interconnect")

plt.show()

circuit_solver_inductor_voltage(VL: Decimal, IL: Decimal, VC: Decimal, IC: Decimal)

Generates the voltage response of the inductor to wavefront distrubances. Solves by means of the wavefront equivalent circuit.

Parameters:

VL (Decimal) – the magnitude of the voltage disturbance from the inductor
IL (Decimal) – the magnitude of the current disturbance from the inductor
VC (Decimal) – the magnitude of the voltage disturbance from the capacitor
IC (Decimal) – the magnitude of the current disturbance from the capacitor

Returns:

the the magnitude of the voltage response of the inductor to the disturbance

Return type:

Decimal

circuit_solver_inductor_current(VL: Decimal, IL: Decimal, VC: Decimal, IC: Decimal)

Generates the current response of the inductor to wavefront distrubances. Solves by means of the wavefront equivalent circuit.

Parameters:

VL (Decimal) – the magnitude of the voltage disturbance from the inductor
IL (Decimal) – the magnitude of the current disturbance from the inductor
VC (Decimal) – the magnitude of the voltage disturbance from the capacitor
IC (Decimal) – the magnitude of the current disturbance from the capacitor

Returns:

the the magnitude of the current response of the inductor to the disturbance

Return type:

Decimal

circuit_solver_inductor_source_voltage(VS: Decimal)

The magnitude of the voltage response of the inductor to a voltage source excitation.

Parameters:: VS (Decimal) – magnitude of soure voltage excitation.
Returns:: the the magnitude of the voltage response of the inductor to the disturbance
Return type:: Decimal

circuit_solver_inductor_source_current(VS: Decimal)

The magnitude of the current response of the inductor to a voltage source excitation.

Parameters:: VS (Decimal) – magnitude of soure voltage excitation.
Returns:: the the magnitude of the current response of the inductor to the disturbance
Return type:: Decimal

circuit_solver_capacitor_voltage(VL: Decimal, IL: Decimal, VC: Decimal, IC: Decimal)

Generates the voltage response of the capacitor to wavefront distrubances. Solves by means of the wavefront equivalent circuit.

Parameters:

VL (Decimal) – the magnitude of the voltage disturbance from the inductor
IL (Decimal) – the magnitude of the current disturbance from the inductor
VC (Decimal) – the magnitude of the voltage disturbance from the capacitor
IC (Decimal) – the magnitude of the current disturbance from the capacitor

Returns:

the the magnitude of the voltage response of the capacitor to the disturbance

Return type:

Decimal

circuit_solver_capacitor_current(VL: Decimal, IL: Decimal, VC: Decimal, IC: Decimal)

Generates the current response of the capacitor to wavefront distrubances. Solves by means of the wavefront equivalent circuit.

Parameters:

VL (Decimal) – the magnitude of the voltage disturbance from the inductor
IL (Decimal) – the magnitude of the current disturbance from the inductor
VC (Decimal) – the magnitude of the voltage disturbance from the capacitor
IC (Decimal) – the magnitude of the current disturbance from the capacitor

Returns:

the the magnitude of the current response of the capacitor to the disturbance

Return type:

Decimal

circuit_solver_capacitor_source_voltage(VS: Decimal)

The magnitude of the voltage response of the capacitor to a voltage source excitation.

Parameters:: VS (Decimal) – magnitude of soure voltage excitation.
Returns:: the the magnitude of the voltage response of the capacitor to the disturbance
Return type:: Decimal

circuit_solver_capacitor_source_current(VS: Decimal)

The magnitude of the current response of the capacitor to a voltage source excitation.

Parameters:: VS (Decimal) – magnitude of soure voltage excitation.
Returns:: the the magnitude of the current response of the capacitor to the disturbance
Return type:: Decimal

self_reflection_event_solver_inductor(Wavefront_Parent_voltage: Decimal, Wavefront_Parent_current: Decimal)

Calculates the voltage and current magnitude of a produced inductive wavefront due to an inductive self-reflection event. A self-reflection event is when a wavefron form a transmission line arrives at the interface and is reflected back into itself. The Parent wavefront’s parameters are passed to this function, the self reflected child wavefront magnitudes are calculated.

Parameters:

Wavefront_Parent_voltage (Decimal) – voltage of the parent wavefront arriving at the interface
Wavefront_Parent_current (Decimal) – current of the parent wavefront arriving at the interface

Returns:

(voltage, current ) of child wavefront

Return type:

Tuple

exitation_event_solver_inductor(Wavefront_Parent_voltage: Decimal, Wavefront_Parent_current: Decimal)

The voltage and current calcualtion of the inducitve wavefront produced due to a source excitation event.

Parameters:

Wavefront_Parent_voltage (Decimal) – voltage of the source excitation wavefront
Wavefront_Parent_current (Decimal) – current of the source excitation wavefront

Returns:

(voltage, current) of the produced inductive wavefront

Return type:

Tuple (Decimal, Decimal)

transmission_event_solver_inductor(Wavefront_Parent_voltage: Decimal, Wavefront_Parent_current: Decimal)

The voltage and current calculation of the inductive wavefront produced due to a capacitve wavefront arriving at the interface.

Parameters:

Wavefront_Parent_voltage (Decimal) – voltage of the incident capacitve wavefront
Wavefront_Parent_current (Decimal) – current of the incident capacitve wavefront

Returns:

(voltage, current) of the produced inductive wavefront

Return type:

Tuple (Decimal, Decimal)

termination_event_solver_inductor(Arriving_Voltage: Decimal, Arriving_Current: Decimal)

The voltage and current calcutation of the re-reflected wavefront produced when an inductive wavefront reaches its termination.

Parameters:

Arriving_Voltage (Decimal) – voltage of the wavefront arriving at the inductor termination
Arriving_Current (Decimal) – current of the wavefront arriving at the inductor termination

Returns:

(voltage, current) of the re-reflected inductive wavefront

Return type:

Tuple (Decimal, Decimal)

self_reflection_event_solver_capacitor(Wavefront_Parent_voltage: Decimal, Wavefront_Parent_current: Decimal)

Calculates the voltage and current magnitude of a produced capcaitve wavefront due to a capacitve self-reflection event. A self-reflection event is when a wavefront form a transmission line arrives at the interface and is reflected back into itself. The Parent wavefront’s parameters are passed to this function, the self reflected child wavefront magnitudes are calculated.

Parameters:

Wavefront_Parent_voltage (Decimal) – voltage of the parent wavefront arriving at the interface
Wavefront_Parent_current (Decimal) – current of the parent wavefront arriving at the interface

Returns:

(voltage, current ) of child wavefront

Return type:

Tuple

exitation_event_solver_capacitor(Wavefront_Parent_voltage: Decimal, Wavefront_Parent_current: Decimal)

The voltage and current calcualtion of the capacitive wavefront produced due to a source excitation event.

Parameters:

Wavefront_Parent_voltage (Decimal) – voltage of the source excitation wavefront
Wavefront_Parent_current (Decimal) – current of the source excitation wavefront

Returns:

(voltage, current) of the produced capacitive wavefront

Return type:

Tuple (Decimal, Decimal)

transmission_event_solver_capacitor(Wavefront_Parent_voltage: Decimal, Wavefront_Parent_current: Decimal)

The voltage and current calculation of the capacitve wavefront produced due to a inductive wavefront arriving at the interface.

Parameters:

Wavefront_Parent_voltage (Decimal) – voltage of the incident inductive wavefront
Wavefront_Parent_current (Decimal) – current of the incident inductive wavefront

Returns:

(voltage, current) of the produced capacitve wavefront

Return type:

Tuple (Decimal, Decimal)

termination_event_solver_capacitor(Arriving_Voltage: Decimal, Arriving_Current: Decimal)

The voltage and current calcutation of the re-reflected wavefront produced when a capacitve wavefront reaches its termination.

Parameters:

Arriving_Voltage (Decimal) – voltage of the wavefront arriving at the capcitor termination
Arriving_Current (Decimal) – current of the wavefront arriving at the capcitor termination

Returns:

(voltage, current) of the re-reflected capacitve wavefront

Return type:

Tuple (Decimal, Decimal)

about(): Prints out information input varibles and associated calculated variables.

class wavefronts.storage.Wavefront

Bases: object

Base wavefront class. Assings basic wavefront parameters, all of Decimal type initialised to zero.

about(): Displays information anout the wavefront

position_at_time(time)

Generates the position of wavefront at time-equirey. Returns False if no intercept.

Parameters:: time (Decimal or str) – time enquirey
Returns:: position attime enquiret
Return type:: Decimal

class wavefronts.storage.Wavefront_Source(Data_input: Input_Data, time_start, magnitude=1)

Bases: Wavefront

Class representing switiching wavefronts of the voltage source. In this release wavefonts switching is not supported, this class used to initiated wavefronts at t=0 only.

generate_and_store(storage_Away: deque)

triggers the creation of the inital wavefronts in the inductor and capacitor. Stores them in the storage. Order is important, inductive first followed by capacitive.

Parameters:: storage (deque) – Storage array for away waves

class wavefronts.storage.Wavefront_Kintetic

Bases: Wavefront

An parent class for Inductive and Capacitve wavefronts. Contains the logic for determining how wavefronts respond to particualr events.

setup_wavefront(Wavefront_Parent: Wavefront, is_self_reflection: bool)

handles how the voltage and current of a newly produced wavefront must be assigned.

Parameters:

Wavefront_Parent (Wavefront) – The Parent wavefront that is producing this wavefronts
is_self_reflection (bool) – if the parent wavefront is in the same wavefront as the child. Limits the need for an isinstance check.

merge(Wavefront_Other: Wavefront)

superimposes two wavefronts by altering the voltage and current magnitudes of this wavefront.

Parameters:: Wavefront_Other (Wavefront) – Partner Wavefront to be merging

self_reflection_event_solver(Wavefront_Parent_voltage, Wavefront_Parent_current)

exitation_event_solver(Wavefront_Parent_voltage, Wavefront_Parent_current)

transmission_event_solver(Wavefront_Parent_voltage, Wavefront_Parent_current)

termination_event_solver(Wavefront_Parent_voltage, Wavefront_Parent_current)

class wavefronts.storage.Wavefront_Capacitive(input_data: Input_Data, Wavefront_Parent: Wavefront, is_self_reflection: bool)

Bases: Wavefront_Kintetic

A wavefront travelling in the capacitor. Follows the “wavefronts create wavefronts” paradigm.

generate_and_store(storage: deque)

Generates and stores wavefronts the childern wavefront in a que to be processed

Parameters:: storage (deque) – The deque of wavefronts that are actively being processed

generate_and_return()

Generates the children wavefront/s of this wavefront without directly storing them.

Returns:: children wavefront/s
Return type:: Tuple (Wavefront_Inductive, Wavefront_Capacitive) or Wavefront_Capacitive

class wavefronts.storage.Wavefront_Inductive(input_data: Input_Data, Wavefront_Parent: Wavefront, is_self_reflection: bool)

Bases: Wavefront_Kintetic

A wavefront travelling in the inductor. Follows the “wavefronts create wavefronts” paradigm.

generate_and_store(storage)

Generates and stores wavefronts the childern wavefront in a que to be processed

Parameters:: storage (deque) – The deque of wavefronts that are actively being processed

generate_and_return()

Generates the children wavefront/s of this wavefront without directly storing them.

Returns:: children wavefront/s
Return type:: Tuple (Wavefront_Inductive, Wavefront_Capacitive) or Wavefront_Inductive

class wavefronts.storage.Output_Data(Time: ndarray, Voltage_Interconnect_Inductor: ndarray, Current_Interconnect_Inductor: ndarray, Voltage_Interconnect_Capacitor: ndarray, Current_Interconnect_Capacitor: ndarray, Wavefronts_Sending_Inductor: ndarray, Wavefronts_Sending_Capacitor: ndarray, Wavefronts_Returning_Inductor: ndarray, Wavefronts_Returning_Capacitor: ndarray, has_merged: bool)

Bases: object

Stores data of various types of fanout diagrams after simulation. Stores information for commutatively merged fanouts, as well as, multipicatively merged fanouts.

Fanout diagrams take form of 2D numpy arrays of format Array[L,C] where L is the inductive event number and C the capacitve event number. There are a total of 9 arrays stored, one for the arrival time of each grid node, four for the current and voltage at the interconncet for the capacitor and inductor, and another four for the sending and returning wavefronts of the capacitor and inductor.

Parameters:

Time (np.ndarray[Decimal]) – 2D numpy array of the return times of grid nodes
Voltage_Interconnect_Inductor (np.ndarray[Decimal]) – 2D numpy array of the interconnect voltage change of the inductor at a grid node
Current_Interconnect_Inductor (np.ndarray[Decimal]) – 2D numpy array of the interconnect current change of the inductor at a grid node
Voltage_Interconnect_Capacitor (np.ndarray[Decimal]) – 2D numpy array of the interconnect voltage change of the capacitor at a grid node
Current_Interconnect_Capacitor (np.ndarray[Decimal]) – 2D numpy array of the interconnect current change of the capacitor at a grid node
Wavefronts_Sending_Inductor (np.ndarray[Wavefront_Inductive]) – 2D numpy array of the wavefronts sent into the inductor at grid nodes
Wavefronts_Sending_Capacitor (np.ndarray[Wavefront_Capacitive]) – 2D numpy array of the wavefronts sent into the capacitor at grid nodes
Wavefronts_Returning_Inductor (np.ndarray[Wavefront_Inductive]) – 2D numpy array of the wavefronts returning from the inductor at grid nodes
Wavefronts_Returning_Capacitor (np.ndarray[Wavefront_Capacitive]) – 2D numpy array of the wavefronts returning from the capacitor at grid nodes
has_merged (bool) – indicates if the data stored has been multiplicatively merged or not.

Example use of Output_Data

from wavefronts.storage import Input_Data
from wavefronts.generation import generate_commutative_data, generate_multiplicative_data


# Generate input data object from input paramters
data_input = Input_Data(Simulation_stop_time = '100',L_impedance = '225')

# Generate the commutative merging output data from the created Input_Data object:
data_output_commutative : Output_Data = generate_commutative_data(data_input)
# Get sending wavefronts of the capacitor after only commutative merging:
data_output_commutative.Wavefronts_Sending_Capacitor

# Generate the merged data after multiplicative merging:
data_output_merged  : Output_Data = generate_multiplicative_data(data_input,data_output_commutative)
# Get sending wavefronts of the capacitor after multiplicative merging:
data_output_merged.Wavefronts_Sending_Capacitor

Time: ndarray

Voltage_Interconnect_Inductor: ndarray

Current_Interconnect_Inductor: ndarray

Voltage_Interconnect_Capacitor: ndarray

Current_Interconnect_Capacitor: ndarray

Wavefronts_Sending_Inductor: ndarray

Wavefronts_Sending_Capacitor: ndarray

Wavefronts_Returning_Inductor: ndarray

Wavefronts_Returning_Capacitor: ndarray

has_merged: bool

get_interconnect_array(which_string)

A method for getting interconnect arrays with a sting enquirey.

Parameters:: which_string (str) – possible options: [“voltage inductor”, “current inductor”, “voltage capacitor”, “current capacitor”]
Raises:: ValueError – errors if incorrect string is given.
Returns:: the matching interconnect array
Return type:: np.ndarray[Decimal]

get_sending_wavefronts_magnitudes(which_string)

A method for extracting voltage or current from sending wavefronts.

Parameters:: which_string (str) – possible options: [“voltage inductor”, “current inductor”, “voltage capacitor”, “current capacitor”]
Raises:: ValueError – errors if incorrect string is given.
Returns:: Sending wavefront’s Current or Voltage magnitudes
Return type:: np.ndarray[Decimal]

get_returning_wavefronts_magnitudes(which_string)

A method for extracting voltage or current from returning wavefronts.

Parameters:: which_string (str) – possible options: [“voltage inductor”, “current inductor”, “voltage capacitor”, “current capacitor”]
Raises:: ValueError – errors if incorrect string is given.
Returns:: Returning wavefront’s Current or Voltage magnitudes
Return type:: np.ndarray[Decimal]

class wavefronts.storage.Ordered_Output_Data(Time: ndarray, Voltage_Interconnect_Inductor: ndarray, Current_Interconnect_Inductor: ndarray, Voltage_Interconnect_Capacitor: ndarray, Current_Interconnect_Capacitor: ndarray, Wavefronts_Sending_Inductor: ndarray, Wavefronts_Sending_Capacitor: ndarray, Wavefronts_Returning_Inductor: ndarray, Wavefronts_Returning_Capacitor: ndarray, has_merged: bool, Indexes: ndarray)

Bases: Output_Data

A dataclass that stores ordered inteface output data in form of single dimenstional arrays. All the core arrays that are present in the Output_Data class are present here but in a one-dimensional chronological form.

Parameters:: Indexes (List[Lists]) – An additonal array, indicating the grid co-ordiantes on the merged fanout structure in the order events occured. Is a single dimesional list of (L,C) coordiante lists. The inner lists take form of [L,C].

Indexes: ndarray

get_sending_wavefronts_magnitudes(which_string)

A method for extracting voltage or current from sending wavefronts.

Parameters:: which_string (str) – possible options: [“voltage inductor”, “current inductor”, “voltage capacitor”, “current capacitor”]
Raises:: ValueError – errors if incorrect string is given.
Returns:: Sending wavefront’s Current or Voltage magnitudes
Return type:: np.ndarray[Decimal]

get_returning_wavefronts_magnitudes(which_string)

A method for extracting voltage or current from returning wavefronts.

Parameters:: which_string (str) – possible options: [“voltage inductor”, “current inductor”, “voltage capacitor”, “current capacitor”]
Raises:: ValueError – errors if incorrect string is given.
Returns:: Returning wavefront’s Current or Voltage magnitudes
Return type:: np.ndarray[Decimal]

class wavefronts.storage.Interface_Data(data_input: Input_Data, data_output_commutative: Output_Data, data_output_multiplicative: Output_Data, data_output_ordered: Ordered_Output_Data)

Bases: object

A Dataclass that holds all simulation data for a praticular interface. Contains four data storage components that are also the initialization parameters. The best way to create this Data storage object is through generation.generate_interface_data()

Parameters:

data_input (Input_Data) – input data and calcualted parameters of the interface
data_output_commutative (Output_Data) – Output_Data object for commutative fanouts
data_output_multiplicative (Output_Data) – Output_Data object for multiplicatively merged fanouts
data_output_ordered (Ordered_Output_Data) – Chronologically ordered merged data in a linear format

make a Interface_Data object and plot it’s refelction diagrm

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_refelction_diagram
import matplotlib.pyplot as plt

# simulate an interface by providing key-values altered from the defaults
interface_data = generate_interface_data(L_time = '3.6',C_time = '3.2',L_impedance = '300')

# The interface object created stores all level of data from the simulation
data_input = interface_data.data_input
data_output_commutative = interface_data.data_output_commutative
data_output_multiplicative = interface_data.data_output_multiplicative
data_output_ordered = interface_data.data_output_ordered

# plot the current reflection diagram  of the interface
fig, ax = plt.subplots()
plot_refelction_diagram(interface_data,ax,False,stop_time='40')

plt.show()

data_input: Input_Data

data_output_commutative: Output_Data

data_output_multiplicative: Output_Data

data_output_ordered: Ordered_Output_Data

Generation module

This module is responsible for processing various levels of wavefront simulaiton and storing them in their relevant Data_Storage arrays (see storage module).

Notable functions are:

generate_commutative_data() - generates the production of wavefronts from a Input_Data input variable array. Makes use of commutative merging (described in the associated paper) which make it possible for the efficient simualiton of wavefronts.

wavefronts.generation.generate_commutative_data(input_data: Input_Data)

The commutative generaion algorithm. Generates a storage.Output_Data object from the calculated input variables stored in a storage.Input_Data object.

Parameters:: input_data (Input_Data) – Input data object containing simulation input variables
Returns:: output data (a collection of commutative fanouts in form of np.ndarrays)
Return type:: Output_Data

Resposible for generating wavefronts and simultaneously commutatively merging the wavefronts. The simaltaneous commutative merging of wavefronts is mandatory for longer simulation times.

wavefronts.generation.multiplicative_merging_single_cycle(input_array: ndarray, Inductor_LCM_Factor: int, Capacitor_LCM_Factor: int)

Completes a single merging cycle of a mangitude fanout along the inductive axis. A single cycle consitis of splitting -> shift -> merging.

Parameters:

input_array (np.ndarray) – An output array from Datat_Output_Storage class., i.e. data_output.Voltage_Interconnect_Inductor
Inductor_LCM_Factor (int) – The co-factor of the time-delay for the inductor, KL. KL x TL = LCM(TL,TC)
Capacitor_LCM_Factor (int) – The co-factor of the time-delay for the capacitor axis, KC. KC x TC = LCM(TL,TC)

Returns:

returns the input_array after one more subsequent merging cycle.

Return type:

np.ndarray

wavefronts.generation.multiplicative_merging(input_array: ndarray, Inductor_LCM_Factor: int, Capacitor_LCM_Factor: int, layer_number_limit: int)

recursively apply the merging process on an input array until merged.

Parameters:

input_array (np.ndarray) – array to be merged
Inductor_LCM_Factor (int) – Inductor LCM cofactor KL
Capacitor_LCM_Factor (int) – Capacitor LCM cofactor KC
layer_number_limit (int) – up to what layer the array must be mrged to

Returns:

merged array

Return type:

np.ndarray

wavefronts.generation.transform_merged_array_to_capacitor_axis(data_input: Input_Data, merged_array)

Transform merged data output array to a C-axis merging representation

Parameters:

data_input (Input_Data) – input data for merged array
merged_array (np.ndarray[Decimal]) – merged array aligne to the C-axis

Returns:

merged array aligned to the C-axis

Return type:

np.ndarray[Decimal]

wavefronts.generation.generate_multiplicative_data(input_data: Input_Data, commutative_output_data: Output_Data)

Multiplicatively merges all commutatively merged data if applicable. Produces a Output_Data object with merged data.

Parameters:

input_data (Input_Data) – input data of interface
commutative_output_data (Output_Data) – the commutatively merged data to be multiplicatively merged

Returns:

a merged Output_Data storage object, merged version of the supplied commutative_output_data parameter

Return type:

Output_Data

wavefronts.generation.order_multiplicative_data(input_data: Input_Data, Data_Output_Merged: Output_Data)

Order the merged wavefront data into single dimension chronologically occuring ‘lists’. Uses a Breadth First Search type algorithm.

Parameters:

input_data (Input_Data) – the input data of the interface
Data_Output_Merged (Output_Data) – the merged data to be ordered

Raises:

warnings.warn – should be used on a merged data storage object, ekse results may be incorrect

Returns:

ordered merged data

Return type:

Ordered_Output_Data

wavefronts.generation.generate_interface_data(optional_data_input: Input_Data = False, **input_values)

Do full simualiton of the interface and produce a Interface_Data object with all the simualted data. The simulation procedure is as follows: calcualte input vatiables -> generate wavefront with commutative merging -> multiplicatively merge these wavefronts -> chronologically order wavefronts.

Is initialised using the same key-word arguments to intitalise Input_Data. OPTIONALLY a Input_Data array can be supplied directly to bypass internal creation of input data if it has been customized.

All values with the provided keys are of type string. This each input variable is converterted to a Decimal value to be used for precision calculations. The possible parameters to change and their defualt values are as follows, parameters are all optional

Parameters:

L_impedance (String) – Characteristic impedance of the inductor, assigned to self.Inductor_Impedance (default:’100’)
L_time (String) – The time delay of the inductor in seconds, assigned to self.Inductor_Time (default:’1’)
L_length (String) – The length of the inductor in meters, assigned to self.Inductor_Length (default:’1’)
C_impedance (String) – Characteristic impedance of the capacitor, assigned to self.Capacitor_Impedance (default:’1’)
C_time (String) – The time delay of the capacitor in seconds, assigned to self.Capacitor_Time (default:’1’)
C_length (String) – The length of the capacitor in meters, assigned to self.Capacitor_Length (default:’1’)
V_source (String) – The magnitude of the initial voltage excitation in volts, assigned to self.Voltage_Souce_Magnitude (default:’1’)
number_periods (String) – The number of periods as according to Lumped-Element LC-Osscilator solution. Used to calculate the simulation stop time if provided. Overidden if ‘Simulation_stop_time’ is provided (default:’1’)
Load_impedance (String) – The magnitude of the load resistance, if left inf the load is ignored and the interface takes form of an LC-Osscilator. If a value is provided the load is considered and the self.Is_Buck flag is set to True (default:’inf’)
Simulation_stop_time (String) – The time to which the interface will be simulated. If provided it will overwrite the ‘number_periods’ simulation stop time calculation (default:’0’)
show_about (Boolean) – Indicates information about the calcualted variabels must be printed (default:True)

Returns:

Interface Data object

Return type:

Interface_Data

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_refelction_diagram
import matplotlib.pyplot as plt

# simulate an interface by providing key-values altered from the defaults
interface_data = generate_interface_data(L_time = '3.6',C_time = '3.2',L_impedance = '300')

# The interface object created stores all level of data from the simulation
data_input = interface_data.data_input
data_output_commutative = interface_data.data_output_commutative
data_output_multiplicative = interface_data.data_output_multiplicative
data_output_ordered = interface_data.data_output_ordered

# plot the current reflection diagram  of the interface
fig, ax = plt.subplots()
plot_refelction_diagram(interface_data,ax,False,stop_time='40')

plt.show()

wavefronts.generation.get_spatial_voltage_current_at_time(Time_Enquriey: Decimal, Interface: Interface_Data, is_Inductor: bool)

Calcualte the postions of wavefronts on a transmission line and get the spatial distribution of voltage and current on either sides og the points.

Parameters:

Time_Enquriey (Decimal) – The time at which spatial behaviour is investigated
Interface (Interface_Data) – The data stroage object of the interface
is_Inductor (bool) – if the transmission line investigate is the inductor or capacitor.

Returns:

[intercept_postiions, left_voltage, right_voltage, left_current, right_current] left means closer to the interface.

Return type:

tuple[list, list, list, list, list]

Plotting module

The module responsible for visualisation of distributed behaviours. In general a function will either be a ‘make’ or a ‘plot’ type. ‘plot’ functions require the creation of plotting axes to be provided to the function to be ‘plotted on’. These type of functions typically are plotted on a single axis, were the format of the axis is irrelavant and flexible. ‘make’ functions on the other hand generate axes internally and can have axes passed to them, however they must be of a particualr format. Make functions oftens setup axes in a particular way and is why they handle the generation of the the axes. Internal creation of axes can potentially be problematic when doing multiple loops on a make function, in this case be sure to pass an in axes of the correct format as described per function.

wavefronts.plotting.clear_subplot(axs)

a little loop that clears all axes of an axes object

Parameters:: axs (matplotlib Axes) – axes object array to be cleared

wavefronts.plotting.handle_interface_to_ordered(data) → Ordered_Output_Data

ensures data is ordered, extracts it if it can, else raises an error.

Parameters:: data (any) – input data to be checked
Raises:: TypeError – if ordered data cannot be extracted
Returns:: ordered data
Return type:: Ordered_Output_Data

wavefronts.plotting.plot_fanout_magnitude(array_to_plot: ndarray, ax, **input_kwargs)

the core function for plotting the fanout diagram of a 2D numpy array. Points are coloured using the ‘seismic’ colour map with red being positive and blue negative. See plot_fanout_interconnect() and plot_fanout_wavefronts() for prettier plots with more automation

Parameters:

array_to_plot (np.ndarray or List) – The array to be plotted, can also accept lists of numerical data
ax (matplotlib.Axe) – a matplotlib Axe object to plot using ‘imshow’

Input_kwargs:

title (str) - The title of the fanout (default = “Magnitude Fanout”)
show_colour_bar (bool) - if colour bar must be shown (default = True)
contrast (bool) - if the orign node must be ignored for the colour mapping maximum value calculation (default = False)
padding (int) - the amount of padding around the array, thinner arrays are easier to navigate with padding (default = 0)
units (str) - the units of the colour bar (default = ‘A’)
origin (str) - either ‘lower’ or ‘upper’, sets the postion of the origin (default = ‘lower’)
transpose (bool) - makes x-axis the L-axis if true (default = True)
show_ticks (bool) - if axis ticks are shown (default = False)
custom_colour_bar_limits (tuple or bool) - pass a (max_value, min_value) tuple to customize colouring extent of the fanout(default = False)

Warning

a wavefront storage array must be in their magnitude forms, these arrays can be fetched using storage.Output_Data.get_sending_wavefronts_magnitudes() or storage.Output_Data.get_returning_wavefronts_magnitudes(). Alternatively magnitdues from a wavefront array can be manually extracted by passing as an input parameter to misc.get_voltage_array() or misc.get_current_array()

simple use

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_fanout_magnitude
import matplotlib.pyplot as plt

# simulate interface
interface_data = generate_interface_data(L_time='0.7' , C_time='3.2')

# plot the commutatiive capacitor interconnect voltage 
fig, ax = plt.subplots()
arr = interface_data.data_output_commutative.Voltage_Interconnect_Capacitor
# set units to 'V'
plot_fanout_magnitude(arr,ax, units = 'V')
plt.show()

manual wavefront fanout, see plot_fanout_wavefronts()

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_fanout_magnitude
import matplotlib.pyplot as plt

# simulate interface
interface_data = generate_interface_data(L_time='23' , C_time='11')

# plot the multiplicative sending current capacitor wavefronts
fig, ax = plt.subplots()
arr = interface_data.data_output_multiplicative.get_sending_wavefronts_magnitudes('current capacitor')
# set units to 'V'
plot_fanout_magnitude(arr,ax, units = 'A')
plt.show()

Returns:: plots a magnitude fanout on the provided axis

wavefronts.plotting.plot_fanout_time(input_array: ndarray, ax, **input_kwargs)

Plot a time fanout of a provided input array. Coloured in a rainbow pattern from the minimum array value to the maximum array value.

Parameters:

input_array (np.ndarray or List) – The array to be plotted, can also accept lists of numerical data
ax (matplotlib.Axe) – a matplotlib Axe object to plot using ‘imshow’

Input_kwargs:

same input kwargs as plot_fanout_magnitude()
mask_zero (bool) - if zeros values must be masked (default = True)

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_fanout_time
import matplotlib.pyplot as plt

# simulate interface
interface_data = generate_interface_data(L_time='2' , C_time='7')

# plot the time fanout
fig, ax = plt.subplots()
plot_fanout_time(interface_data.data_output_commutative.Time, ax)

plt.show()

wavefronts.plotting.plot_fanout_interconnect(data_output: Output_Data, ax, which_string: str, contrast_voltage=True, **kwargs)

A wrapper function for plot_fanout_magnitude() for plotting interconnect fanouts. Takes in a Output_Data object and a string to plot and auto format the fanout. It will pass provided **kwargs to the underlying plot_fanout_magnitude function. To plot all interface interconnect fanouts at once see make_fanout_interconnect_all()

Parameters:

data_output (Output_Data) – The data output object that contians the interconnect arrays. Could be commutative or multiplicative data.
ax (matplotlib Axes object) – the matplotlib axis to plot on
which_string (str) – determine which interconnect value to plot. Options are “voltage inductor”, “current inductor”, “voltage capacitor”, “current capacitor”
contrast_voltage (bool) – determine if voltage arrays must exclude the orign point for better contrast, default is True

Raises:

ValueError – if incorrect ‘which_string’ is not provided.
warning – if ‘title=’, ‘units=’ or ‘contrast=’ keyword are included as they are auto assigned by this function

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_fanout_interconnect
import matplotlib.pyplot as plt

# simulate interface
interface_data = generate_interface_data(L_time='12' , C_time='13')

# compare commutative and multiplicative capacitor interconnect voltage
# (on the same subplot)
fig, ax = plt.subplots(1,2, figsize= (10,6))

# pass commutative data output
plot_fanout_interconnect(interface_data.data_output_commutative,
                        ax[0], 'voltage capacitor')

# pass multiplicative data output 
plot_fanout_interconnect(interface_data.data_output_multiplicative,
                        ax[1], 'voltage capacitor')

plt.show()

Warning

When providing the **kwargs, you cannot specify ‘title=’, ‘units=’ or ‘’contrast=’ as these are auto assinged. Providing these values will result in an error.

wavefronts.plotting.plot_fanout_wavefronts(data_output: Output_Data, ax, which_string: str, is_sending: bool = True, **kwargs)

A wrapper function for plot_fanout_magnitude() for plotting wavefront fanouts. Takes in a Output_Data object, a string and a bool are passed to plot and auto format the fanout. It will pass provided **kwargs to the underlying plot_fanout_magnitude function. To plot all wavefront fanouts at once see make_fanout_wavefronts_all()

Parameters:

data_output (Output_Data) – The data output object that contians the interconnect arrays. Could be commutative or multiplicative data.
ax (matplotlib Axes object) – the matplotlib axis to plot on
which_string (str) – determine which interconnect value to plot. Options are “voltage inductor”, “current inductor”, “voltage capacitor”, “current capacitor”
is_sending (bool, optional) – determines if sending or returning wavefronts must be plotted, defaults to True

Raises:

ValueError – if incorrect ‘which_string’ is not provided.

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_fanout_wavefronts
import matplotlib.pyplot as plt

# simulate interface
interface_data = generate_interface_data(L_time='12' , C_time='13')

# compare sending and returning capacitor current wavefronts
# (on the same subplot)
fig, ax = plt.subplots(1,2, figsize= (10,6))

# sending current wavefronts
plot_fanout_wavefronts(interface_data.data_output_commutative,
                        ax[0], 'current capacitor',True)

# returning current wavefront 
plot_fanout_wavefronts(interface_data.data_output_commutative,
                        ax[1], 'current capacitor',False)

plt.show()

Warning

When providing the **kwargs, you cannot specify ‘title=’ or ‘units=’ as these are auto assinged. Providing these values will result in an error.

wavefronts.plotting.make_fanout_crossection(input_array: ndarray, L_intercept: int, C_intercept: int, **kwargs)

Plots a magnitude fanout and corssection at a L and C intercept for a given input data array. The kwargs supplied are passed down to plot_fanout_magnitude(). Additonal key-value customiztion is included for the crossection plot below.

Parameters:

input_array (np.ndarray) – The fanout data to be investigated
L_intercept (int) – The value on the L-axis to intercept
C_intercept (int) – The value on the C-axis to intercept

Returns:

the matplotlib Figure and Axes objects created in this function

Return type:

tuple( fig , ax )

Kwargs for crossection:

ax (Dict(Axes)) - Whether to create a subpot or use exsiting subplot axes.If left blank default is ‘False’ and subplot is created internally.If axes are provided, the must be of a matplotlib.pyplot.subplot_mosaic() form.The labels for these axes must inculde:
- ‘C’ for C-plot/ L interception
- ‘L’ for L-plot/ C interception
- ‘D’ for the Diagonal plot
- ‘F’ for Fanout magnitude plot
fig_size (tuple of ints) - The size of the figure. Default is (10, 8).
Transpose_C_Plot (bool) - Whether to transpose the C plot. Default is True.
Transpose_L_Plot (bool) - Whether to transpose the L plot. Default is False

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import make_fanout_crossection
import matplotlib.pyplot as plt

# simulate interface
interface = generate_interface_data(L_time='6.5' , C_time='3' , L_impedance='700')

# make axes internally, intercept at L=25, C= 10
data = interface.data_output_commutative.Voltage_Interconnect_Capacitor
make_fanout_crossection(data, 25, 10, units='V')

# make axes externally, intercept at L=25, C= 10

fig, ax = plt.subplot_mosaic([['C','F'],
                              ['D','L']])

make_fanout_crossection(data, 25, 10, units='V', ax=ax)

plt.show()

Warning

if ax keyword is not provided, function will make new subplot objects each time it is called. These plots will not be closed by default, so if multiple calls are needed it is suggested you provide the appropriate subplot_mosaic Axes object.

wavefronts.plotting.make_fanout_interconnect_all(data_output: Output_Data, contrast_voltage=True, **kwargs)

plots all the interconnect magnitude fanouts for a particular Output_Data object. A wrapper fucniton for plot_fanout_interconnect(). This is a ‘make’ type function which means that by default the function will internally create the plotting axes unless specified otherwise. The kwargs supplied are passed down to plot_fanout_interconnect(). Additonal key-value customiztion is included for the crossection plot below.

Parameters:

data_output (Output_Data) – The data object to be plotted
contrast_voltage (bool, optional) – if the voltage arrays must ignore the intial excitation point for better contrast, defaults to True

Returns:

the matplotlib Figure and Axes objects created in this function (if created)

Return type:

tuple( fig , ax )

Kwargs for figure creation:

ax (Dict(Axes)) - Whether to create a subpot or use exsiting subplot axes.If left blank default is ‘False’ and subplot is created internally.If axes are provided, the must be of a matplotlib.pyplot.subplot_mosaic() form.The labels for these axes must inculde:
- ‘VL’ axis for inductor voltage
- ‘VC’ axis for capcitor voltage
- ‘IL’ axis for inductor current
- ‘IC’ axis for capacitor current
fig_size (tuple of ints) - The size of the figure. Default is (10, 8).

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import make_fanout_interconnect_all
import matplotlib.pyplot as plt

# simulate interface
interface = generate_interface_data(L_time='12' , C_time='8')

# make figure internally, plot commutative data
fig1,ax1 = make_fanout_interconnect_all(interface.data_output_commutative)
fig1.suptitle(f"commutative Fanouts") # customize title

# make figure externally, put currents left and voltages right
fig2, ax2 = plt.subplot_mosaic([['IL','VL'],
                                ['IC','VC']])

# pass ax2 to fucniton, also, show multiplicative data this time
make_fanout_interconnect_all(interface.data_output_multiplicative, ax=ax2)
fig2.suptitle(f"multiplicative Fanouts") # customize title

plt.show()

Warning

if ax keyword is not provided, function will make new subplot objects each time it is called. These plots will not be closed by default, so if multiple calls are needed it is suggested you provide the appropriate subplot_mosaic Axes object.

wavefronts.plotting.make_fanout_wavefronts_all(data_output: Output_Data, is_Inductor: bool, **kwargs)

plots all the sending and returning magnitude fanouts for a transmission line of a Output_Data object. A wrapper fucniton for plot_fanout_wavefronts(). This is a ‘make’ type function which means that by default the function will internally create the plotting axes unless specified otherwise. The kwargs supplied are passed down to plot_fanout_wavefronts(). Additonal key-value customiztion is included for the crossection plot below.

Parameters:

data_output (Output_Data) – The data object to be plotted
is_Inductor (bool) – if the wavefronts shown are form the inductor or the capacitor.

Returns:

the matplotlib Figure and Axes objects created in this function (if created)

Return type:

tuple( fig , ax )

Kwargs for figure creation:

ax (Dict(Axes)) - Whether to create a subpot or use exsiting subplot axes.If left blank default is ‘False’ and subplot is created internally.If axes are provided, the must be of a matplotlib.pyplot.subplot_mosaic() form.The labels for these axes must inculde:
- ‘VS’ axis for sending voltage
- ‘VR’ axis for returning voltage
- ‘IS’ axis for sending current
- ‘IR’ axis for returning current
fig_size (tuple of ints) - The size of the figure. Default is (10, 8).

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import make_fanout_wavefronts_all
import matplotlib.pyplot as plt

# simulate interface
interface = generate_interface_data(L_time='0.34' , C_time='0.12', L_impedance = '700', C_impedance = '7')

# make figure internally, 
# plot commutative inductive wavefronts
fig_ind,ax_ind = make_fanout_wavefronts_all(interface.data_output_commutative,True)

# plot commutative capacitive wavefronts
fig_cap,ax_cap = make_fanout_wavefronts_all(interface.data_output_commutative,False)

# make figure externally,
# put sending wavefronts left and returning wavefronts right
# show merged data

fig2_ind, ax2_ind = plt.subplot_mosaic([['IS','IR'],
                                        ['VS','VR']])
make_fanout_wavefronts_all(interface.data_output_multiplicative,True, ax=ax2_ind)

# put voltages in opposite corners (for fun)
fig2_cap, ax2_cap = plt.subplot_mosaic([['IS','VR'],
                                        ['VS','IR']])
make_fanout_wavefronts_all(interface.data_output_multiplicative,False, ax=ax2_cap)

plt.show()

Warning

if ax keyword is not provided, function will make new subplot objects each time it is called. These plots will not be closed by default, so if multiple calls are needed it is suggested you provide the appropriate subplot_mosaic Axes object.

wavefronts.plotting.plot_trace_on_merged_fanout_axis(data_output_ordered: Ordered_Output_Data, ax, upto_time: Decimal = False, **kwargs)

Plots a path of arrows on a merged fanout diagram.

Parameters:

data_output_ordered (Ordered_Output_Data or Interface_Data) – the ordered data array, can also be an interface object
ax (Matplotlib Axes) – the axis with a fanout diagram plotted on it
upto_time (Decimal, optional) – the time to which the path must be plotted, defaults to False

Kwargs:

show_cross (bool) - If a cross must be plotted to show current arrow at ‘upto_time’. Default is False
padding (int) - The padding around the arrow. Default is 0.
length_includes_head (bool) - Whether the head is included in the arrow length. Default is True.
head_width (float) - The width of the arrow head. Default is 0.3.
head_length (float) - The length of the arrow head. Default is 0.3.
width (float) - The width of the arrow shaft. Default is 0.0005.
facecolor (str) - The face color of the arrow. Default is ‘gray’.
edgecolor (str) - The edge color of the arrow. Default is ‘black’.

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_trace_on_merged_fanout_axis, plot_fanout_interconnect
import matplotlib.pyplot as plt

# simulate an interface
interface_data = generate_interface_data(L_time = '3.6',C_time = '3.2')

fig, ax = plt.subplots()
plot_fanout_interconnect(interface_data.data_output_multiplicative,ax,'voltage capacitor')
plot_trace_on_merged_fanout_axis(interface_data,ax)
plt.show()

Warning

the trace plotted is compatible with merged fanouts. (fanout plots of storage.Inupt_Data.data_output_multiplicative)

wavefronts.plotting.plot_merging_lines_on_fanout(array_to_plot: ndarray, KL: int, KC: int, ax, **kwargs)

Plots the borders of merging regions for a given array_to_plot onto an axis that is plotting a fanout.

Parameters:

array_to_plot (np.ndarray) – The data array contianing fanout magnitude information
KL (int) – Inductor LCM factor
KC (int) – Capacitor LCM factor
ax (matplotlib Axes object) – Axis with a fanout plot on it

Kwargs:

transpose (bool) - Whether the plot is transposed (L-axis is horizontal axis). Default is True
padding (int) - The padding of the plot. Default is 0
line_colour (str) - The color of the lines. Default is ‘k’
line_width (float) - The width of the lines. Default is 0.5

wavefronts.plotting.make_commutative_merged_lines(interface_data: Interface_Data, which_operation: str, which_string: str)

Make 3 - magnitude fanouts with their merging regions shown. Fanout 1 is the commutative fanout before merging. Fanout 2 is the merged fanout along the L-axis. Fanout 3 is the merged fanout along the C-axis.

Parameters:

interface_data (Interface_Data) – the interface data to be plotted
which_operation (str) – the operation for fetching fanout data, options are ‘interconnect’,’sending’ or ‘returning’.
which_string (str) – which specific magnitude to extract in form ‘{voltage or current} {inductor or capacitor}’

Raises:

ValueError – if incorrect ‘which_operation’ or ‘which_string’ information is provided.

wavefronts.plotting.plot_time_interconnect(data_output_ordered: Ordered_Output_Data, ax, which_string: str, is_integrated: bool = True, **kwarg)

Plots the time waveform of one of the interconncet metrics. It must be noted that interconnect values stored in the Ordered_Output_Data object signify the ‘change’ in interface values due to wavefronts. To see the full time wavefrom, the changes must be accumulated. This function shows both change and accumulated quantities.

Parameters:

data_output_ordered (Ordered_Output_Data or (Interface_Data)) – The data object containing 1D ordered simulation data
ax (Matplotlib Axes object) – The axis on which the interconncet wavefrom will be plotted.
which_string (str) – The interconnect value to be plotted, options are “voltage inductor”, “current inductor”, “voltage capacitor” and “current capacitor”
is_integrated (bool) – If the wavefrom must represent the ‘change’ or ‘accumulation of changes’ of the data selected to be plotted, default is True

Raises:

ValueError – if an incorrect which_string is provided.

Returns:

(optional) if key word ‘return_data = True’ is passed, will return the plotted array, default is False

Return type:

np.ndarray[Decimal]

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_time_interconnect
import matplotlib.pyplot as plt

# simulate interface
interface = generate_interface_data(L_time='0.34' , C_time='0.12', L_impedance = '700', C_impedance = '7')

# Make axes 
fig,ax = plt.subplots(2,1,figsize=(8,8))

# make a handle for ordered data (very optional)
data = interface.data_output_ordered

# plot accumulated data on ax[0]
plot_time_interconnect(data,ax[0],'current capacitor',True)

# plot change data on ax[1], use 'interface' instead of 'data' (for fun)
plot_time_interconnect(interface,ax[1],'current capacitor',False)

plt.show()

Warning

This function accepts only storage.Ordered_Output_Data as an input. The data is required to be 1D and ordered.

wavefronts.plotting.plot_time_wavefronts(data_output_ordered: Ordered_Output_Data, ax, which_string: str, is_sending: bool, is_integrated: bool = True)

Plots the time waveform of one of the wavefront metrics. It must be noted that interconnect values stored in the Ordered_Output_Data object signify the ‘change’ in interface values due to wavefronts. To see the full time wavefrom, the changes must be accumulated. This function shows both change and accumulated quantities.

Parameters:

data_output_ordered (Ordered_Output_Data or Interface_Data) – The data object containing 1D ordered simulation data, also accepts full interface data
ax (Matplotlib Axes object) – The axis on which the interconncet wavefrom will be plotted.
which_string (str) – The wavefront value to be plotted, options are “voltage inductor”, “current inductor”, “voltage capacitor” and “current capacitor”
is_sending (bool) – If the the wavefront data shown must be for sending or returning wavefronts.
is_integrated (bool) – If the wavefrom must represent the ‘change’ or ‘accumulation of changes’ of the data selected to be plotted, default is True

Raises:

ValueError – if an incorrect which_string is provided.

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_time_wavefronts
import matplotlib.pyplot as plt

# Example, comparing the sending and returning current wavefronts in the capacitor:
# =================================================================================

# simulate interface
interface = generate_interface_data(L_time='3' , C_time='7', L_impedance = '700', C_impedance = '7')
data = interface.data_output_ordered

# Make axes 
fig,ax = plt.subplots()

# plot sending wavefronts (not accumulated)
plot_time_wavefronts(data,ax,'current capacitor',True,False)

# plot returning wavefronts (not accumulated)
plot_time_wavefronts(data,ax,'current capacitor',False,False)

plt.show()

Warning

This function accepts only storage.Ordered_Output_Data as an input. The data is required to be 1D and ordered.

wavefronts.plotting.make_time_interconnect_all(data_output_ordered: Ordered_Output_Data, is_integrated: bool = True, **kwargs)

Plots all interconnect time waveforms of an storage.Interface_Data/ Orderd_Output_data.

Parameters:

data_output_ordered (Ordered_Output_Data) – data to be plotted. Can be interface or ordered data.
is_integrated (bool, optional) – If the wavefrom must represent the ‘change’ or ‘accumulation of changes’ of the data selected to be plotted, default is True

Returns:

the matplotlib Figure and Axes objects created in this function (if created)

Return type:

tuple( fig , ax )

Kwargs for figure creation:

ax (Dict(Axes)) - Whether to create a subpot or use exsiting subplot axes.If left blank default is ‘False’ and subplot is created internally.If axes are provided, the must be of a matplotlib.pyplot.subplot_mosaic() form.The labels for these axes must inculde:
- ‘VL’ axis for inductor voltage
- ‘VC’ axis for capcitor voltage
- ‘IL’ axis for inductor current
- ‘IC’ axis for capacitor current
fig_size (tuple of ints) - The size of the figure. Default is (10, 8).

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import make_time_interconnect_all
import matplotlib.pyplot as plt

# simulate interface
interface = generate_interface_data(L_time='8' , C_time='7', L_impedance = '500', C_impedance = '2')

# plot all interconnect time waveforms
fig,ax = make_time_interconnect_all(interface)

# plot the 'change' in those waveforms
fig2,ax2 = make_time_interconnect_all(interface,False)

plt.show()

wavefronts.plotting.make_time_wavefronts_all(data_output_ordered: Ordered_Output_Data, is_Inductor: bool, is_integrated: bool = True, **kwargs)

Plots the wavefront time beahviour of a particualr transmission line. Both sending and returning, current and voltage wavefront time behaviour is shown

Parameters:

data_output_ordered (Ordered_Output_Data or Interface_Data) – data to be plotted. Can be interface or ordered data.
is_Inductor (bool) – if the inductor or capacitor wavefronts must be plot.
is_integrated (bool, optional) – if the individual wavefront value or an accumulation of these values msut be shown, defaults to True

Returns:

the matplotlib Figure and Axes objects created in this function (if created)

Return type:

tuple( fig , ax )

Kwargs for figure creation:

ax (Dict(Axes)) - Whether to create a subpot or use exsiting subplot axes.If left blank default is ‘False’ and subplot is created internally.If axes are provided, the must be of a matplotlib.pyplot.subplot_mosaic() form.The labels for these axes must inculde:
- ‘VS’ axis for sending voltage
- ‘VR’ axis for returning voltage
- ‘IS’ axis for sending current
- ‘IR’ axis for returning current
fig_size (tuple of ints) - The size of the figure. Default is (10, 8).

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import make_time_wavefronts_all
import matplotlib.pyplot as plt

# Example: the accumulated wavefront behaviour over time between the capacitor and inductor
# ==========================================================================================

# simulate interface
interface = generate_interface_data(L_time='7' , C_time='3.4', L_impedance = '654', C_impedance = '2.5')

# plot accumulation wavefront activity for inductor
fig,ax = make_time_wavefronts_all(interface,True,True)

# plot the accumulation wavefront activity for capacitor
# here we just pass the ax object as a kwarg so that it is plotted on the same axes
make_time_wavefronts_all(interface,False,True,ax=ax)

# rename the auto generated suptitle
fig.suptitle('Comparison between accumulated wavefronts over time in each transmission line')

# use the key word to set titles of each axis independantly 
ax['VS'].set_title('Sending Voltage Wavefronts')
ax['VR'].set_title('Returning Voltage Wavefronts')
ax['IS'].set_title('Sending Current Wavefronts')
ax['IR'].set_title('Returning Current Wavefronts')

# plot a legend for all axes
for ax_i in ax.values(): 
    ax_i.legend(['Inductor', 'Capacitor'])

plt.show()

wavefronts.plotting.plot_refelction_diagram(interface_data: Interface_Data, ax, is_voltage: bool, **kwargs)

plots a coloured current or voltage reflection for the inductor and capacitor of a simulated interface.

Parameters:

interface_data (Interface_Data) – The interface to be plotted.
ax (Matplotlib Axes) – axis to plot on
is_voltage (bool) – if the plot

Raises:

TypeError – if supplied custom_colour_bar are not a tuple

Kwargs for figure creation:

stop_time (float) - The simulation stop time. Default is the value of interface_data.data_input.Simulation_Stop_Time.
custom_colour_bar_limits (tuple) - supply a tuple in form of (Vmax,Vmin) for colourbar limits. Default is False, meaning it is calcuated of absolute maximum of wavefronts.
face_colour (str) - The face color of the plot. Default is ‘xkcd:grey’.
LS_colour (bool or str) - if supplied overides colour map colouring, The color of the sending inductor wavefronts, matplotlib colour. Default is False.
LR_colour (bool or str) - if supplied overides colour map colouring, The color of the returning inductor wavefronts, matplotlib colour. Default is False.
CS_colour (bool or str) - if supplied overides colour map colouring, The color of the sending capacitor wavefronts, matplotlib colour. Default is False.
CR_colour (bool or str) - if supplied overides colour map colouring, The color of the returning capacitor wavefronts, matplotlib colour. Default is False.
LS_style (str) - The style of the sending inductor wavefronts, matplotlib linestyle. Default is ‘-‘.
LR_style (str) - The style of the returning inductor wavefronts, matplotlib linestyle. Default is ‘-‘.
CS_style (str) - The style of the sending capacitor wavefronts, matplotlib linestyle. Default is ‘-‘.
CR_style (str) - The style of the returning capacitor wavefronts, matplotlib linestyle. Default is ‘-‘.
info_title (bool) - Whether to include a title with input information about the plot. Default is True.

Compare Voltage and Current wavefronts of the interface

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_refelction_diagram
import matplotlib.pyplot as plt

# simulate interface
interface = generate_interface_data(L_time = '12',C_time = '11',Simulation_stop_time=100)

# create subplot
fig,ax = plt.subplots(1,2,figsize=(18,8))

# compare voltage and current 
plot_refelction_diagram(interface,ax[0],True)
plot_refelction_diagram(interface,ax[1],False)

plt.show()

Customizing plots to highlight sending wavefronts

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_refelction_diagram
import matplotlib.pyplot as plt

# simulate interface
interface = generate_interface_data(L_time = '12',C_time = '11',Simulation_stop_time=100)

# create subplot
fig,ax = plt.subplots(1,2,figsize=(18,8))

# highlight sending wavefronts and make returning gray
c = 'dimgray'
plot_refelction_diagram(interface,ax[0],True, CR_colour=c, CR_style = '--', LR_colour=c, LR_style = '--')
plot_refelction_diagram(interface,ax[1],False, CR_colour=c, CR_style = '--', LR_colour=c, LR_style = '--')

plt.show()

wavefronts.plotting.make_spatial_voltage_and_current(Time_Enquriey: Decimal, Interface: Interface_Data, **kwargs)

Plots the spatial distribution of voltage and current in both the inductor and capacitor.

Parameters:

Time_Enquriey (Decimal) – the time at which spatial distrinution of energy is shown.
Interface (Interface_Data) – the data storage object for the interface simulation

Returns:

interconnect values of voltage for capacitor and inductor and current for capacitor and inductor in that order if ‘return-data’ keyword set to True, default is False

Return type:

tuple ( Decimal[VC], Decimal[VL], Decimal[IC], Decimal[IL] )

Kwargs for figure creation:

ax (Dict(Axes)) - Whether to create a subpot or use exsiting subplot axes.If left blank default is ‘False’ and subplot is created internally.If axes are provided, the must be of a matplotlib.pyplot.subplot_mosaic() form or a 1D np.ndarray of two items. The first will be assigned voltage and the other current.The labels for these axes must inculde:
- ‘V’ axis for voltage spatial plot
- ‘I’ axis for current spatial plot
fig_size (tuple of ints) - The size of the figure. Default is (12,10).
quantize (str or Decimal) - the precision to round the input time shown in the title
return_data (bool) - if the interconnect values must be returned or not, default is False

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import make_spatial_voltage_and_current
import matplotlib.pyplot as plt
from decimal import Decimal

# simulate an interface
interface_data = generate_interface_data(L_time = '2.07',C_time = '3.2')

# investgate the spatial waveforms a t = 30.573
make_spatial_voltage_and_current(Decimal('30.573'),interface_data)

# this time we will pass an axes dict, put current at the top:
# notice the correct formatting of ['V'] and ['I']
fig,ax = plt.subplot_mosaic([['I'],
                            ['V']])

# investgate the spatial waveforms a t = 30.7
make_spatial_voltage_and_current(Decimal('30.7'),interface_data,ax=ax)

plt.show()

Warning

if you do not pass an axes object the function will make a new suplot at each call. This means that if you plan to run the function such that it called multiple timea, like a loop, it is advised to pass axes object to avoid uneccassary creation of supblots each interation.

wavefronts.plotting.plot_timewaveforms_and_intercepts(Time_Enquriey: Decimal, data_output_ordered: Ordered_Output_Data, **kwargs)

plots all the interconnect voltages and/or currents of the tansmission lines on two sperate axes, one axis for voltage and one for current. Shows the magnitude of the interconnect values at a particualr time intercept as horizontal lines. Has an interactive form using ipywidgets, py:func:wavefronts.interactive.interact_spatial . See code-block below.

Parameters:

Time_Enquriey (Decimal) –
data_output_ordered (Ordered_Output_Data or Interface_Data) – ordered data, can also be interface data

Kwargs:

ax_voltage (axis or bool) - the axis to plot the voltage on, leave empty to not plot. Default is False.
ax_current (axis or bool) - the axis to plot the current on, leave empty to not plot. Default is False.

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_timewaveforms_and_intercepts
import matplotlib.pyplot as plt
from decimal import Decimal

# simulate interface
interface_data = generate_interface_data(L_time='0.7' , C_time='3.2')

time_enquirey = Decimal('25')

# plot both voltage and current

fig_both, ax_both = plt.subplots(2,1)
# define axes with kwargs 'ax_voltage=' and 'ax_current='
plot_timewaveforms_and_intercepts(time_enquirey,interface_data,
                                            ax_voltage = ax_both[0],
                                            ax_current = ax_both[1])

# lets plot just the voltage this time, also we will progress the time enquirey
# we will leave out 'ax_current='
fig_single,ax_single = plt.subplots()
time_enquirey += Decimal('5')
plot_timewaveforms_and_intercepts(time_enquirey,interface_data,ax_voltage = ax_single)

plt.show()

wavefronts.plotting.make_3d_spatial(Time_Enquriey: Decimal, interface: Input_Data, input_ax=False)

an experimanetal plot that shows spatial distribution of voltage and current at a time as a 3D bar graph. One dimension is space, one dimenstion is voltage and the final dimension is current. See make_spatial_voltage_and_current() for a less dense representation of the same data.

Parameters:

Time_Enquriey (Decimal) – time ate wwich the spatial information is investigated
interface (Input_Data) – interface simulation storage object
input_ax (matplotlib Axes (projection='3d')) – an optional axis to prevent plotting object to be made internally, default is False

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import make_3d_spatial
import matplotlib.pyplot as plt
from decimal import Decimal

# simulate interface
interface_data = generate_interface_data(L_time='12' , C_time='13')

make_3d_spatial(Decimal('53.56'),interface_data)

# or

fig = plt.figure()
ax = fig.add_subplot(111, projection='3d')

make_3d_spatial(Decimal('67.07'),interface_data,ax)

plt.show()

Warning

if input_ax is provided, it must have ‘projection=’3d’ else the plot will error.

wavefronts.plotting.save_spatial_interconnect(Interface: Interface_Data, **kwargs)

a function that saves an animation of the spatial distribution of voltage and current compared to time interconncect plots. Is the combination of make_spatial_voltage_and_current() and plot_timewaveforms_and_intercepts(). It is effectively interactive.interact_spatial(), however smoother as computation is not ‘real-time’

Parameters:

Interface (Interface_Data) – the interface data to be saved.

Kwargs:

auto_zoom (bool) - Whether to automatically zoom the plot or to have the axes aligned. Default is False.
start_time (str) - The start time enquirey for the plot. Default is ‘0’.
end_time (float) - The end time enquirey for the plot. Default is the value of Interface.data_input.Simulation_Stop_Time.
fps (str) - The frames per second for the video. Default is ‘30’.
video_runtime (str) - The runtime of the video in seconds. Default is ‘60’.
dpi (str) - The dots per inch for the video. Default is ‘300’.
fig_size (tuple of ints) - The size of the figure. Default is (14, 8).
meta_data (dict) - The metadata for the video. Default is {‘title’: ‘Distributed Modelling’, ‘artist’: ‘Jonathan Meerholz’}.
save_name (str) - The name to save the video as. Default is a string with the values of ‘spatial_and_time_{ZL}_{ZC}ohm_{TL}_{TC}s’

Warning

the default values of 60s runtime with 30 fps will result in a computation that will often take longer than 10 mins. be sure to alter these values if you dont want to wait!

from wavefronts.generation import generate_interface_data
from wavefronts.plotting import save_spatial_interconnect

# simulate an interface
interface_data = generate_interface_data(L_time = '3.6',C_time = '3.2')

save_spatial_interconnect(interface_data, video_runtime = '5',
                        start_time = '0', end_time = '30')

Interactive module

wavefronts.interactive.interact_spatial(Interface: Interface_Data, number_of_steps: int = 1000)

Creates an interactive spatial plot using ipywidgets. The slider bar ranges from 0 to number_of_steps (default is 1000).

Parameters:

Interface (Interface_Data) – interface data storage object
number_of_steps (int, optional) – the number of steps in the slider, defaults to 1000

wavefronts.interactive.interact_fanout_path(Interface: Interface_Data, is_Voltage: bool = True, padding: int = 0)

Creates an interactive plot that draws the ‘path of occurence’ ontop merged interconnect fanouts.

Parameters:

Interface (Interface_Data) – interface data storage object
is_Voltage (bool) – if to show voltage or current fanouts, defaults to True.
padding (int) – the padding around the fanouts, default = 0.

wavefronts.interactive.interact_3D_spatial(Interface: Interface_Data, **kwargs)

Creates an interactive 3D plot of voltage and current distributed in space with a slider bar to scrub time. (Not recomended for ver small time delays as the interactive )

Parameters:

Interface (Interface_Data) – interface data storage object
is_Voltage (bool) – if to show voltage or current fanouts, defaults to True.
padding (int) – the padding around the fanouts, default = 0.

Verification module

A Module responsible getting LTSpice simulation data as for verification. Ensure that ‘LTSpice_exe_Path’ in module points to your LTspice installation. Requires the the LC interface spice file template ‘LC_Spice_Input.txt’ which must be in the wavefronts folder.

wavefronts.verification.get_Spice_Arrays(**new_Spice_values)

Runs a LTSpice simulation on a Circuit theory LC interface as well as a distributed LC interface. Returns associated arrays. Useful for comparing distributed effects to lumped element effects, and the distributed soltuion made in using generation.generate_interface_data().

Parameters:: new_Spice_values – A set of key-value pairs used to configure the simulaiton. This dictonary is calculatedd on the creation of a storage.Input_Data,

storete under the parameter of SPICE_input_values. Default simulation values are as follows and will be overwritten with provided key-values.

new_Spice_values:

L_impedance (str) - The inductor impedance. Default is ‘100’.

L_time (str) - The inductor time constant. Default is ‘1’.

C_impedance (str) - The capacitor impedance. Default is ‘1’.

C_time (str) - The capacitor time constant. Default is ‘1’.

number_periods (str) - The number of periods to simulate. Default is ‘1’.

L_tot (str) - The total inductance. Default is ‘L_impedance*L_time/2 ‘.

C_tot (str) - The total capacitance. Default is ‘C_time/(2*C_impedance)’.

Simulation_stop_time (str) - The simulation stop time. Default is ‘2*number_periods*pi*sqrt(L_tot*C_tot)’.

Step_size (str) - The step size for the simulation. Default is ‘0.01’.

V_source (str) - The voltage of the source. Default is ‘1’.

Returns dictionary of output arrays [np.ndarrays]:

dict{

“Time”,

“Inductor_Voltage_Circuit”,

“Inductor_Current_Circuit”,

“Capacitor_Voltage_Circuit”,

“Capacitor_Current_Circuit”,

“Inductor_Voltage_Tx”,

“Inductor_Current_Tx”,

“Capacitor_Voltage_Tx”,

“Capacitor_Current_Tx”

}

manual SPICE simulaiton

from wavefronts.verification import get_Spice_Arrays
import matplotlib.pyplot as plt

# Do manual simulation

# Change Impedances and simulaiton timestep
LTSpice_Arrays = get_Spice_Arrays(L_impedance = '500',C_impedance = '20', Step_size='0.1')

# Plot Inductor votlage using Lumped circuit elements
plt.plot(LTSpice_Arrays['Time'],LTSpice_Arrays['Inductor_Voltage_Circuit'])
plt.title('Lumped Element analysis of Inductor Voltage')
plt.xlabel('time (s)')
plt.ylabel('Voltage (V)')
plt.show()

Using SPICE to verify output

from wavefronts.verification import get_Spice_Arrays
from wavefronts.generation import generate_interface_data
from wavefronts.plotting import plot_time_interconnect
import matplotlib.pyplot as plt

interface = generate_interface_data(L_impedance = '500',C_impedance = '20')

# get spice kwarg array
spice_kwargs = interface.data_input.SPICE_input_values

# set step-size to be GCD/8 to be safe
step_size = interface.data_input.GCD/8

# get arrays
LTSpice_outputs = get_Spice_Arrays(**spice_kwargs,Step_size=str(step_size))

fig,ax = plt.subplots()

# plot lumped current
ax.plot(LTSpice_outputs['Time'],LTSpice_outputs['Capacitor_Current_Tx'])

# plot distributed from LTSpice
ax.plot(LTSpice_outputs['Time'],LTSpice_outputs['Capacitor_Current_Circuit'])

# plot distributed from simulator
plot_time_interconnect(interface.data_output_ordered,ax,'Current Capacitor',True)

ax.legend(['LT-lumped','LT-dist','Wavefronts'])

plt.show()

Warning

does not account for the lengths of the capacitor and inductor. Also only wokrs for LC osscialtor configuration with no load.

Misc module

wavefronts.misc.default_input_values: dict = {'C_impedance': '1', 'C_length': '1', 'C_time': '1', 'L_impedance': '100', 'L_length': '1', 'L_time': '1', 'Load_impedance': 'inf', 'Simulation_stop_time': '0', 'V_source': '1', 'number_periods': '1', 'show_about': True}: The default values used in the simulation if not specified otherwise

wavefronts.misc.handle_default_kwargs(input_kwargs: dict, default_kwargs: dict, copy_default=True)

handles default values for key-word arguments. Alters or creates a copy of the defualt_kwargs to represent the new values provided by the input.

Parameters:

input_kwargs (dict) – kwargs given by user.
default_kwargs (dict) – default values that kwargs must be one of.
copy_default (bool) – determines if the the defaults array must be copied or not default is True

Raises:

Exception – ValueError if a kwarg is provided that is not one of the default values.

Returns:

returns a modfied version of the default_kwargs that includes input changes

Return type:

dict

wavefronts.misc.split_outer_inner_default_kwargs(input_kwargs: dict, outer_defaults: dict, inner_defaults: dict, handle_kwargs: bool = True, copy_default: bool = True)

Splits input_kwargs into two seperate dictionaries, One for outer function kwargs and one for an inner function kwargs.

Parameters:

input_kwargs (dict) – kwargs passed to outer function
outer_defaults (dict) – default kwargs for the outer function
inner_defaults (dict) – default kwargs for the inner function
handle_kwargs (bool, optional) – if handle_default_kwargs() must be called, decides if default values must be populated for return dicts, defaults to True.
copy_default (bool, optional) – if provided defaults must be coppeid or passed by reference, defaults to True

Raises:

ValueError – if keywords are not found in either of the defaults

Returns:

dictionaries for inner and outer functions (outer_function_dict, inner_function_dict)

Return type:

tuple( Dict , Dict )

wavefronts.misc.closest_event_to_time(data_ordered_time: list, time_enquirey: Decimal, can_be_after_enquirey: bool = True)

Finds the closest event and time to a praticular time enquirey.

Parameters:

data_ordered_time (list[Decimal]) – time list, must be chronologically ordered. Typically from storage:Ordered_Output_Data
time_enquirey (Decimal) – The time to wich the returned event will be closest
can_be_after_enquirey (bool, optional) – if the event is allowed to occur after the enquirey, defaults to True

Returns:

the index in time list and the closest time retuned as a tuple

Return type:

tuple ( index[int] , time[Decimal])

from wavefronts.generation import generate_interface_data
from wavefronts.misc import closest_event_to_time
from decimal import Decimal

# simulate random interface
interface = generate_interface_data(L_time='7' , C_time='3.4',show_about = False)

# handle for ordered time list
Time_arr = interface.data_output_ordered.Time
time_enquirey = Decimal('10.3')

# find closest event, can be after enquirey
i_after, t_after = closest_event_to_time(Time_arr,time_enquirey,True)
# find closest event, event must be before enquirey
i_before, t_before = closest_event_to_time(Time_arr,time_enquirey,False)

# the two closest times are 10.4 and 10.2 and time enquirey is 10.3
# 10.2 <--- 10.3 -> 10.4
print(f" time enquirey is {time_enquirey}")
print(f" best time if can be after {t_after} ") # returns 10.4
print(f" best time if must be before {t_before} ") # returns 10.2

# We can get the [ L , C ] coordiante by refernecing the 'Indexes' array

coord_after  = interface.data_output_ordered.Indexes[ i_after ]
coord_before = interface.data_output_ordered.Indexes[ i_before ]

print(f" [L , C] after  {coord_after} ") #  returns [1, 1]
print(f" [L , C] before {coord_before} ") # returns [0, 3]

Warning

time_enquirey must should be a Decimal number to be compatible with the storage array. The enquirey will be auto converted into a decimal but can produce errors.

wavefronts.misc.split_and_translate_to_L_axis(input_array: ndarray, C_value: int)

The first step in the recursive merging process. Seperates the input array into two arrays along the line C = C_value, this line is parallel to the L-axis. Both arrays are padded with ‘zeros’ such that the shape of the input array is maintained. The split array touching the origin and the L-axis will be padded such that it is ‘stationary’, The other array will be shifted to the origin along the L-axis with the padding is ‘ontop’.

Parameters:

input_array (np.ndarray) – array to be split.
C_value (int) – The value on the C-axis in which the array is split in two. Typically this is C = KC such as to divide along multiplicative merging region boundary.

Returns:

Stationary and Translated arrays in that order.

Return type:

tuple( np.ndarray , np.ndarray )

wavefronts.misc.translate_along_L_axis(input_array: ndarray, L_value: int)

The second step in the recursive merigng process. Shifts an array L_value units along the L-axis, and pads it with zeros so that the input shape is maintained.

Parameters:

input_array (np.ndarray) – array to be translated.
L_value (int) – the extent to which the array is shifted.

Returns:

the shifted array.

Return type:

np.ndarray

wavefronts.misc.lcm_gcd_euclid(TL: Decimal, TC: Decimal)

Gets the LCM, GCD and two co-factors KL and KC for time delays TL and TC.

This function makes use of the Euclidean algorithm, which is typically only defined for the integers. In this implementation the functionallity is extended to the rational numbers.

Parameters:

TL (Decimal) – any rational number, Typically the inductive time delay
TC (Decimal) – any rational number, Typically the capacitve time delay

Returns:

A dictionary that contains the LCM, GCD and two co-factors.

Return type:

Dict

wavefronts.misc.Steady_State_Analysis(TL: Decimal, TC: Decimal)

Prints out the steady-state analysis of an interface described by two time delays. Returns when each of the two criteria for steady-state to be reach will occur.

Parameters:

TL (Decimal) – inductive time delay
TC (Decimal) – capacitive time delay

Returns:

(time_before_regular_GCF, time_before_regular_Steady_State)

Return type:

Tuple

wavefronts.misc.get_array_absolute_maximum(array: ndarray)

Get the maximum absolute value of a data_output array. Used for normalising the colour bars of fanout plots.

Parameters:: array (np.ndarray[Decimal]) – array to get the absoulute maximum
Returns:: the absolute maximum of the array
Return type:: Decimal

wavefronts.misc.get_voltage_from_wavefront(wavefront)

get the voltage of a wavefront. Used as a dummy fucntion to be vectorized, see get_voltage_array().

Parameters:: wavefront (Wavefront) – a wavefront
Returns:: voltage magnitude of wavefront
Return type:: Decimal

wavefronts.misc.get_voltage_array = <numpy.vectorize object>: The vectorized function that extracts the voltages from an np.ndarray[Wavefronts] array and returns an np.ndarray[Decimal] voltage array.

wavefronts.misc.get_current_from_wavefront(wavefront)

get the voltage of a wavefront. Used as a dummy fucntion to be vectorized, see get_current_array().

Parameters:: wavefront (Wavefront) – a wavefront
Returns:: current magnitude of wavefront
Return type:: Decimal

wavefronts.misc.get_current_array = <numpy.vectorize object>: The vectorized function that extracts the currents from an np.ndarray[Wavefronts] array and returns an np.ndarray[Decimal] current array.

wavefronts.misc.convert_to_image_array(array)

Takes an input array, and if it is a 1-dimensional list, it will convert it into a suitable format for matplotlib “imshow” used by fanout plotters.

Parameters:: array (np.ndarray or List) – np.ndarray or List to be processed if neccessary
Returns:: an output array that can be shown using “imshow”
Return type:: np.ndarray