Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Multiple Input/Multiple Output Shock Control

15Multiple Input/Multiple Output Shock Control

The MIMO Shock environment in Rattlesnake is implemented as a sum-of-decayed-sines (SDS) shock environment. Its purpose is to generate one or more drive signals whose resulting measured responses match a specified shock response spectrum (SRS) at one or more control channels.

The environment supports:

15.1Governing Equations

The SDS environment represents a shock signal as a sum of exponentially decaying sinusoids. For one drive channel, the excitation may be written as

v(t)=∑k=1NAke−ζkωk(t−τk)sin⁡ ⁣(ωk(t−τk))v(t) = \sum_{k=1}^{N} A_k e^{-\zeta_k \omega_k (t-\tau_k)} \sin\!\bigl(\omega_k (t-\tau_k)\bigr)
(15.1)

for t≥τkt \ge \tau_k, where:

For multiple drive channels, one such sum is constructed per drive channel.

The resulting measured control response x(t)\mathbf{x}(t) is related to the drives through the structural dynamics of the system. In the frequency domain this is still governed by the transfer function matrix

X(ω)=Hxv(ω)V(ω)\mathbf{X}(\omega) = \mathbf{H}_{xv}(\omega)\mathbf{V}(\omega)
(15.2)

where:

Instead of controlling directly to the transient x(t)\mathbf{x}(t) or its frequency response X(ω)\mathbf{X}(\omega), the goal is to generate a transient x(t)\mathbf{x}(t) whose SRS matches the specified SRS at the control channels.

If a measured or predicted response time history is denoted xi(t)x_i(t) for control channel ii, then the environment computes its SRS

Si(f)S_i(f)
(15.3)

using a bank of single-degree-of-freedom oscillators with specified damping and response type.

The SDS control problem therefore becomes:

  1. choose the sine-tone frequencies fkf_k,

  2. choose drive amplitudes AkA_k,

  3. choose drive decays ζk\zeta_k,

  4. choose drive delays τk\tau_k,

such that the measured response SRS approximately matches the specification at each control channel.

The current default control law begins from the MIMO inverse idea:

V(ω)=Hxv+(ω)Xtarget(ω)\mathbf{V}(\omega) = \mathbf{H}_{xv}^{+}(\omega)\mathbf{X}_{\text{target}}(\omega)
(15.4)

where Xtarget(ω)\mathbf{X}_{\text{target}}(\omega) is chosen to have the desired response amplitudes together with optimized response phases. These complex drive values are then converted into decayed-sine amplitudes and delays.

Because an SRS is not itself a complex spectrum, this requires an additional synthesis step: a response SRS target is first converted into a family of decayed sinusoids whose resulting transient approximately reproduces that SRS. The transfer functions are then used to solve for the corresponding drive signals that produce those desired decayed sine response signals.

15.2Specification Definition

The SDS environment specification is defined in terms of a shock response spectrum (SRS) rather than a CPSD or deterministic transient signal.

The specification consists of:

Internally this is represented by a SpecParameters object, which stores:

These data define the required response at the control channels.

15.2.1Specification File Format

Rather than entering the breakpoint table manually, which for large channel-count and tone-count tests would be tedious, the user can load the specification from an external file. The SDS environment currently loads specification data from a NumPy archive (*.npz) file or a MATLAB (*.mat) file.

Both NumPy and MATLAB files are structured identically, with the same field names and shapes associated with each field. Note that for 1D arrays, MATLAB can either specify n×1n \times 1 or 1×n1 \times n arrays; Rattlesnake will squeeze out the extra dimension.

Suppose the specification contains nfn_f SRS frequencies and ncn_c control channels, then the specification file should contain the following fields:

Any frequency/channel combination for which no control or no limit is desired may be represented with NaN.

For any array with dimension of size ncn_c, the ordering of this dimension must be identical to the ordering of the control degrees of freedom in the environment loading the file. No bookkeeping or reordering of specification data to match the channel data occurs in the SDS environment. If a transformation matrix is used, then the ordering of this dimension must be identical to the rows of the transformation matrix.

This is the same general rule used elsewhere in Rattlesnake: specifications are always defined in the actual control coordinates of the environment.

15.3Defining the MIMO Shock Environment in Rattlesnake

The SDS environment definition page allows the user to define:

A representative definition page is shown in Figure 15.1.

UI used to define the MIMO Shock / SDS environment.

Figure 15.1:UI used to define the MIMO Shock / SDS environment.

15.3.1Sampling Parameters

The Sampling section determines the sample rate and the transient block size used for one SDS hit.

The block size is important because it defines the duration available for the decayed-sine signal, and the sample rate is important to sufficiently extract the maximum response in the for the SRS computation. Various documentation, such as MIL-STD-810 1, suggest a sample rate of 10x the largest frequency of the shock response spectrum in order to adequately resolve the maximum response.

15.3.2Sine Tone Definition

The SDS environment supports multiple strategies for defining the frequencies used in the decayed-sine table, in the Sine Tone Frequencies portion of the window. This portion also defines if a compensation pulse is used. The compensation pulse is represented internally as an additional decayed-sine row with its own frequency and decay. This is useful in some SDS synthesis workflows to improve the shape or baseline behavior of the transient, often to create a signal with zero net velocity or displacement, so there is not a “snap-back” of the shaker system when the signal ends.

The default option is to specify the Sine Tone Table simply using the frequency breakpoints from the specification SRS as the sine tones in the SDS. In this case, the sine tone table is only for display purposes.

A second option is to specify the the Sine Tone Frequencies by octave. This will involve specifying the minimum and maximum frequency as well as the number of sine tones per octave.

The final approach is to manually specify the Sine Tone Table. In this case, the sine tone table will be editable, and options to add or remove tones will become available.

15.3.3Decay Definition

The environment supports several equivalent ways to define decay:

Internally these are converted into the damping-style decay values used during synthesis.

The environment supports either one common decay for all tones, or one decay value per tone.

Decay values are specified in the Sine Tone Decays portion of the window.

If a common decay is used, the Sine Tone Decays portion will have the additional widget

If decays are specified per sine tone, then they can be entered in the Sine Tone Table portion of the window.

15.3.4SRS Parameters

The SRS section defines how the response SRS is computed. This includes the SRS type, absolute vs. relative displacement convention, and damping. These parameters define both how the specification SRS is computed and how the SRS will be computed from time data.

15.3.5SDS Synthesis Parameters

The Sum of Decayed Sines Computation settings control the iterative decayed-sine synthesis algorithm. Because the computation of the SRS is a nonlinear operation on the time response data, an iterative solution is required to compute time response data that fits a given SRS.

15.3.6Control Law Definition

Like other advanced environments, SDS supports loading a custom Python control law in the Control Parameters section of the window. The definition page allows the user to specify a Python script and function or class within that script to use as a control law. The default control law uses a MIMO inverse-based approach and is described in Section Section 15.8.

15.3.7Control Channels

The Control Channels section defines which channels are used to evaluate and control the SRS response. The ordering of these channels determines the ordering of the specification columns when no transformation is used.

The Channel I/O section then summarizes the number of physical channels used as inputs, outputs, and control channels.

15.3.8Transformation Matrices

The SDS environment supports both response and excitation transformations, defined in the Control and Drive Transforms section of the window. These work the same way conceptually as in the other environments. A response transformation maps physical control channels into virtual control channels, and an excitation transformation maps physical drive channels into virtual drive signals. See Section 12.8 for the shared transformation-matrix workflow.

15.3.9Test Specification

The SRS specification itself is entered or loaded in the Specification section of the definition page. The user can add or remove breakpoints, edit the required SRS values, edit lower and upper limits, and set the target number of hits. If a user does not wish to control to a specific frequency tone for a specific channel or if upper or lower limits are not desired for that channel and frequency, a Value of NaN can be provided in the loaded specification file, or the value in the table can be set to Disabled.

The specification is added on the Specification section of the window on the Breakpoint Table tab. This is where the breakpoints are added or removed and the control values are modified.

The lower limits are added on the Lower Limit Table tab of the Specification portion of the window.

Similarly, upper limits are added on the Upper Limit Table tab of the Specification portion of the window.

Finally, there is functionality to display various channels of the specification.

15.4System Identification for the MIMO Shock Environment

Like the Random, Sine, and Transient environments, the SDS environment uses a system identification phase defined on the System Identification tab to estimate the transfer functions between the drive channels and control channels. This is shown when all environments are defined and the Initialize Environments button is pressed. The transfer functions are needed because the environment must map desired response behavior back into the corresponding drive signals that can be generated by the control system.

A typical system identification UI for the shock environment is shown in Figure 15.2.

System identification UI used by the MIMO Shock / SDS environment.

Figure 15.2:System identification UI used by the MIMO Shock / SDS environment.

Rattlesnake’s system identification phase will start with a noise floor check, where the data acquisition records data on all the channels without specifying an output signal. After the noise floor is computed, the system identification phase will play out the specified signals to the excitation devices, and transfer functions will be computed using the responses of the control channels to those excitation signals. Section 3.3 describes the System Identification tab and its various parameters and capabilities.

15.5Test Prediction for the MIMO Shock Environment

Once system identification is complete, the SDS environment can compute a prediction of the drive signals and the resulting response. Note that because the Sum-of-Decays sine calculation is iterative, it can take a bit of time to compute predictions using the default control law, see Section 15.8 for more information on the default control law’s computations.

A representative prediction page is shown in Figure 15.3.

Prediction UI used by the MIMO Shock / SDS environment.

Figure 15.3:Prediction UI used by the MIMO Shock / SDS environment.

The prediction page and associated run-table dialog allow the user to inspect:

15.5.1Excitation Prediction

The SDS prediction UI is centered around a table of decayed sine terms. For each excitation channel, the table stores:

for each sine tone.

These parameters fully define the synthesized drive transient for that drive channel. The Excitation Display shows the synthesized time history from the tone table. Selecting a row in the tone table will draw that specific sine tone’s contribution to drive transient.

15.5.2Response Prediction

The right side of the page displays response data. Responses are computed from a convolution of the generated drive signals with the system’s impulse response as measured in the System Identification phase of the controller. These plots allow the user to inspect whether the current open-loop or updated SDS table is likely to meet the specification.

15.6Running the MIMO Shock Environment

The Run Test tab of the SDS environment is where actual shock hits are executed and tracked.

A representative run page is shown in Figure 15.4.

Run GUI used by the MIMO Shock / SDS environment.

Figure 15.4:Run GUI used by the MIMO Shock / SDS environment.

The SDS run workflow differs from the Random and Sine environments because the natural unit of operation is a single hit, not a continuously running stationary control loop.

The SDS run mode supports:

A single SDS hit consists of:

  1. constructing a transient drive waveform from the current SDS table,

  2. playing that transient through the outputs,

  3. measuring the responses,

  4. aligning the measured drive and response to the expected transient,

  5. computing the response SRS,

  6. optionally updating the SDS table through the control law.

This is fundamentally different from the continuously updating loop used by Random Vibration.

The main Run Test tab for the Shock environment contains displays for tracking the overall drive levels and response errors. It also displays the control SRS to give the user a rough idea of the current responses.

The tab also has a number of widgets to control the environment as it is running.

A brief discussion of the capabilities provided by these widgets is described below.

15.6.1Manual Hits mode

In manual hits mode, each press of Start Environment performs exactly one hit and then returns to idle.

This is useful when dialing in the transient carefully or when the operator wants explicit control over each impact.

15.6.2Automatic Hits mode

In automatic mode, one press of Start Environment begins a sequence of repeated hits separated by the requested interval. The sequence continues until:

If post-hit computations take longer than the requested interval, the next hit is simply launched as soon as the computations finish.

15.6.3Hit counters and history

The SDS run page tracks:

Unlike a hardcoded “0 dB only” notion of target-level hits, the SDS environment interprets “hits at level” relative to the currently selected run test level. Thus, if the test level is set to -3 dB, then the displayed hit count and automatic stop logic both operate on the number of historical hits performed at -3 dB.

15.6.4Shock History

Clicking on the Shock History button opens the Shock History dialog shown in Figure 15.5.

Shock History Dialog

Figure 15.5:Shock History Dialog

The Shock History dialog provides an overview of what has been done to the test article, including:

This is especially useful when many lower-level “dial-in” hits are performed before full-level hits.

There are several numerical displays showing the number of hits.

There are also graphical displays showing a visual representation of the hit history.

If more detail is desired, a hit table can be shown, showing exactly when each hit occurred.

15.6.5Run-Time SDS Table

Clicking the SDS Table button will bring up a dialog containing a real-time display of the SDS table that is used to generate voltage signals. This is shown in Figure 15.6.

Shock History Dialog

Figure 15.6:Shock History Dialog

Depending on which options are checked the user can manually or the control law can automatically update the values in this table. When values are updated, the control law will automatically make response predictions based on the new drive signals. When measurements are obtained, the measured data will also be plotted on the response sections. This allows users or the control law to tune the controller as the run is progressing.

This dialog is particularly important because the SDS environment is table-driven: the current SDS table defines the transient that will be played on the next hit.

The left side of the window focuses on the drive signals:

The right side of the window focuses on measured responses and responses predicted from the updated drive voltages based on transfer functions.

15.6.6Displaying Data

In addition to the main UI showing all of the control SRSs and the Run Table showing predictions and measured responses, SRS and time histories from individual channels can be shown in separate windows using the operations in the Data Display. Representative windows are shown in Figure 15.7 and Figure 15.8.

Control SRS Window

Figure 15.7:Control SRS Window

Control Time Window

Figure 15.8:Control Time Window

15.7Output NetCDF File Structure

Like the other environments in Rattlesnake, the SDS environment stores its metadata in a netCDF group whose name matches the environment name.

Because the SDS environment derives from the shared system-identification infrastructure, its netCDF group contains SDS-specific metadata, shared system-ID metadata, and, when saving control data, the current SDS table, most recent hit data, and hit history.

Due to the complexity of the metadata for the SDS environment, the metadata is spread between the main group and several subgroups, each handling a specific portion of the metadata.

15.7.1NetCDF Dimensions

The SDS environment creates the following dimensions in its netCDF group.

15.7.2NetCDF Attributes

The SDS environment group stores both shared system-ID attributes and SDS-specific attributes on the environment’s netCDF group.

When saving current control data after or during a run, additional scalar attributes are also stored, including:

15.7.3NetCDF Variables

Only one variable consistently exists in the root environment group.

If transformation matrices are defined, the following variables may also be present directly on the environment group:

These variables are omitted when no transformation is used.

15.7.4Tone Parameters Subgroup

The subgroup tone_parameters stores:

15.7.5Compensation Pulse Subgroup

The subgroup compensation_pulse_parameters stores the following attributes:

15.7.6Decay Parameters Subgroup

The subgroup decay_parameters stores the following attributes:

This subgroup also stores one of the following:

15.7.7SRS Parameters Subgroup

The subgroup srs_parameters stores the following attributes:

These values fully define how the environment computes SRS values from transient response data.

15.7.8SDS Synthesis Parameters Subgroup

The subgroup sds_parameters stores the following attributes:

These values define how the response-side sum-of-decayed-sines synthesis is performed before the MIMO inverse is solved.

15.7.9Specification Parameters Subgroup

The subgroup specification_parameters stores the user’s SRS specification. It contains the following attribute:

The subgroup also stores the following dimensions:

The following variables are then defined:

If control or limits are not required for particular frequency/channel combinations, those entries may be NaN.

15.7.10Control Parameters Subgroup

The subgroup control_parameters stores metadata describing the SDS control law. It contains the following attributes:

A nested subgroup named control_extra_parameters is also created. This subgroup stores each additional control-law parameter as an attribute on the subgroup, using the parameter name as the attribute key.

This allows arbitrary scalar control-law settings to be stored without changing the netCDF schema.

15.7.11Saved Control Data

When the user saves current SDS control data from the Run Test page rather than streaming, the netCDF file additionally stores the current run state, including:

These are in addition to the environment metadata already described above.

If a run SDS table is stored, the following dimensions are created:

The following variables are then stored:

If the most recent measured drive signal is available, the following dimensions are created:

and the variable

If the most recent measured control response is available, the following dimensions are created:

and the variable

If the most recent measured response SRS is available, the following dimensions are created:

and the variable

To make post-run analysis easier, the current specification is also written explicitly to the saved control-data file even though it is already represented in the metadata subgroup. The following dimensions are created:

The following variables are stored:

When saving current SDS control data, the following scalar run-state attributes are written:

The hit history is stored in a flattened array form for easy analysis. The dimension

is created, and then the following arrays are stored:

This structure allows a saved SDS run file to serve not only as a metadata archive, but also as a record of what was actually done to the test article over the course of the run.

15.8Writing a Custom SDS Control Law

The SDS environment supports custom control laws through a Python function or class, and the current default implementation is a useful reference because it demonstrates the full chain from:

A custom SDS control law is expected to produce updated SDS table quantities:

for each decayed-sine term and drive channel.

15.8.1What the default SDS control law does

The current default control law, implemented in sds_sys_id_control_law.py, proceeds in several stages.

15.8.1.1Stage 1: Build the target response SRS

The control law begins from the target SRS stored in the environment metadata. This target is defined for each control channel at the SDS frequencies.

15.8.1.2Stage 2: Generate a decayed-sine representation of the target response

For each control channel, helper routines synthesize a decayed-sine signal whose resulting SRS approximates the target SRS. This produces:

15.8.1.3Stage 3: Interpolate the FRF matrix

The measured system-identification FRFs are interpolated onto the SDS frequencies.

15.8.1.4Stage 4: Solve a MIMO inverse with optimized response phases

At each SDS frequency, the control law solves a MIMO inverse problem using the transfer function matrix and an optimized set of response phases. This produces a complex drive vector for that frequency.

This is done using a pseudoinverse-based solve with phase-target optimization to balance:

15.8.1.5Stage 5: Convert complex drives into amplitudes and delays

The complex drive values are converted into:

and the phases are converted to delays via

τ=−ϕ2πf\tau = -\frac{\phi}{2\pi f}
(15.5)
15.8.1.6Stage 6: Optionally include a compensation pulse row

If a compensation pulse is enabled, the returned SDS table includes an additional row for it. The current default control law does not yet try to optimize the compensation pulse itself, so the compensation row is currently appended with zero amplitude.

15.8.2Function-Based SDS Control Laws

The simplest way to implement a custom SDS control law is as a Python function.

This is the same style used by the current default control law.

A function-based control law is best when the control calculation is mostly stateless, all required information is naturally available from the current call, or the user wants the simplest possible implementation.

A function-based SDS control law must accept the core arguments expected by the environment and must return

15.8.2.1Expected function signature

A function-based SDS control law should have a signature compatible with:

def my_sds_control_law(
    environment_metadata,
    sysid_data,
    last_response_srs=None,
    last_response_signals=None,
    last_drive_amplitudes=None,
    last_drive_decays=None,
    last_drive_delays=None,
    last_drive_signals=None,
    **kwargs,
):
    ...
    return amplitudes, decays, delays

The exact parameter order and keyword argument names need not match exactly, but the function must be callable using keyword arguments corresponding to the environment’s expected call pattern.

The function arguments are:

These last-* quantities may be None during the initial prediction stage, before any actual hit has been performed.

Additional keyword arguments can be specified in the function signature, but they must have type hints assigned to allow the UI to populate the correct interface to capture that argument. See Section 15.8.5 for more information.

15.8.2.2Return values

The function must return three arrays:

  1. amplitudes

  2. decays

  3. delays

These are expected to be shaped consistently with the environment’s SDS table:

Thus, if there are nfn_f SDS frequencies and non_o drive channels, the returned arrays should each have shape

(nf,no)(n_f, n_o)
(15.6)

If the compensation pulse is enabled, the final row corresponds to that compensation term.

15.8.2.3Minimal example

A minimal function-based control law might look like:

def my_sds_control_law(
    environment_metadata,
    sysid_data,
    last_response_srs=None,
    last_response_signals=None,
    last_drive_amplitudes=None,
    last_drive_decays=None,
    last_drive_delays=None,
    last_drive_signals=None,
    **kwargs,
):
    frequencies = environment_metadata.get_sds_frequencies_w_compensation_pulse()
    num_drive_channels = environment_metadata.num_reference_channels

    amplitudes = np.zeros((frequencies.size, num_drive_channels))
    decays = np.tile(
        environment_metadata.get_sds_decays_w_compensation_pulse()[:, np.newaxis],
        (1, num_drive_channels),
    )
    delays = np.zeros((frequencies.size, num_drive_channels))

    return amplitudes, decays, delays

This example is not useful as a real controller as it only outputs zeros, but it shows the required structure.

15.8.3Class-Based SDS Control Laws

A class-based control law is appropriate when the user wants to preserve state between calls.

This is useful when the control law needs to remember things like:

A class makes it easy to keep persistent internal state without rederiving or reparsing everything on every control-law call.

This is especially valuable for SDS because the environment is naturally hit-based and iterative.

15.8.3.1Expected class structure

A class-based SDS control law in the SDS environment is expected to provide at least:

A typical structure might look like:

class MySDSControlLaw:
    def __init__(
        self,
        environment_metadata,
        sysid_data,
        last_response_srs=None,
        last_drive_amplitudes=None,
        last_drive_decays=None,
        last_drive_delays=None,
        **kwargs,
    ):
        self.environment_metadata = environment_metadata
        self.sysid_data = sysid_data
        self.extra_parameters = kwargs

    def system_id_update(self, sysid_data):
        self.sysid_data = sysid_data

    def control(
        self,
        last_response_srs,
        last_response_signals,
        last_drive_amplitudes,
        last_drive_decays,
        last_drive_delays,
        last_drive_signals,
    ):
        ...
        return amplitudes, decays, delays

In practice, the current example class-based implementation (DefaultSDSControlLaw) uses the following pattern:

This means that a class-based SDS control law does not have to recompute the entire SDS table on every control(...) call. A valid implementation may instead compute the table once in system_id_update(...), cache it internally, and then either:

15.8.3.2Lifecycle of a class-based control law

A class-based SDS control law participates in the environment lifecycle as follows.

15.8.3.2.1__init__(...)

The environment constructs the class during environment initialization and passes in:

This is the correct place to:

15.8.3.2.2system_id_update(...)

When the system identification changes or is reloaded, this method is called so the control law can update any FRF-dependent internal state.

This is useful if the class wants to store:

15.8.3.3control(...)

This method is called to obtain the SDS table that should be used for prediction or for the next hit.

A class-based control law may choose to:

The current example class-based control law uses the third approach: it performs the main inversion and table construction in system_id_update(...), then control(...) returns the most recently computed:

This is a valid pattern when the control law is effectively open-loop after the most recent system-identification update.

15.8.3.4Practical guidance

A class-based SDS control law should still preserve the same core responsibilities as the function-based version:

  1. use the SRS specification as the response target,

  2. use the system identification data to relate response to drive,

  3. produce an SDS table that can be synthesized by the environment,

  4. optionally adapt that table based on previous measured hits.

The difference is that a class can preserve internal state between those calls.

15.8.4Interactive SDS Control Laws

The SDS environment also supports an interactive class mode, intended for more advanced workflows where the control law may need to exchange parameters or commands with a UI object.

This is the most advanced and most stateful control-law style.

An interactive control law may be appropriate when the user wants:

In this mode, the environment can:

This mode is best suited to research-oriented or experimental control implementations.

15.8.5Additional Control-Law Parameters and GUI Population

One of the most useful SDS features is that additional control-law parameters can be exposed automatically in the Environment Definition page when a Python control function is loaded.

When the user loads a Python module containing candidate SDS control laws, the UI inspects the available functions and classes and identifies which ones are valid control laws.

A function is considered valid if it contains the required arguments:

Any additional keyword-capable arguments beyond these required arguments are treated as extra control parameters.

The UI can automatically create widgets for extra parameters when the parameter type annotation is one of:

If the parameter has a supported type annotation, the UI creates a matching widget automatically:

If the parameter has an unsupported annotation but provides a default value, the function can still be loaded, but that argument is not exposed as an editable widget.

For example, a function like:

def my_sds_control_law(
    environment_metadata,
    sysid_data,
    last_response_srs=None,
    last_response_signals=None,
    last_drive_amplitudes=None,
    last_drive_decays=None,
    last_drive_delays=None,
    last_drive_signals=None,
    *,
    rcond: float = 1e-10,
    accuracy_weight: float = 100.0,
    input_weight: float = 1.0,
):
    ...

will automatically expose widgets for:

in the SDS Environment Definition page.

The UI collects those values into a dictionary and stores them in the ControlParameters metadata object.

For class-based SDS control laws, the same idea applies to the constructor. The UI inspects the __init__(...) signature of the class and exposes any supported additional keyword-capable constructor arguments as editable GUI parameters, while ignoring the standard runtime-provided SDS arguments such as the environment metadata and system identification package.

When the environment later calls the function-based control law or class control law’s __init__(...) method, those parameters are unpacked as keyword arguments:

control_law(
    environment_metadata=...,
    sysid_data=...,
    last_response_srs=...,
    last_response_signals=...,
    last_drive_amplitudes=...,
    last_drive_decays=...,
    last_drive_delays=...,
    last_drive_signals=...,
    **control_parameters,
)

Thus, extra control-law arguments are simply normal Python keyword arguments whose values are supplied by the UI.

If you want your control law to expose user-tunable parameters in the GUI, the easiest way is to:

  1. include the standard required SDS arguments,

  2. add additional keyword arguments,

  3. annotate them with supported Python types,

  4. provide reasonable default values.

That way the SDS UI can automatically build the needed widgets.

15.8.6What a Custom SDS Control Law Must Do

A replacement SDS control law should preserve the same broad responsibilities, even if the mathematics differ.

At minimum, a custom implementation should be able to:

  1. accept and store specification information,

  2. accept updated system identification results,

  3. compute an initial or updated SDS table,

  4. optionally preserve state between hits,

  5. return amplitudes, decays, and delays in the expected SDS table format.

In other words, even if a custom SDS control law uses a completely different synthesis or inversion strategy, it still needs to fit into the same environment lifecycle and data contract.

15.8.7Practical Guidance for Implementing a Replacement

15.8.7.1Preserve state explicitly if needed

If your control law needs to remember things like:

then use a class-based implementation rather than trying to reconstruct that state each call.

15.8.7.2Be careful about coordinate systems

The control law may be operating on:

A custom implementation should ensure that:

are all interpreted in mutually consistent coordinates.

15.8.7.3Respect the expected return format

The SDS environment expects arrays shaped like the current SDS table. In particular:

Returning the wrong shape will generally cause the environment to fail or produce invalid synthesis.

15.8.7.4Remember that measured data are scaled back to full level

During run-time postprocessing, the SDS environment scales measured response and drive data back up to the nominal full level before passing them to the control law. A custom control law therefore receives normalized data appropriate for direct comparison to the specification.

15.8.7.5Think carefully about hit-based iteration

Unlike Random or Sine, the SDS environment evolves one hit at a time. A replacement control law should therefore think in terms of:

If automatic SDS table updates are disabled, the environment may skip calling the control law entirely after hits, so a custom implementation should be designed with that workflow in mind.

15.8.8Summary

A custom SDS control law in Rattlesnake may be implemented as either:

The current default implementation is function-based, but class-based implementations are often a natural fit for SDS because the problem is iterative and hit-based.

The key requirement is that the control law must participate correctly in the SDS environment lifecycle and return:

in a form that the environment can synthesize and execute.

References
  1. United States Department of Defense. (2019). MIL-STD-810H: Environmental Engineering Considerations and Laboratory Tests (Standard MIL-STD-810H). U.S. Army Test. https://quicksearch.dla.mil/qsDocDetails.aspx?ident_number=35978
Rattlesnake Vibration Controller
Multiple Input/Multiple Output Sine Control
Rattlesnake Vibration Controller
Modal Testing