ssutil¶

buzz.ssutil

Functions

`addOutputs`(sys[, outputs, newnames, iod])	Given a system this function will return a system whose output is the sum of two or more outputs of the original system
`add_delay`(sys, delay)	Add a delay to a system
`asSISO`(sys)
`balance_sys_gain`(sys[, func, method, equil, ...])	To compute a reduced order model (Ar,Br,Cr,Dr) for an original state-space representation (A,B,C,D) by using either the square-root or the balancing-free square-root Singular Perturbation Approximation (SPA) model reduction method for the alpha-stable part of the system.
`bode`(sys[, ax, plotting_omega, label, ...])	Plot the bode plot of a MIMO system
`connect`(SS1, SS1_dict, SS2, SS2_dict, con_names)	Connect two state space systems and combine their name dictionaries
`controllabilityMatrix`(sys)	Get the controllability matrix of a system
`downsample_data`(freq, PSD, n_samples)
`duplicate_io`(sys, io[, iogain])	duplicate the output of a system.
`fit_ASD`(freq, ASD, n_samples[, ...])
`getSPO`(S, O, D)
`get_margin`(sys[, input, output])	Given a system, this function returns the gain margin of the system.
`get_num_ins_outs`(sys)	Get the number of inputs and outputs of a model.
`isControllable`(sys)	Check the controllability of a system
`isDescriptor`(sys[, error, print_error])	Check if the system is a descriptor system.
`isMIMO`(sys)	check if the system is of the buzz.ss.MIMOStateSpace type
`isObservable`(sys)	Check the observability of a system
`isSISO`(sys)	check if the system is siso
`isStable`(sys)	Check if a system is stable
`listpoles`(sys)	List the poles of a system.
`listzeros`(sys)	List the zeros of a system.
`loadSys`(fname)	load a system from a file
`load_zpk`([fname, asZPK])	Load the zeros, poles, and gain of a system from a file.
`makeFullModel`(E, P, M, F1, F2[, extras, EM, ...])	makeFullModel takes all the principle systems for the EMPFF model and combines them into a single system. This function is used to combine the plant, the environment noise, the measurement noise, and the two FOMs into a single system. This function is used to combine the plant, the environment noise, the measurement noise, and the two FOMs into a single system. The function will also adjust the plant to make it strictly proper if it is not already. The function will also check that the plant, the environment noise, the measurement noise, and the two FOMs are all stable.
`makeSPOFF`(S, P, O, F1, F2[, extras, SO, ...])	makeSPOFF takes all the principle systems for the SPOFF model and combines them into a single system.
`makeSys`(mod, iod[, wield, dt])	Make a system with iod and mod.
`make_stable`(sys)	Make a given state-space model stable by shifting the eigenvalues of the A matrix.
`mergeSys`(sysList, dictList[, inlist, outlist])	Merge a list of systems into one system.
`minreal`(sys, args, *kwargs)	Minreal function for Bunch systems
`multiconnect`(sysList, conlist[, dictList, ...])	Connect a list of systems together.
`negsys`(sys[, iod])	Make the negative of a system.
`normalize_gain`(sys[, norm, tol_percent, ...])	Normalize the maximum gain of a system to 1.
`observabilityMatrix`(sys)	Get the observability matrix of a system
`order`(sys)	Get the order of the system
`reduce`(sys, inputs, outputs[, iod, minreal, ...])
`removeIodIndices`(iod, inputs_to_remove, ...)	Take an iod and remove the inputs and outputs specified by the indices and or names provided in the inputs_to_remove and outputs_to_remove lists
`rename_io`(sys, oldname, newname)	Rename an input or output
`reorder_io`(sys, newinput, newoutput)
`save_zpk`(sys[, fname, safe])	Save the zeros, poles, and gain of a system to a file.
`savesys`(sys[, name, safe])	Save the system to a file.
`scale_io`(sys, ioname, gain)	Scale an input or output
`switch_io`(sys)	Switch the inputs and outputs of the system
`transpose`(sys)	Transpose the system
`truncate_io`(sys, inputs, outputs[, iod, ...])	Reduce a system to the specified inputs and outputs while removing unobservable states
`wieldSS`(*args[, iod])

Details

addOutputs(sys, outputs: list = None, newnames=None, iod=None)[source]¶

Given a system this function will return a system whose output is the sum of two or more outputs of the original system

Parameters:

sys (control.ss or Bunch) – State space model or bunch system with mod as attribute
outputs (list) – list of outputs to add together or list of lists of outputs to add together. Default to None #list of lists not implemented yet
newnames (list or str, optional) – list of names for the new outputs. Defaults to None.
iod (dict, optional) – input/output dictionary. Defaults to None.

Returns:

Bunch with mod and iod as attributes

Return type:

Bunch

add_delay(sys, delay)[source]¶

Add a delay to a system

Parameters:

sys (wield.siso) – SISO system to add a delay to
delay (float) – The delay to add to the system in seconds.

Returns:

SISO system with the delay added

Return type:

wield.siso

asSISO(sys)[source]¶

balance_sys_gain(sys, func='ab09nd', method='sqrt', equil=True, iod=None, verbose=False, **kwargs)[source]¶

To compute a reduced order model (Ar,Br,Cr,Dr) for an original state-space representation (A,B,C,D) by using either the square-root or the balancing-free square-root Singular Perturbation Approximation (SPA) model reduction method for the alpha-stable part of the system. - From SLICOT Documentation for ab09nd (https://www.slicot.org/objects/software/shared/doc/AB09ND.html)

Parameters:

sys (Bunch) – Bunch system with mod as attribute.
func (str, optional) – Function to use for reduction. ‘ab09nd’: use the ab09nd function. ‘ab09md’: use the ab09md function. ‘tb01id’: use the tb01id function. ‘ab09ad’: use the ab09ad function. Defaults to ‘ab09nd’.
method (str, optional) – Method to use for reduction. ‘sqrt’: use the square-root SPA method. ‘bfsqrt’: use the balancing-free square-root SPA method. Defaults to ‘sqrt’.
equil (bool, optional) – If True, preliminarily equilibrates the triplet (A,B,C). Defaults to True.
iod (dict, optional) – input/output dictionary. Defaults to None.

Returns:

Returns the local name space for the function including the state space model as mod, input output dictionary as iod, and namespace.

Return type:

wield.bunch

bode(sys, ax=None, plotting_omega=None, label=None, omega_limits=None, UG_line=False, axB=None, **kwargs)[source]¶

Plot the bode plot of a MIMO system

Parameters:

sys (wield.MIMO or wield.SISO) – MIMO system to plot
ax (_type_, optional) – The axes to plot on. Defaults to None.
plotting_omega (np.array, optional) – Plotting omega. Defaults to None.
label (string, optional) – Label for the plot trace. Defaults to None.
omega_limits (list, optional) – Limits for the omega. Defaults to None.
UG_line (bool, optional) – If true, a unity gain line will be plotted. Defaults to False.
axB (_type_, optional) – The axes to plot on. Depreciated replaced by ax. Defaults to None.

Returns:

the axis to plot on

Return type:

_type_

connect(SS1, SS1_dict, SS2, SS2_dict, con_names)[source]¶

Connect two state space systems and combine their name dictionaries

Parameters:

SS1 (control.statesp.StateSpace) – first state space system
SS1_dict (dict) – dictionary of names of the first state space system
SS2 (control.statesp.StateSpace) – second state space system
SS2_dict (dict) – dictionary of names of the second state space system
con_names (list) – list of connections between the two state space systems

Returns:

combined state space system with connections between the two systems dictionary: dictionary of names and indices of the combined state space system

Return type:

control.statesp.StateSpace

controllabilityMatrix(sys)[source]¶

Get the controllability matrix of a system

Parameters:: sys (wield.MIMO | wield.SISO) – MIMO or SISO system to get the controllability matrix of
Returns:: controllability matrix of the system
Return type:: np.array

downsample_data(freq, PSD, n_samples)[source]¶

duplicate_io(sys, io, iogain=None)[source]¶

duplicate the output of a system. This adds a C and D row to the system

Parameters:

sys (Bunch) – Bunch system with mod as attribute
output (str or list, optional) – string or list of strings outputs to duplicate
iogain (float or list, optional) – gain(s) to apply to the duplicated inputs or outputs. Order iogain the same as the io list is ordered. Defaults to None.

Returns:

Returns the local name space for the function including the state space model as mod, input output dictionary as iod, and namespace.

Return type:

wield.bunch

fit_ASD(freq, ASD, n_samples, relative_degree=-2, SNR=None)[source]¶

getSPO(S, O, D)[source]¶

get_margin(sys, input=None, output=None)[source]¶

Given a system, this function returns the gain margin of the system.

Parameters:

sys – (Bunch): Bunch system with mod as attribute and iod as attribute. iod is optional in the bunch (array | list): array of system data to use for the gain margin of the form [mag, phase, omega]
input (int, optional) – Input to use for the gain margin. Defaults to None.
output (int, optional) – Output to use for the gain margin. Defaults to None.

Returns:

Gain margin of the system phase_margin (float): Phase margin of the system in degrees

Return type:

gain_margin (float)

get_num_ins_outs(sys)[source]¶

Get the number of inputs and outputs of a model.

Parameters:: sys (dict | StateSpace | wield.mimo) – The model or dictionary to get the number of inputs and outputs of.
Returns:: The number of inputs. num_outs (int): The number of outputs.
Return type:: num_ins (int)

isControllable(sys)[source]¶

Check the controllability of a system

Parameters:: sys (wield.MIMO | wield.SISO) – MIMO or SISO system to check the controllability of
Returns:: True if the system is controllable, False if the system is not controllable
Return type:: bool

isDescriptor(sys, error=True, print_error=True)[source]¶

Check if the system is a descriptor system. A descriptor system is a system where the E matrix is not None and not all zeros.

Parameters:

sys (wield.MIMO | wield.SISO) – MIMO or SISO system to check if it is a descriptor system
error (bool, optional) – If True, an error will be raised if the system is not a descriptor system. Defaults to True.

Returns:

True if the system is a descriptor system, False if the system is not a descriptor system

Return type:

bool

isMIMO(sys)[source]¶

check if the system is of the buzz.ss.MIMOStateSpace type

Parameters:: sys (any) – system to check
Returns:: True if the system is of the buzz.ss.MIMOStateSpace type, False if not
Return type:: Bool

isObservable(sys)[source]¶

Check the observability of a system

Parameters:: sys (wield.MIMO | wield.SISO) – MIMO or SISO system to check the observability of
Returns:: True if the system is observable, False if the system is not observable
Return type:: bool

isSISO(sys)[source]¶

check if the system is siso

Parameters:: sys (wield.siso) – SISO system to check
Returns:: True if the system is SISO, False if the system is not SISO
Return type:: bool

isStable(sys)[source]¶

Check if a system is stable

Parameters:: sys (Bunch or MIMO, SISO sys) – System where the A matrix of it’s state space can be accesses by sys.A or sys.mod.A
Returns:: True if stable, False if unstable
Return type:: bool

listpoles(sys)[source]¶

List the poles of a system.

Parameters:: sys (Bunch or MIMO, SISO sys) – System where the A matrix of it’s state space can be accesses by sys.A or sys.mod.A
Returns:: List of poles
Return type:: np.array

listzeros(sys)[source]¶

List the zeros of a system. Adapted from python control library

Parameters:: sys (Bunch or MIMO, SISO sys) – System where the A matrix of it’s state space can be accesses by sys.A or sys.mod.A
Returns:: List of zeros
Return type:: list

loadSys(fname)[source]¶

load a system from a file

Parameters:: fname (string) – the filename of the file to load
Returns:: the system that was loaded
Return type:: wield statespace

load_zpk(fname='sys_zpk.yml', asZPK=False, **kwargs)[source]¶

Load the zeros, poles, and gain of a system from a file.

Parameters:

fname (str, optional) – The filename and path where the system should be loaded from. Defaults to ‘sys_zpk.yml’.
asZPK (bool, optional) – If true, the system will be returned as a zeros, poles, and gain model. Defaults to False.

Returns:

system with zeros, poles, and gain loaded from the file. Includes the iod if present in file. If asZPK is true, the system will be returned as a zeros, poles, and gain model.

Return type:

wield state space

makeFullModel(E, P, M, F1, F2, extras=False, EM=None, Zinf=True, diagnostic=False, delay=None, balance=False, include_F1=True, Ein=None, Eout=None, Min=None, Mout=None, Pin=None, Pout=None, F1in=None, F1out=None, F2in=None, F2out=None)[source]¶

makeFullModel takes all the principle systems for the EMPFF model and combines them into a single system. This function is used to combine the plant, the environment noise, the measurement noise, and the two FOMs into a single system. This function is used to combine the plant, the environment noise, the measurement noise, and the two FOMs into a single system. The function will also adjust the plant to make it strictly proper if it is not already. The function will also check that the plant, the environment noise, the measurement noise, and the two FOMs are all stable.

>>>>>>> dev

Args:
E (Wield State Space): The state space model of the environment noise P (Wield State Space): The state space model of the plant M (Wield State Space): The state space model of the measurement noise F1 (Wield State Space): The first FOM. This is normally the shaped FOM. It would be better to keep this one as the shaped FOM. F2 (Wield State Space): The second FOM. This is normally the flat FOM. It would be better to keep this one as the flat FOM. extras (string, bool, optional): Weather or not to add extra outputs for high frequency/low frequency FOMS. If output is ‘F3’, then the function will add an output after the controller that is equilivelant to actuator cost passed through F1. If extras is ‘F3_withP’, then the function will add an output after the controller that is equilivelant to actuator cost passed through the plant and F1. Defaults to False. EM (Wield State Space, optional): A two input two output system that combines the environment noise and the measurement noise. This is only used if the environmental noise and the measurement noise are interconected. For example in the LIGO test mass control case the shaking from seismic desturbances also shakes the shadow sensors so the environmental noise also effects the measurement noise. Defaults to None. Zinf (bool, optional): Weather to add a Z infinity input to the system. Defaults to True. diagnostic (bool, optional): Weather to print diagnostic information. Defaults to False. delay (float, optional): The delay of the system. Defaults to None. balance (bool, optional): If true the function will use the balance_sys_gain function to balance the system. Defaults to False. include_F1 (bool, optional): If False, it will drop the F1 FOM output. Typically only used when using the F3 FOM output. Defaults to True. Ein (string, optional): The name of the input to the environment noise system. Defaults to None. Eout (string, optional): The name of the output to the environment noise system. Defaults to None. Min (string, optional): The name of the input to the measurement noise system. Defaults to None. Mout (string, optional): The name of the output to the measurement noise system. Defaults to None. Pin (string, optional): The name of the input to the plant. Defaults to None. Pout (string, optional): The name of the output to the plant. Defaults to None. F1in (string, optional): The name of the input to the F1 system. Defaults to None. F1out (string, optional): The name of the output to the F1 system. Defaults to None. F2in (string, optional): The name of the input to the F2 system. Defaults to None. F2out (string, optional): The name of the output to the F2 system. Defaults to None.

Returns:
Wield State Space: The combined EMPFF system

makeSPOFF(S, P, O, F1, F2, extras=False, SO=None, Zinf=True, diagnostic=False, delay=None, balance=False, include_F1=True, Ein=None, Eout=None, Min=None, Mout=None, Pin=None, Pout=None, F1in=None, F1out=None, F2in=None, F2out=None)[source]¶: makeSPOFF takes all the principle systems for the SPOFF model and combines them into a single system. This function is used to combine the plant, the environment noise, the measurement noise, and the two FOMs into a single system. This function is used to combine the plant, the environment noise, the measurement noise, and the two FOMs into a single system. The function will also adjust the plant to make it strictly proper if it is not already. The function will also check that the plant, the environment noise, the measurement noise, and the two FOMs are all stable.

makeSys(mod, iod, wield=True, dt=0.0001)[source]¶

Make a system with iod and mod.

Note: This is legacy code and should be replaced with wieldSys

Parameters:

mod (control.lti) – The system to change the namespace of.
iod (dict) – The input output dictionary of the system.
wield (bool, optional) – Whether to wield the system. Defaults to True.
dt (float, optional) – The time step of the system. Defaults to 1e-4.

Returns:

Returns the local name space for the function including the state space model as mod, input output dictionary as iod, and namespace. or wield.control.mimo: system with the input output dictionary if wield is True

Return type:

wield.bunch

make_stable(sys)[source]¶

Make a given state-space model stable by shifting the eigenvalues of the A matrix. if system is stable, it will return the same system.

Parameters:: ss_model (control.StateSpace) – The state-space model to be made stable.
Returns:: A new state-space model that is stable.
Return type:: Wield MIMO SS

mergeSys(sysList: list, dictList, inlist=None, outlist=None)[source]¶

Merge a list of systems into one system.

Parameters:

sysList (list) – A list of systems.
dictList (list) – A list of dictionaries.
inlist (list) – A list of inputs.
outlist (list) – A list of outputs.

Returns:

The merged system. dict: The merged dictionary.

Return type:

control.lti

minreal(sys, *args, **kwargs)[source]¶

Minreal function for Bunch systems

Parameters:: sys (Bunch) – Bunch system with mod as attribute
Returns:: Bunch system with mod as attribute
Return type:: Bunch

multiconnect(sysList: list, conlist, dictList=None, balance=False, concentrate=False)[source]¶

Connect a list of systems together. This is a wrapper for the control.connect function. This function also appends input output dictionaries together.

Parameters:

sysList (list) – A list of systems or of Bunch objects including dictionaries.
conlist (list) – A list of connections. This is a list of lists of the form [[input1, output1], [input2, output2]]. The inputs and outputs can be either strings or integers. If they are strings, they must be in the input output dictionary of one of the models.
dictList (list, optional) – A list of dictionaries. Defaults to None.
balance (bool, optional) – Whether to balance the gain of each individual system using the balance_sys_gain() function. Defaults to True.

Returns:

Bunch with mod and iod as attributes

Return type:

Bunch

negsys(sys, iod=None)[source]¶

Make the negative of a system. Given a system with inputs u and outputs y, this function returns a system with output -y for inputs u.

Parameters:

sys (Bunch) – Bunch system with mod as attribute and iod as attribute. iod is optional in the bunch
iod (dict, optional) – input/output dictionary. Defaults to None.

Returns:

Returns the local name space for the function including the state space model as mod, input output dictionary as iod, and namespace.

Return type:

wield.bunch

normalize_gain(sys, norm=1, tol_percent=1, tol_mag=None, previous_scale=1, return_scale=False, method='L_inf', interval=[0.001, 10000.0])[source]¶

Normalize the maximum gain of a system to 1. This is done by dividing the system by the max gain of the system.

Parameters:

sys (Bunch) – Bunch system with mod as attribute.
norm (float, optional) – The value to normalize the gain to. Defaults to 1.
tol_percent (float, optional) – The tolerance for the gain. Defaults to 1.
previous_scale (float, optional) – The previous scale of the system used for recursive scaling. Defaults to 1.
return_scale (bool, optional) – Whether to return the gain applied to normalize the sys as well as the system. Defaults to False. return scale returns 1/max(mag)
method (str, optional) – The method to use to normalize the gain. ‘L_inf’: use the L_inf norm. ‘fq_resp’: uses wields frequency response. Defaults to ‘L_inf’.
interval (list, optional) – The interval to use for the frequency response. Not used if method is ‘L_inf’. Defaults to [1e-3, 1e4].

Returns:

Returns the local name space for the function including the state space model as mod, input output dictionary as iod, and namespace.

Return type:

wield.bunch

observabilityMatrix(sys)[source]¶

Get the observability matrix of a system

Parameters:: sys (wield.MIMO | wield.SISO) – MIMO or SISO system to get the observability matrix of
Returns:: observability matrix of the system
Return type:: np.array

order(sys)[source]¶

Get the order of the system

Parameters:: sys (wield.MIMO | wield.SISO) – MIMO or SISO system to get the order of. If the system is a state space model, the order will be the dimension of the A matrix. If the system is a ZPK model, the order will be the number of poles.
Returns:: order of the system
Return type:: int

reduce(sys, inputs, outputs, iod=None, minreal=False, balance_gain=False)[source]¶

removeIodIndices(iod, inputs_to_remove, outputs_to_remove)[source]¶

Take an iod and remove the inputs and outputs specified by the indices and or names provided in the inputs_to_remove and outputs_to_remove lists

Parameters:

iod (dict or Bunch) – input/output dictionary or bunch system with iod as attribute
inputs_to_remove (list) – List of indices or names of inputs to remove
outputs_to_remove (list) – List of indices or names of outputs to remove

Returns:

Input/output dictionary with the removed inputs and outputs

Return type:

dict

rename_io(sys, oldname, newname)[source]¶

Rename an input or output

Parameters:

sys (Bunch or dict) – Bunch system with mod as attribute
oldname (str or list) – old name of the input or output
newname (str or list) – new name of the input or output

Returns:

Returns the local name space for the function including the state space model as mod, input output dictionary as iod, and namespace.

Return type:

wield.bunch

reorder_io(sys, newinput, newoutput)[source]¶

save_zpk(sys, fname='sys_zpk.yml', safe=True)[source]¶

Save the zeros, poles, and gain of a system to a file. If the system is a State Space model, it will be converted to a zeros, poles, and gain model.

Parameters:

sys (wield.SISO) – SISO system to save.
fname (str, optional) – The filename and path where the system should be saved. Defaults to ‘sys_zpk.yml’.
safe (bool, optional) – If true, the system will be loaded to check if there are differences. Only save if the new file is different than the old one. This safety feature is useful for storing the models in git, without churning the index since binary matlab files can be different for no material reason. Defaults to True.

savesys(sys, name='savedsys.mat', safe=True)[source]¶

Save the system to a file.

Safe:: defaults False. If true, then load the system to check if there are differences. Only save if the new file is different than the old one. This

safety feature is useful for storing the models in git, without churning the index since binary matlab files can be different for no material reason.

scale_io(sys, ioname, gain)[source]¶

Scale an input or output

Parameters:

sys (Bunch or dict) – Bunch system with mod as attribute
ioname (str or list) – name of the input or output
gain (float or list) – gain to scale the input or output

Returns:

Returns the local name space for the function including the state space model as mod, input output dictionary as iod, and namespace.

Return type:

wield.bunch

switch_io(sys)[source]¶

Switch the inputs and outputs of the system

Parameters:: sys (Bunch or dict) – Bunch system with mod as attribute or iod dict
Returns:: Returns the local name space for the function including the state space model as mod, input output dictionary as iod, and namespace. or dict if dict was given as input
Return type:: wield.bunch or dict

transpose(sys)[source]¶

Transpose the system

Parameters:: sys (Bunch) – Bunch system with mod as attribute
Returns:: Returns the local name space for the function including the state space model as mod, input output dictionary as iod, and namespace.
Return type:: wield.bunch

truncate_io(sys, inputs, outputs, iod=None, minreal=False, balance_gain=False)[source]¶

Reduce a system to the specified inputs and outputs while removing unobservable states

Parameters:

sys (control.ss or bunch) – State space model or bunch system with mod and iod as attribute
inputs (list or string or int) – List of inputs to keep
outputs (list or string or int) – List of outputs to keep
iod (dict, optional) – Input/output dictionary to be provided if sys does not have an ido attribute. Defaults to None.
minreal (bool, optional) – Whether the system should be reduced using the control.minreal function. Defaults to False.
balance_gain (bool, optional) – Whether the system should be reduced using the ssutil.balance_sys_gain function. Defaults to False.

Returns:

Bunch with mod and iod as attributes

Return type:

Bunch

wieldSS(*args, iod=None)[source]¶