plecsutil.ui

class plecsutil.ui.Controller(idx: int = 1, get_gains: callable | None = None, label: str = '')

Bases: object

A class to represent multiple controllers in a PLECS model.

get_gains: callable = None

Callback to get the gains of the controller that are used in the model. The function should take a dictionary with the controller parameters as argument, and return a dictionary with the model parameters.

idx: int = 1

Index of the controller in the configurable subsystem.

label: str = ''

A label for the controller.

class plecsutil.ui.DataSet(t: ndarray, data: ndarray, source: str, meta: {})

Bases: object

A dataclass to hold data generated from a PLECS simulation.

data: ndarray

(N, M) matrix containing the signals connected to the output data ports.

meta: {}

A dictionary containing model and controller paramaters used to run the simulation. The dictionary always contain the following key:

  • model_params: The dictionary with the model parameters used in the simulation.

The dictionary may contain the following keys, if they are specified when running a simulation:

  • ctl: Controller used in the simulation. Only for models with multiple controllers.

  • ctl_params: Parameters used to generate the gains/parameters of the controller.

  • ctl_label: Controller.label of controller used for the simulation.

  • extras: Extra metadata that might be useful storing.

source: str

PLECS info (version, time and date of simulation).

t: ndarray

N-size vector with time steps of the simulation.

class plecsutil.ui.PlecsModel(file, file_path, model_params, get_ctl_gains=None, controllers=None)

Bases: object

A class representing a PLECS model.

PlecsModel provides a framework to set up and run simulations, and manage parameters of the model and its controllers.

Parameters:

  • file (str) – The filename of the model (without the .plecs extension).

  • file_path (str) – The path to the directory containing the model file.

  • model_params (dict) – A dictionary of model parameters for the simulation. These parameters are used to initialize the model and can be overridden by simulation-specific parameters when running simulations.

  • get_ctl_gains (callable, optional) – A function for retrieving control gains for the model’s controller. Only relevant if the model has a single controller.

  • controllers (Controller, optional) – An object representingthe controllers of the model. Only relevant for models with multiple controllers.

gen_m_file(sim_params={}, ctl=None, ctl_params={})

Generates the .m file for the simulation model.

Parameters:

  • sim_params (dict, optional) – Dictionary of simulation parameters to override the model’s default parameters. If not set, the simulation is executed with the default parameters.

  • ctl (NoneType or str, optional) – Sets the controller to be enabled in the simulation, in case of models with multiple controllers. If not set, the simulation runs with the default controller and its parameters (if there are any).

  • ctl_params (dict, optional) – Controller parameters, in case of model with one or more controllers. If not set, the default controller parameters are used for the simulation (if there is one).

Raises:

KeyError – If any parameter in sim_params or ctl_params does not exist in the default model parameters, KeyError is raised.

sim(sim_params={}, ctl=None, ctl_params={}, extra_meta={}, ret_data=True, save=False, close_sim=True)

Runs the PLECS simulation with specified parameters and returns the simulation data.

Parameters:

  • sim_params (dict, optional) – Dictionary of simulation parameters to override the model’s default parameters. If not set, the simulation is executed with the default parameters.

  • ctl (NoneType or str, optional) – Sets the controller to be enabled in the simulation, in case of models with multiple controllers. If not set, the simulation runs with the default controller and its parameters (if there are any).

  • ctl_params (dict, optional) – Controller parameters, in case of model with one or more controllers. If not set, the default controller parameters are used for the simulation (if there is one).

  • extra_meta (dict, optional) – Extra metadata used to build the controller or run the simulation that don’t fit in the other meta fields.

  • ret_data (bool, optional) – Whether to return the simulation. Default is True.

  • save (bool or str, optional) – Specifies whether to save the simulation data. If False, the data is not saved. If a string is provided, it will be used as the filename to save the data. Default is False.

  • close_sim (bool, optional) – Whether to close PLECS after running the simulation. Default is True.

Returns:

A DataSet object containing the simulation data. Returned only if ret_data is set to True.

Return type:

DataSet

Raises:

KeyError – If any parameter in sim_params or ctl_params does not exist in the default model parameters, KeyError is raised.

plecsutil.ui.gen_controllers_params(n_ctl, active_ctl)

Generates the logic to set controllers in models with multiple controllers.

Parameters:

  • n_ctl (int) – The total number of controllers.

  • active_ctl (int) – The index of the active controller to be enabled in the simulation.

Returns:

Logic for the .m file as a dictionary.

Return type:

dict

plecsutil.ui.load_data(file)

Loads simulation data from a zipped file.

Parameters:

file (str) – Name of the file, without .zip. Must include the full or relative path if file is in a different directory.

Returns:

data – Data loaded from the specified file.

Return type:

DataSet

plecsutil.ui.save_data(file, data)

Saves simulation data to a zipped file.

Parameters:

  • file (str) – Name of the file (without the .zip extension). The name can contain a relative or full path.

  • data (DataSet) – Simulation data.