Control Module#

Defines control system elements for multibody dynamics models.

This module provides the infrastructure to define, valdiate and manage control-related elements within a multibody simulation. Control elements introduce time-domain behavior and system responses through differential equations, transfer functions, or external inputs and outputs.

It includes classes for defining first-order differential states, transfer functions, plant inputs and outputs, and interfaces for Functional Mock-up Units (FMUs). These allow integration of real-time control strategies, co-simulation with external tools, and system linearization capabilities.

This module enables simulation of feedback control systems and interfacing with external control software or hardware.

For a complete overview of all the modeling entities and how components integrate, refer back to the msolve.Model module.

class ActivateCoSim(**kwds)#

Activate CoSimulation class

cosim_dll_name#

Type=Str, Required

cosim_ptr#

Type=Int, Default=0

ip_address#

Type=Str, Default=localhost

pipe_name#

Type=Str

port#

Type=Int, Default=0

sendAfterMS()#

Can be called after motion solve has been invoked for cleanup

sendBeforeMS()#

Called before API_SendOffStartAutoProgramControl (i.e. END())

validateSelf(validator)#

Add your validation criteria for ActivateCosim, for example ensure that required parameters are defined

class CoSim(**kwds)#
Performs a one-/two-way coupled Leader/Follower simulation by instantiating separate MotionSolve processes.

Assume you have two models. The leading model has to contain an instance of this class that defines the connection between both models. As soon as the leading model simulates, it spawns a Follower process that contains the second model and begins to communicate with it.

Name

Type

Required

Default

Modifiable

Designable

bonding

Enum

\(\checkmark\)

COOPERATIVE

file

Str

\(\checkmark\)

i

Reference - Marker

\(\checkmark\)

id

Int

Auto

j

Reference - Marker

\(\checkmark\)

label

Str

name

Str

type

Enum

\(\checkmark\)

SPHERICAL

Usage

A displacement-force coupling is achieved by bonding i Marker on the leading model with j Marker on the following model. MotionSolve supports different types of bonding between both models:

  1. COOPERATIVE (two-way coupling): Binds i with j as specified by type. i provides displacement, and j returns forces.

  2. COERCIVE (two-way coupling): Binds i with j forcibly as specified by type. i provides forces, and j returns displacement.

  3. DICTATIVE (one-way coupling): Same as COOPERATIVE bonding except j does not return forces.

  4. IMITATIVE (one-way coupling): Same as COERCIVE bonding except i does not return forces.

bonding#

Type of bonding between i and j.

Type=Enum, Required, Default=COOPERATIVE

Permitted values are:

  • COERCIVE

  • COOPERATIVE

  • DICTATIVE

  • IMITATIVE

file#

Path and file name of the follower model.

Type=Str, Required

i#

Marker on the leading model bonded with j on the follower model.

Type=Reference (Marker), Required

j#

Marker on the follower model bonded with i marker on the leading model.

Type=Reference (Marker), Required

type#

Bonded joint type between i and j.

Type=Enum, Required, Default=SPHERICAL

Permitted values are:

  • CONVEL

  • CYLINDRICAL

  • FIXED

  • PLANAR

  • REVOLUTE

  • SPHERICAL

  • TRANSLATIONAL

  • UNIVERSAL

class CoSimulation(**kwds)#

Base class for CoSimulation. For a derived class, you can define the following methods as well as the createChildren and updateChildren method.

sendAfterCosim()#

Called after the co-simulation is done, when for example it is necessary to kill an executable

sendAfterMS()#

Called after API_SendOffCommandSimulate

sendBeforeMS()#

Called before API_SendOffStartAutoProgramControl is called

class Control(**kwds)#

Base class for control modeling elements.

The objects derived from Control are:

class Diff(**kwds)#

Creates a user-defined state variable and defines a first-order differential equation that describes it.

Name

Type

Required

Default

Modifiable

Designable

active

Bool

True

\(\checkmark\)

function

Function

\(\checkmark\)

\(\checkmark\)

ic

Double [2]

[None, None]

\(\checkmark\)

\(\checkmark\)

id

Int

Auto

implicit

Bool

False

label

Str

name

Str

routine

Routine

script

Script

static_hold

Bool

False

Example

Create a state variable using Diff.#
from msolve import *

model = Model(output="diff")

ground = Part(ground=True)
global_ref = Marker(body=ground)
Units(length="MILLIMETER")
Accgrav(kgrav=-9810)

body=Part(mass=1, ip=[1e3,1e3,1e3], cm=Marker(qp=[0,0,100], zv=[0,0,1]))

dif = Diff(function=f"ACCZ({body.cm.id},{global_ref.id})", ic=[1.25])

See also

For more details, see also Control: Differential Equation.

User Subroutine

The following user subroutine template expects the function signature and return value(s) as shown. Note that this is a placeholder implementation for reference purposes only.

def DIFSUB(id, time, par, npar, dflag, iflag):
  # calculate a differential equation value for a control Diff
  value = 0.0
  return value

For more information, see MotionSolve Subroutines.

function#

Parameters passed to user defined subroutine or a legal MotionSolve expression that defines the differential equation.

Type=Function, Required, Modifiable

ic#

Initial conditions of differential equation.

Type=Double [2], Default=[None, None], Modifiable, Designable

implicit#

Specifies if derivative is defined implicitly.

Type=Bool, Default=False

routine#

The value can be a callable Python function, a Matlab/OML script, or a string that includes the name of a DLL/SO file and the corresponding function name, separated by ‘::’.

Type=Routine

script#

Path and name of the script that contains the routine.

Type=Script

static_hold#

Specifies if dynamic state is kept fixed during static solution.

Type=Bool, Default=False

class Fmu(**kwds)#

Creates a Functional Mock-up Interface used for Model Exchange and Co-Simulation.

Name

Type

Required

Default

Modifiable

Designable

active

Bool

True

\(\checkmark\)

comm_intvl

Alias

dll

Str

nugsefmu

dll_name

Alias

geoms

Int [0]

0

ic

Reference - Array

id

Int

Auto

interval

Double

0.0

ip_addr

Alias

ip_address

Str

PIPE

label

Str

name

Str

path

Str

start_time

Double

0.0

static_hold

Bool

False

type

Enum

ME

u

Reference - Array

var_ic

Property

var_name

Str

x

Reference - Array

y

Reference - Array

See also

For more details, see also Control: FMU.

comm_intvl#

Alias to interval.

Type=Alias

dll#

Path and name of the DLL that is used to load the FMU.

Type=Str, Default=nugsefmu

dll_name#

Alias to dll.

Type=Alias

geoms#

Type=Int [0], Default=0

ic#

Array used to store the initial conditions for the continuous states.

Type=Reference (Array)

interval#

Time interval between successive communications with the FMU.

Type=Double, Default=0.0

ip_addr#

Alias to ip_address.

Type=Alias

ip_address#

IP address for the FMU connecting to MotionSolve.

Type=Str, Default=PIPE

path#

Path of the FMU file.

Type=Str

start_time#

The start time for the coupled co-simulation.

Type=Double, Default=0.0

static_hold#

Specifies if dynamic states x are kept fixed during static/quasi-static solution.

Type=Bool, Default=False

type#

Type of FMU.

Type=Enum, Default=ME

Permitted values are:

  • CS

  • ME

u#

Array used to store the input, u.

Type=Reference (Array)

var_ic#

The values of var_name variables that need to be set by the user.

Type=Property

var_name#

The names of the variables inside FMU that can be assigned a value.

Type=Str

x#

Array used to store the continuous states, x.

Type=Reference (Array)

y#

Array used to store the output, y.

Type=Reference (Array)

class Pinput(**kwds)#

Defines the inputs (type Variable) to a mechanical system or plant.

Name

Type

Required

Default

Modifiable

Designable

function

Function

\(\checkmark\)

hold_order

Int

1

\(\checkmark\)

id

Int

Auto

ip_addr

Str

label

Str

name

Str

offset_time

Double

\(\checkmark\)

routine

Routine

sampling_period

Double

\(\checkmark\)

script

Script

variables

Reference - Variable [0]

Example

Define a Plant Input.#
from msolve import *

model = Model(output="pinput")

Units(system="MKS")
ground = Part(ground=True)
global_frame = Marker(body=ground)

part = Part (mass=1, ip=[1e3]*3,cm=Marker())

var_lin = Variable(function = "100*TIME")
var_sin = Variable(function = "SIN(2*PI*TIME)")

pin = Pinput(variables = [var_lin], sampling_period = 0, offset_time = 0)

pout = Poutput(variables = [var_sin], sampling_period  = 0, offset_time = 0)

See also

For more details, see also Control: Plant Input.

User Subroutine

The following user subroutine template expects the function signature and return value(s) as shown. Note that this is a placeholder implementation for reference purposes only.

def PINSUB(id, time, par, npar, dflag, iflag):
  # compute the value of the Pinput element
  value = 0.0
  return value

For more information, see MotionSolve Subroutines.

function#

Parameters passed to user defined subroutine.

Type=Function, Modifiable

hold_order#

Order of interpolation applied to the control signal(s).

Type=Int, Default=1, Modifiable

ip_addr#

Type=Str

offset_time#

Sample time offset for each input port.

Type=Double, Modifiable

routine#

The value can be a callable Python function, a Matlab/OML script, or a string that includes the name of a DLL/SO file and the corresponding function name, separated by ‘::’.

Type=Routine

sampling_period#

Sample time of an input port.

Type=Double, Modifiable

script#

Path and name of the script that contains the routine.

Type=Script

variables#

Input variables to the plant.

Type=Reference (Variable) [0]

PlantState#

alias of Pstate

class Poutput(**kwds)#

Defines a list of outputs (type Variable) to a mechanical system or plant.

Name

Type

Required

Default

Modifiable

Designable

function

Function

\(\checkmark\)

hold_order

Int

1

\(\checkmark\)

id

Int

Auto

ip_addr

Str

label

Str

name

Str

offset_time

Double

\(\checkmark\)

routine

Routine

sampling_period

Double

\(\checkmark\)

script

Script

variables

Reference - Variable [0]

Example

For an example, see Pinput.

See also

For more details, see also Control: Plant Output.

function#

Parameters passed to user defined subroutine.

Type=Function, Modifiable

hold_order#

Order of extrapolations, default is ‘1’.

Type=Int, Default=1, Modifiable

ip_addr#

Type=Str

offset_time#

The sample time offset for each output port. The sample time offset must be strictly less than the sampling_period if the latter is non-zero. If the sampling_period is 0.0 (continuous), then offset_time defaults to 0.0 as well.

Type=Double, Modifiable

routine#

The value can be a callable Python function, a Matlab/OML script, or a string that includes the name of a DLL/SO file and the corresponding function name, separated by ‘::’.

Type=Routine

sampling_period#

The sample time for the output plant. A value of zero signifies continuous sampling. Any non zero value signifies discrete sampling.

Type=Double, Modifiable

script#

Path and name of the script that contains the routine.

Type=Script

variables#

Define a list of variables that define the plant output.

Type=Reference (Variable) [0]

class Pstate(**kwds)#

Creates a container for Solver Variables that are used in generating a linear representation of a model about an operating point.

Name

Type

Required

Default

Modifiable

Designable

id

Int

Auto

label

Str

name

Str

variables

Reference - Variable [0]

See also

For more details, see also Reference: PlantState.

variables#

A list of state Variable

Type=Reference (Variable) [0]

class Tfsiso(**kwds)#
Defines a transfer function as a ratio of two polynomials in the Laplace domain.

Modeling applications of this element include actuators (electrical, hydraulic, and pneumatic), vibration isolators (bushings and shock absorbers), and controllers (PID).

Name

Type

Required

Default

Modifiable

Designable

active

Bool

True

\(\checkmark\)

denominator

Double [0]

\(\checkmark\)

0.0

\(\checkmark\)

\(\checkmark\)

id

Int

Auto

label

Str

name

Str

numerator

Double [0]

\(\checkmark\)

0.0

\(\checkmark\)

\(\checkmark\)

static_hold

Bool

False

\(\checkmark\)

u

Reference - Array

\(\checkmark\)

\(\checkmark\)

x

Reference - Array

\(\checkmark\)

\(\checkmark\)

y

Reference - Array

\(\checkmark\)

\(\checkmark\)

Example

Create a SISO Transfer Function.#
from msolve import *

model = Model(output="tfsiso")

ground = Part(ground=True)
Units(system="MKS")

x = Array(type="x")
y = Array(type="y")
u = Array(type="u", size=1, variables=[Variable(function="20*SIN(2*PI*TIME)")])

tf = Tfsiso(numerator=[1, 0.5], denominator=[1, 2, 3], u=u, x=x, y=y)

See also

For more details, see also Control: SISO.

denominator#

List of coefficients, in ascending order of s, of the denominator polynomial of the transfer function.

Type=Double [0], Required, Default=0.0, Modifiable, Designable

numerator#

List of coefficients, in ascending order of s, of the numerator polynomial of the transfer function.

Type=Double [0], Required, Default=0.0, Modifiable, Designable

static_hold#

Specifies if dynamic states x are kept fixed during static/quasi-static solution.

Type=Bool, Default=False, Modifiable

u#

Array used to store the inputs ‘u’ of this Gse.

Type=Reference (Array), Required, Modifiable

x#

Array used to store the states ‘x’ of this Gse.

Type=Reference (Array), Required, Modifiable

y#

Array used to store the states ‘y’ of this Gse.

Type=Reference (Array), Required, Modifiable