agentlib_mpc.modules.dmpc.admm package

Submodules

agentlib_mpc.modules.dmpc.admm.admm module

Holds functionality for ADMM modules.

class agentlib_mpc.modules.dmpc.admm.admm.ADMM(config: dict, agent)

Bases: DistributedMPC

This class represents a module participating in a fully decentralized Consensus-ADMM optimization for distributed MPC. Agents autonomously send the values of their coupling variables, register other participants and perform update steps.

admm_step()

Performs an entire ADMM optimization.

all_coupling_statuses() → Iterable[ADMMParticipation]

Gives and iterator of all ADMMParticipation that are registered.

assert_mpc_variables_are_in_model()

Checks whether all variables of var_ref are contained in the model. Returns names of model variables not contained in the var_ref, sorted by keys: ‘states’, ‘inputs’, ‘outputs’, ‘parameters’.

collect_couplings_for_optimization()

Collects updated AgentVariables only of the coupling variables.

collect_variables_for_optimization(var_ref: VariableReference = None) → dict[str, agentlib.core.datamodels.AgentVariable]

Gets all variables noted in the var ref and puts them in a flat dictionary.

property cons_and_exchange: List[ExchangeEntry | CouplingEntry]

deregister_all_participants()

Sets the participating status of all participating agents to False.

get_participants_values(coupling_alias: str) → List[Series]

Get the values of all agents for a coupling variable.

get_results() → DataFrame | None

Read the results that were saved from the optimization backend and returns them as Dataframe.

Returns:

(results, stats) tuple of Dataframes.

participant_callback(variable: AgentVariable)

Puts received variables in the correct queue, depending on registration status of this agent.

property penalty_factor_var: MPCVariable

process()

This abstract method must be implemented in order to sync the module with the other processes of the agent and the whole MAS.

receive_participant(variable: AgentVariable)

Set the participation to true for the given coupling input.

property registered_participants: Dict[str, Dict[str, ADMMParticipation]]

Dictionary containing all other agents this agent shares variables with. Ordered in a two-layer form, with variables at the first layer and agents at the second layer. Contains ADMMParticipation objects at the base layer.

Examples

self.registered_participants = {‘coupling_var_1’: {‘src_of_agent1’: status_1,

‘src_of_agent2’: status_2, ‘src_of_agent3’: status_3}

‘coupling_var_1’: {‘src_of_agent3’: status_a,

‘src_of_agent2’: status_b, ‘src_of_agent4’: status_c}

} here, <status> refers to an ADMMParticipation object.

reset_participants_ready()

Sets the ready status of all participating agents to False.

send_coupling_values(solution: Results)

Sets the coupling outputs to the data_broker, which automatically sends them.

Parameters:

solution – Output dictionary from optimization_backend.solve().

send_coupling_variable(name: str, value: int | float | list[Union[int, float]] | Series | ndarray)

Sends an admm coupling variable through the data_broker and sets its value locally

update_lambda()

Performs the update of the lagrange multipliers. lambda^k+1 := lambda^k - rho*(z-x_i)

var_ref: VariableReference

pydantic model agentlib_mpc.modules.dmpc.admm.admm.ADMMConfig

Bases: DistributedMPCConfig

Config:

• arbitrary_types_allowed: bool = True

• validate_assignment: bool = True

• extra: str = forbid

• frozen: bool = True

Fields:

• couplings (List[agentlib_mpc.data_structures.mpc_datamodels.MPCVariable])

• exchange (List[agentlib_mpc.data_structures.mpc_datamodels.MPCVariable])

• iteration_timeout (float)

• max_iterations (float)

• penalty_factor (float)

• registration_period (float)

Validators:

• check_prefixes_of_variables » controls

• check_prefixes_of_variables » couplings

• check_prefixes_of_variables » exchange

• check_prefixes_of_variables » inputs

• check_prefixes_of_variables » outputs

• check_prefixes_of_variables » parameters

• check_prefixes_of_variables » states

field couplings: List[MPCVariable] = []

Validated by:

• check_prefixes_of_variables

field exchange: List[MPCVariable] = []

Validated by:

• check_prefixes_of_variables

field iteration_timeout: float = 20

Maximum computation + waiting time for one iteration.

Constraints:

• ge = 0

field max_iterations: float = 20

Maximum number of ADMM iterations before termination of control step.

Constraints:

• ge = 0

field penalty_factor: float = 10

Penalty factor of the ADMM algorithm. Should be equal for all agents.

Constraints:

• ge = 0

field registration_period: float = 2

Time spent on registration before each optimization

Constraints:

• ge = 0

validator check_prefixes_of_variables  »  exchange, parameters, couplings, inputs, states, outputs, controls

Ensures no user provided variable is named with the reserved ADMM prefix.

model_post_init(context: Any, /) → None

We need to both initialize private attributes and call the user-defined model_post_init method.

class agentlib_mpc.modules.dmpc.admm.admm.ADMMParticipation(variable)

Bases: object

Holds data for the status of a shared variable of another system.

de_register()

empty_memory()

class agentlib_mpc.modules.dmpc.admm.admm.LocalADMM(config: dict, agent)

Bases: ADMM

process()

This abstract method must be implemented in order to sync the module with the other processes of the agent and the whole MAS.

property registration_delay: float

Timeout value used to wait one on registration. Waits in real time (time.sleep)

property sync_delay: float

Timeout value used to sync local admm processes. Should be very small.

pydantic model agentlib_mpc.modules.dmpc.admm.admm.LocalADMMConfig

Bases: ADMMConfig

Config:

• arbitrary_types_allowed: bool = True

• validate_assignment: bool = True

• extra: str = forbid

• frozen: bool = True

Fields:

• registration_delay (float)

• sync_delay (float)

Validators:

field registration_delay: float = 0.1

field sync_delay: float = 0.001

model_post_init(context: Any, /) → None

We need to both initialize private attributes and call the user-defined model_post_init method.

class agentlib_mpc.modules.dmpc.admm.admm.ModuleStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

at_registration = 3

not_started = 1

optimizing = 4

sleeping = 7

syncing = 2

updating = 5

waiting_for_other_agents = 6

class agentlib_mpc.modules.dmpc.admm.admm.ParticipantStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

available = 2

confirmed = 3

not_available = 4

not_participating = 1

agentlib_mpc.modules.dmpc.admm.admm_coordinated module

Module implementing the coordinated ADMM module, which works together with a coordinator.

class agentlib_mpc.modules.dmpc.admm.admm_coordinated.CoordinatedADMM(*, config: dict, agent: Agent)

Bases: MiniEmployee, ADMM

Module to implement an ADMM agent, which is guided by a coordinator. Only optimizes based on callbacks.

get_new_measurement()

Retrieve new measurement from relevant sensors Returns:

init_iteration_callback(variable: AgentVariable)

Callback that answers the coordinators init_iteration flag.

optimize(variable: AgentVariable)

Performs the optimization given the mean trajectories and multipliers from the coordinator. Replies with the local optimal trajectories. Returns:

process()

This abstract method must be implemented in order to sync the module with the other processes of the agent and the whole MAS.

registration_callback(variable: AgentVariable)

callback for registration

pydantic model agentlib_mpc.modules.dmpc.admm.admm_coordinated.CoordinatedADMMConfig

Bases: MiniEmployeeConfig, ADMMConfig

Config:

• arbitrary_types_allowed: bool = True

• validate_assignment: bool = True

• extra: str = forbid

• frozen: bool = True

Fields:

• shared_variable_fields (list[str])

Validators:

• check_valid_fields » shared_variable_fields

• couplings_should_have_values » couplings

• couplings_should_have_values » exchange

field shared_variable_fields: list[str] = ['messages_out', 'outputs', 'controls']

Validated by:

• check_valid_fields

validator couplings_should_have_values  »  exchange, couplings

Asserts that couplings and exchange have values, as they are needed for initial guess.

model_post_init(context: Any, /) → None

We need to both initialize private attributes and call the user-defined model_post_init method.

agentlib_mpc.modules.dmpc.admm.admm_coordinated.coupInput

alias of coup_input

agentlib_mpc.modules.dmpc.admm.admm_coordinator module

Defines classes that coordinate an ADMM process.

class agentlib_mpc.modules.dmpc.admm.admm_coordinator.ADMMCoordinator(*, config: dict, agent: Agent)

Bases: Coordinator

cleanup_results()

Deletes all files this module created.

Override this method, if your module creates e.g. results files etc.

get_results() → DataFrame

Reads the results on iteration data if they were saved.

optim_results_callback(variable: AgentVariable)

Saves the results of a local optimization. :param variable:

Returns:

register_agent(variable: AgentVariable)

Registers the agent, after it sent its initial guess with correct vector length.

registration_callback(variable: AgentVariable)

trigger_optimizations()

Triggers the optimization for all agents with status ready. Returns:

pydantic model agentlib_mpc.modules.dmpc.admm.admm_coordinator.ADMMCoordinatorConfig

Bases: CoordinatorConfig

Hold the config for ADMMCoordinator

Config:

• arbitrary_types_allowed: bool = True

• validate_assignment: bool = True

• extra: str = forbid

• frozen: bool = True

Fields:

• abs_tol (float)

• admm_iter_max (int)

• dual_tol (float)

• penalty_change_factor (float)

• penalty_change_threshold (float)

• penalty_factor (float)

• prediction_horizon (int)

• primal_tol (float)

• registration_period (float)

• rel_tol (float)

• sampling_time (float | None)

• save_iter_interval (int)

• save_solve_stats (bool)

• solve_stats_file (str)

• time_step (float)

• use_relative_tolerances (bool)

• wait_time_on_start_iters (float)

Validators:

• default_sampling_time » sampling_time

• solve_stats_file_is_csv » solve_stats_file

field abs_tol: float = 0.001

Absolute stopping criterion.

field admm_iter_max: int = 20

Maximum number of ADMM iterations before termination of control step.

field dual_tol: float = 0.001

Absolute dual stopping criterion.

field penalty_change_factor: float = 2

Factor to vary the penalty parameter with.

field penalty_change_threshold: float = -1

When the primal residual is x times higher, vary the penalty parameter and vice versa.

field penalty_factor: float = 10

Penalty factor of the ADMM algorithm. Should be equal for all agents.

field prediction_horizon: int = 10

Prediction horizon of participating agents.

field primal_tol: float = 0.001

Absolute primal stopping criterion.

field registration_period: float = 5

Time spent on registration before each optimization

field rel_tol: float = 0.001

Relative stopping criterion.

field sampling_time: float | None = None

Sampling interval for control steps. If None, will be the same as time step. Does not affect the discretization of the MPC, only the interval with which there will be optimization steps.

Validated by:

• default_sampling_time

field save_iter_interval: int = 1000

field save_solve_stats: bool = False

When True, saves the solve stats to a file.

field solve_stats_file: str = 'admm_stats.csv'

File name for the solve stats.

Validated by:

• solve_stats_file_is_csv

field time_step: float = 600

Sampling interval of between two control steps. Will be used in the discretization for MPC.

field use_relative_tolerances: bool = True

If True, use abs_tol and rel_tol, if False us prim_tol and dual_tol.

field wait_time_on_start_iters: float = 0.1

wait_on_start_iterations

validator default_sampling_time  »  sampling_time

model_post_init(context: Any, /) → None

We need to both initialize private attributes and call the user-defined model_post_init method.

validator solve_stats_file_is_csv  »  solve_stats_file

Module contents