Models of the Advanced LIGO Suspensions in Mathematica™

Purpose and Scope

This document outlines the physical assumptions, internal structure, and applications of the Advanced LIGO suspension models developed in Mathematica by Mark Barton, distinguishing them from the Matlab models created by Calum Torrie and Ken Strain.

Version history

1/15/03: Pre-rev-00 draft Discusses quad model v 2.0.3.

3/2/2005: Rev 01 Discusses quad and triple models 3.3 and toolkit version 2.0.

9/13/2006: Rev 02 draft Added theory of transfer functions and state-space matrix export Added illustration of concepts using a toy model.

6/4/08: Rev 02 final Added References section Mentioned quad lateral model, violin mode models, Mathematica v.6 changes Added diagram for toy model section.

Features

The triple and quad pendulum models utilize a Mathematica toolkit designed for creating mass-wire-spring systems, originally developed from the analysis of the X-pendulum, which was proposed as a low-frequency vibration isolator for the Japanese TAMA project (Barton et al., 1994, 1996) This toolkit facilitates the modeling of essential physical components.

(i) Rigid bodies with up to 6 degrees of freedom

(ii) Massless wires with longitudinal, transverse and torsional elasticity

(iii) Springs described by a 6x6 matrix of elastic constants and a 6x1 vector of preload forces

All sources of elasticity can have arbitrary frequency dependent damping.

At the time of Rev 00, the toolkit consisted of Mathematica functions that needed to be individually copied into each model description file As the number of models grew, maintaining synchronization among these copies became increasingly challenging To address this issue, the functions from version 2.5 of the quad model were consolidated into a Mathematica package known as PendUtil.nb This document describes version 2.0 of the toolkit.

In this document, a "model" refers to a specific arrangement of toolkit elements such as masses, wires, and springs, without detailing the numerical properties of these elements A "case" represents this model with assigned numeric values LIGO focuses on two primary models: one for a generic GEO-style triple suspension and another for a quad suspension Furthermore, additional models can be easily created by using existing models as templates.

Method of calculation

Basic Normal Mode Calculation

The calculation is based on the method of normal modes as described in Goldstein, “Classical Mechanics” Conceptually such a calculation has the following steps:

(i) Express the potential energy of the system in terms of the coordinates:

(ii) Express the kinetic energy of the system in terms of the coordinates and coordinate velocities:

E K = E K (x 1 , x n , x ˙ 1 , x ˙ n ) (iii) Minimize the potential energy to find the equilibrium values of the coordinates. x eq = x( 1 eq ( ) , x n eq ( ) )

(iv) Differentiate the potential energy of the system w.r.t pairs of coordinates at equilibrium to create a matrix of second derivatives, a.k.a., the potential energy matrix or the stiffness matrix.

(v) Differentiate the kinetic energy of the system w.r.t pairs of coordinate velocities at equilibrium to create a matrix of second derivatives, a.k.a., the kinetic energy matrix or the mass matrix.

(vi) Do a simultaneous diagonalization of the stiffness and mass matrices to obtain the eigenfrequencies f i =ω i 2π and eigenmodes e i :

However for a practical calculation step (iv) needs to be considerably elaborated, partly for efficiency and partly to support additional calculations such as transfer functions and thermal noise estimates.

Categories of Coordinates and the Master Potential Matrix

In normal mode analysis, it is essential that the coordinates are independent and effectively represent the position and orientation of all masses involved in the oscillation Additionally, there are two other categories of coordinates that warrant attention.

In mechanical systems, the position and orientation coordinates of junctions connecting elastic elements without mass are known as floats These floats are influenced by the adjacent elastic elements, allowing them to occupy positions that exist between the mass elements The relationship can be represented mathematically as q = q(1, , q m) T.

Using specific junctions and coordinates can simplify problem specification; however, for normal mode analysis, these coordinates are not independent It is essential to resolve the equations for force equilibrium at the junction to express them in terms of the true normal mode coordinates.

The position and orientation coordinates of the structure, along with other points connected to the pendulum by elastic elements, are represented as s = s(1, s l) T For normal mode analysis, these coordinates are fixed at nominal positions s nom = s(1(nom), s l(nom)) T, while they are considered movable when calculating the transfer function based on displacement.

To cope with these complications it is convenient to consider a master potential matrix with second derivatives with respect to all three classes of coordinates:

P : E P = E P (x eq ,q eq ,s nom ) + 1 2(x T −x eq T q T −q eq T s T −s nom T )P x−x eq q−q eq s−s nom

⎟ The master potential matrix has a block structure with many useful submatrices:

The Effective Potential Matrix

In cases where there is a non-zero number of float coordinates, the traditional K submatrix of P becomes unsuitable for normal mode analysis, as it includes partial derivatives with q held constant Instead, it is essential to utilize an effective value, K eff, which is calculated using the dynamic equilibrium positions of q i over time When the structure is at its nominal position, s = s nom, the equilibrium positions can be expressed as q = q eq − Q − 1 C QX (x − x eq).

The Equation Of Motion Matrix and the Coupling Matrix

To calculate the transfer function from the displacement input of a structure, it is essential to utilize the matrix that couples the displacements of the s coordinates to the generalized force inputs at the x coordinates In the absence of floating coordinates, this is represented by the submatrix C XS However, similar to normal mode analysis, additional terms arise from the variation in q, leading to the equation: f xs = C XS(eff)(s - s nom) = C(XS - C XQ Q −1 C QS)(s - s nom).

If we also allow for other generalized forces f x acting directly on x, the equation of motion during a transfer function test is

K eff (x−x eq ) + M x = f˙ x + C XS( eff ) (s−s nom )

In the frequency domain this becomes

The equation K eff (x−x eq )−(2πf) 2 M x( −x eq ) = f x + C XS( eff ) (s−s nom ) represents a dynamic system where f denotes frequency in Hz By solving this equation for various frequency values, one can derive transfer functions related to force-input or displacement-input Additionally, the left side of the equation can be reformulated as an equation of motion matrix, facilitating further analysis of the system's behavior.

The Structure Matrix

When integrating models in state-space form for Simulink or E2E, coupling a pendulum model with a corresponding SEI platform is beneficial This process involves calculating the support forces, which consist of two components The force generated by the pendulum's motion, while the structure remains unchanged, is represented by the transpose of the coupling matrix Specifically, the equation f sx = Χ ΣΞ(εφφ) (ξ − ξ εθ) illustrates this relationship, where Χ(ΣΞ − Χ ΣΘ Θ −1 Χ ΘΞ) ξ − ξ(εθ) = ΧΤ ΞΣ(εφφ)(ξ − ξ εθ) provides the necessary calculations for accurate modeling.

This would be incorporated in the state-space C matrix The component generated as the pendulum remains constant but the structure moves is f ss = Σ (εφφ) (σ− σ νοà ) = Σ − Χ( ΣΘ Θ −1 Χ ΘΣ ) σ− σ( νοà)

This would be incorporated in the state-space D matrix Together the two terms give the total force for arbitrary relative motion of the support and pendulum.

Damping

Lossiness in elastic components can be represented by a complex elastic constant: k→k 0 (ε ω′( ) + i ε ω′′( )) (where ω=2πf ) where the real and imaginary multipliers ε ′ and ε ′ ′ are related by the Kramers-Krửnig relations: ε ω′ ( ) −1 = 2 π PV ε′′( )x x−ω

Provided the losses are small, the frequency dependence of the real part can be neglected and the imaginary part can be identified as a frequency dependent loss angle: k→k 0 (1+ iφ( )f )

To implement this approach effectively within the toolkit, two key issues must be addressed Firstly, the varying magnitudes and frequency dependencies of damping multipliers across different elastic components necessitate a division of the total potential into distinct terms, allowing for independent processing If dissipation dilution is not applicable, further considerations will be required.

P =∑ P i ( ε ′ i ( ) + i f ε ′ i ′ ( ) f ) ………( i =1…number of terms; no dissipation dilution)

This has a number of advantages:

Generating the P i is efficient because each typically relies on only a limited number of variables This allows for an optimization process where only the relevant variables for each specific term are iterated over, significantly speeding up the computation compared to allowing Mathematica to independently determine the independence of most terms from the majority of variables.

Organizing the numeric values of P i separately from the symbolic values of ε ′ i and ε ′ ′ i enhances efficiency in calculations By delaying their combination until the final stages, it enables the exploration of various ε ′ i and ε ′ ′ i values without incurring the expense of recalculating P i.

Incorporating optional terms for wire bending and torsion is crucial, as these calculations can be expensive yet often yield minimal values Their significance primarily arises in the context of thermal noise assessment.

• It also facilitates the handling of dissipation dilution (see below).

Dissipation dilution

Naively calculating the damping and thermal noise by summing the P i with damping multipliers often leads to an overestimation due to the neglect of dissipation dilution This phenomenon occurs when a restoring force is applied to an object using a lossy spring in two distinct ways The first method involves directly attaching the spring to the object, resulting in first-order changes in the spring's length during oscillations, leading to proportional energy dissipation Alternatively, the second method employs the spring to generate a static force, with a mechanical device adjusting the mechanical advantage between this static force and the object's force A classic example is a violin string, where longitudinal tension creates a lateral restoring force; here, first-order lateral movements yield only second-order changes in length, resulting in minimal energy loss for small amplitudes.

A pendulum, as simulated by the toolkit, presents a unique variation on the second case, demonstrating low net loss due to two independent factors Firstly, the potential energy during the bob's lateral movements is stored gravitationally rather than through the extension of the lossy fiber Secondly, the restoring force acting on the bob arises from the lateral component of the fiber's tension Notably, a pendulum can maintain low loss even if its tension is supplied by a secondary wire instead of gravity, similar to a violin string This distinction is crucial, as the normal mode formalism may not effectively differentiate between these two mechanisms.

In analyzing a pendulum with an elastic wire, two natural coordinate systems can be utilized: polar coordinates centered around the suspension point and Cartesian coordinates In polar coordinates, the pendulum's eigenmode manifests as an oscillation in the angle θ while maintaining a constant radius r Conversely, in Cartesian coordinates, the equivalent mode reflects horizontal oscillation, necessitating a second-order extension of the spring Notably, the potential energy in the spring during horizontal motion is precisely equal to the potential energy in the gravitational field during circumferential motion, resulting in identical eigenfrequencies Ultimately, a real pendulum embodies a combination of these two idealizations, influenced by the wire's stiffness.

Accurate specification of the problem is crucial, as one case can replace another, and a simplistic approach may lead to an overestimation of damping While the system's oscillatory energy is maximized in the potential energy of the pendulum wire at peak excursion, energy loss per cycle is minimal, resulting in an infinite Q at small amplitudes To isolate the low-loss component of the restoring force, which arises from a static force via variable mechanical advantage, one should evaluate the second derivatives twice: first with the complete potential and then with all tensions and static forces set to zero.

P =∑(P i tension _ off (ε′ i ( ) + i f ε′ i ′( )f ))+ ∑( P i tension _ on −P i tension _ off )

A restoring force that remains active when tension is released leads to length changes in the corresponding spring, which are proportional to the first-order oscillation amplitude This results in an energy loss that is also first-order relative to the stored energy.

For more on dissipation dilution, see T070101-00.

Potential terms for standard elements

Wires

A wire connects a designated point in local coordinates on one object to a corresponding point on another object Users have the option to define the attachment angles from which the wire extends from each object; if no angles are specified, it is assumed that the wire aligns with its direction at equilibrium.

The potential energy of each wire is divided into several distinct components, each featuring its own damping function The initial component accounts for the increase in the straight-line distance between the endpoints.

The user must provide the net elastic constant of the wire, denoted as k w, either directly or through related quantities like the Young’s modulus To establish the tension-off condition necessary for calculating dissipation dilution, the unstretched length, l 0, is defined to be equal to the equilibrium length.

Torsional energy, when considered for damping purposes, can be divided into two components: one that is proportional to the unloaded torsional rigidity and another that is proportional to the tension.

The equation ∆θ T 2 represents the relationship between tension (T), polar moment of area (J), torsional elastic modulus (G), torsional stiffness geometric factor (J e), and net twist (θ T) Utilizing advanced geometry, θ T can be automatically calculated based on the coordinates of the attachment points.

The energy associated with lateral bending in a wire is determined by treating it as a massless beam under tension This bending shape can be analytically derived, leading to a complex closed-form expression for energy This expression is influenced by factors such as tension, Young’s modulus, the axial moments of area along the wire's principal axes, and the degree of bending at the endpoints compared to the straight line connecting them.

The term refers to the energy resulting from a slight additional longitudinal stretch caused by lateral bending, which is influenced by the same factors mentioned previously.

Springs

A spring connects two points on separate objects, applying restoring forces in six degrees of freedom (DOFs) based on a tensor of elastic constants and a vector of pre-load forces.

Phases of the calculation

The calculation of wire bending potential is divided into five stages: 0A, 0B, 1A, 1B, and 2 Stage 0 focuses on calculating potential terms related to gravity, springs, and wire stretching In Stage 1A, additional terms for wire torsion are incorporated, while Stage 1B introduces terms for bending at the attachment points Finally, Stage 2 accounts for slight longitudinal stretching of the wires caused by bending away from the initial straight-line assumption made in Stage 0.

Utility functions

To support the above calculations the toolkit provides a large number of utility functions which are common to both the triple and quad models:

(i) geometry of points on rigid bodies subject to translations and rotations

(ii) geometry of angular velocity and infinitesimal rotations

(iii) manipulating variables, parameters and velocities

(iv) manipulating lists of substitutions

(v) properties of wires (length, stretching and bending potential energy etc)

(vii) creating the total potential for the system

(viii) creating matrices of elastic constants (a.k.a., potential energy matrices)

(ix) creating matrices of mass/MOI coefficients

(x) processing and pretty-printing eigenvectors

(xi) outputting useful intermediate results

(xii) converting to state-space matrix format

Model specific utilities

In addition to specifying the model, users must provide certain utility functions that are indirectly related to the model, making it impossible for these functions to accept the model specification as a parameter or to be generated automatically.

(i) routines for drawing 3D pictures of the mode shapes

(ii) vectors that specify force and displacement inputs of interest (e.g., “unit x-direction displacement input at the structure”)

(iii) vectors that specify outputs of interest (e.g., “unit x-direction displacement output at the upper left OSEM position”)

Dynamics via frequency dependent matrices

There are two effective methods for representing system dynamics: frequency-dependent matrices and state-space formalism Frequency-dependent matrices are particularly useful in Mathematica due to their smaller size and enhanced ability to accurately depict damping effects Alternatively, state-space formalism provides another approach to modeling dynamics, which will be explored in the following section The dynamics of a pendulum can be effectively expressed using a frequency-dependent equation of motion matrix.

Conceptually, the frequency domain transfer function from force/torque on the pendulum to displacements of the pendulum is x= Ε −1 φ ξ

Numerical solutions can be obtained for various frequency values, f For practical computations, it is advisable to use specialized routines like Mathematica’s LinearSolve[] instead of directly taking the inverse and multiplying.

The transfer function from structure displacement is then derived by transforming to a force first: x= Ε −1 Χ ΞΣ(εφφ) σ

Dynamics via state-space formalism

For time domain simulation, the state-space formalism is advantageous as it facilitates the export of state-space matrices in formats compatible with Matlab/Simulink or E2E In mechanical problems, the state-space representation of a pendulum includes both positions/orientations and linear/angular velocities, represented as a double-length vector: x− ξ εθ.

We assume a standard set of inputs and outputs convenient for E2E: inputs= σ− σ νοà φ ξ

 i.e., displacement of the structure and force on the mass, and outputs= ξ − ξ εθ φ σ

 i.e., the position of the mass and force back on the structure Then the state-space matrices are

 and the state space equations are

The transfer function in Laplace transform format is x− ξ εθ φ σ

For numerical time domain simulation, it is essential that the matrix coefficients are both real and frequency-independent While the stiffness matrices are generally real, they may not always be frequency-independent Typically, the real parts of these stiffness matrices exhibit weak frequency dependence, allowing for a reasonable approximation by using values at DC or a frequency close to the relevant eigenfrequencies However, the submatrix may require special consideration.

The term Im(−Μ −1 Κ εφφ ) 2π φ in the lower right of the A matrix is frequency independent only when all damping sources are proportional to velocity, resulting in a numerator that is proportional to frequency (f) This relationship allows for the cancellation of frequency in the denominator, leading to a purely numeric matrix Conversely, structural damping presents a frequency-independent numerator but a frequency-dependent quotient, making it incompatible with this representation.

3 Illustration of concepts with a toy model

A mass \( m \) is allowed to move freely along the x-axis, connected to a fixed mechanical ground by two massless springs, \( k_1 \) and \( k_2 \), which are arranged in series The position of the mass is denoted by \( x \), the junction between the two springs is represented by \( q \), and the fixed ground position is indicated by \( s \) In this context, \( x \) is classified as a variable, \( q \) is identified as a float, and \( s \) is considered a parameter.

Stiffness and coupling matrices

E P = 1 2 κ 1 (θ − σ) 2 + 1 2 κ 2 (ξ − θ) 2 The master stiffness matrix is

The float stiffness matrix Q gives the elasticity on the junction with both the structure and mass fixed:

The overall stiffness in a parallel system is the sum of the individual stiffnesses A positive gradient indicates that when the junction is slightly displaced in the +x direction, it experiences a restoring force that acts in the -x direction.

In the established sign convention, multiplying a stiffness matrix by a displacement vector results in a potential gradient vector, while incorporating a negative sign transforms it into a force or torque vector.

The raw stiffness matrix K is determined solely by the spring constant of the nearest spring, denoted as k2, since the partial derivatives are calculated with q held constant Conversely, the effective stiffness matrix comes into play when q is permitted to adjust to its time-dependent neutral position between s and x.

As might be hoped, this is the usual formula for the stiffness of two springs added in series.

The raw coupling matrix from the structure to the mass (C XS) is zero, indicating that the two points are not directly connected However, the effective value takes into account the influence of the two springs.

The negative sign here says that when the structure moves in the +x direction, the mass encounters a potential with a negative gradient, i.e., there is a force on it in the +x direction.

The structure stiffness matrix, akin to the mass stiffness matrix, represents the restoring force on a structure with the mass held constant while allowing the spring junction to move freely The raw value indicates only the nearest spring stiffness (k1), whereas the effective value accounts for the combined stiffness of both springs in series.

The mass matrix

E K = 1 2 àϖ 2 so the mass matrix is just

Basic transfer functions

The dynamics of the pendulum proper can be represented by a frequency-dependent equation of motion matrix

The state-space matrices

Directory structure overview

The most up-to-date version of the triple and quad models and the required support files can be downloaded from http://www.ligo.caltech.edu/~e2e/SUSmodels/

Mathematica packages serve as support files, available in both nb and m formats The nb file acts as the source, including comments, while the m file is the version that gets loaded for use Whenever the nb file is edited, the m file is automatically regenerated to reflect those changes.

• RotationsXYZ.*: A package similar to the standard Mathematica package Geometry`Rotations` except that it uses a yaw, pitch and roll convention for angles. Required directly by the toolkit.

MyShapes.* is a specialized package akin to the standard Mathematica package Graphics`Shapes`, designed to offer improved consistency when using Translate[] and Rotate[] commands While it is essential for all standard models, it remains optional for other applications.

The IFOModel is a Mathematica implementation that encapsulates essential components of the Bench model for a generic LIGO interferometer It includes all necessary physical constants and specific parameters related to the interferometer While it is essential for all standard models, its use remains optional for other applications.

• MatlabExport.*: Utilities to export numbers, numerical vectors and matrices as Matlab ".m" files Required by all the standard models, but otherwise optional.

• StatusWindow.*: Utilities to display progress and timing information in a status window.

To ensure proper functionality, download both versions of each package to a default Mathematica path directory, such as ~/Library/Mathematica/Applications on Mac OS X, or to another easily accessible location that can be added to the path If using a different directory, remember to register the package directory in the model files as detailed in the following instructions.

The model is distributed in tar, zip, or sit formats, expanding into a directory typically named "current," which includes the model definition file, such as ASUS3ModelDefn.nb This directory, known as the model directory, can be renamed or relocated as long as its path is correctly registered in the model files Inside the model directory, there are subdirectories for various case results, which must remain in the model directory but can be renamed or duplicated to create new cases, provided their new names are also registered in the model files.

Each case subdirectory, such as "default," includes a calculation notebook named ASUS3ModelCalcDefault.nb, along with a "precomputed" subdirectory that stores archived intermediate results for that specific case It is essential to register the subdirectory name in the calculation notebook, as detailed in the following section.

Registering paths in the code

To ensure proper functionality, it's essential to register three key directories: the custom package directory, the model directory, and the case subdirectory for the current case Each case calculation file must include these settings After downloading and unpacking the model files, repeat this process for every case.

1 Go into the case subdirectory and look for a notebook with a name likeASUS3ModelCalcXXX.nb (The XXX part will normally reflect the case subdirectory name, e.g., default -> ASUS3ModelCalcDefault.nb) Open the notebook in Mathematica

2 Check the assignment to modelcase in the Switches section near the beginning It should correspond exactly to the name of the case subdirectory (e.g., “default”).

3 Check the assignment to modeldirectory in the Switches section Check that there is a case in the Switch[] statement corresponding to the value of $System for your version of Mathematica, and if not, create one The value returned for that case should be a string giving an absolute path to the model directory The path string should be in the particular standard syntax for your OS (e.g., slash-delimited for Unix or Mac OS X, colon-delimited for Mac OS 9, etc).

4 Check the assignment to modelsupportdirectory in the Switches section Check that there is a case in the Switch[] statement corresponding to the value of $System for your version of Mathematica, and if not, create one The value returned for that case should be a string giving an absolute path to the directory where you have placed the custom packages PendUtil.* etc The path string should be in the particular standard syntax for your OS.

Triple Model

The triple model is a three-stage pendulum with the structure of the usual GEO triple From the ground it consists of

(i) A support structure (taken to be immovable except for the purpose of transfer functions).

(ii) Two “upper” blade springs.

(iii) Two “upper” wires, one per upper blade spring.

(iv) The “upper” mass, a.k.a., mass 1.

(vi) Four “intermediate” wires, one per lower blade spring.

(vii) The “intermediate” mass, a.k.a., mass 2.

(viii) Four “lower” wires (or fibres).

The triple model has evolved through three distinct versions, each featuring variations in the design of the blade springs The “lite” and “xtra-lite” model families, discussed further below, were phased out in two stages.

Quad Model

The quad model is a four stage pendulum with the structure of the conceptual design for the test mass suspension in Advanced LIGO From the ground it consists of

(i) A support structure (not modelled as movable except for the purpose of transfer functions).

(ii) Two “upper” blade springs.

(iii) Two “upper” wires, one per upper blade spring.

(iv) The “top” mass, a.k.a mass 0 or mass N (“N” = new, relative to the triple masses) (v) Two “intermediate” blade springs.

(vi) Four wires, two per intermediate blade spring.

(vii) The “upper” mass, a.k.a., mass 1.

(viii) Two “lower” blade springs.

(ix) Four “intermediate” wires, two per lower blade spring.

(xi) Four “lower” wires (or fibres).

A significant distinction between the quad and triple configurations is that the quad features only two blades at the intermediate and lower levels, each equipped with two wires connected to the tip of its spring In contrast, the triple configuration includes four blades at the lower level, with a single wire for each spring throughout the design.

5.3 “Lite”, “Xtra-Lite” and “Xtra-Lite Lateral” Versions of the Triple and Quad Models

In the initial designs of the triple and quad models, each blade spring was modeled as a 6-DOF mass element linked to its base by a 6-DOF spring, simplifying implementation for early toolkit versions This approach favored the representation of one-dimensional motion through stiff potentials over geometric constraints, which, while increasing matrix sizes, was manageable for frequency domain analysis However, when transitioning to time domain simulations, the models struggled due to high-frequency eigenmodes at the blade tips requiring very fine time steps Consequently, two simplified versions of each model were developed to enhance performance.

The "lite" version of each model restricts the movement of each blade tip to five degrees of freedom (DOFs), maintaining one independent DOF This design minimizes the total DOFs to 24 for the triple model and 30 for the quad model, resulting in smaller matrices However, the eigenmode frequency of a blade tip in its operational direction remains relatively high due to the compliance of the blade and the rigidity of the attached wire Consequently, the lite models are still only marginally suitable for time domain simulations.

The "xtra-lite" versions eliminate blade tip objects completely, maintaining a coordinate at the junction of the spring and wire without any mass or moment of inertia (MOI) This absence of inertia allows for the assumption that it tracks the force and torque equilibrium point between the blade and wire, enabling its exclusion from normal mode analysis This functionality is supported by the floats feature introduced in version 1.6 of the toolkit.

During the assembly of the quad suspension controls prototype, it was found that the lateral compliance of the blades in the upper masses significantly impacts the fundamental pitch frequency, potentially leading to instability Refer to T050255-07, T050172-00, and T050257-01 for further details.

To enhance performance, additional degrees of freedom (DOFs) for the lateral positions of the blades were introduced, leading to the quad xtra-lite lateral model becoming the preferred choice for quad suspension Although a triple xtra-lite lateral model exists, the lateral compliance effect is not significant for the mode-cleaner triple, making the standard xtra-lite version more common However, this effect may gain importance with the larger beamsplitter triple, highlighting the relevance of the lateral model.

Recent advancements have led to the extension of several quad and triple versions by segmenting the lowest wires into six parts and incorporating mass beads between these segments This innovative approach generates five distinct violin modes for each wire, applicable to both longitudinal and transverse displacements relative to the optic axis Notably, the first three modes exhibit acceptable harmonic characteristics, making them valuable for investigating violin mode thermal noise and coupling effects.

To familiarize yourself with the software, begin by loading one of the predefined cases available in the case subdirectory, such as the default values in the 'default' folder Open the calculation notebook named ASUS3ModelCalcDefault.nb to explore the plotting and analysis functions.

Computing cases from scratch versus using precomputed results

To optimize calculation time, each case's calculation notebook is designed to save intermediate results in a designated precomputed subdirectory By setting the useprecomputed switch to True at the beginning of the notebook, users can load archived results instead of recalculating them from scratch Each provided case includes a corresponding set of precomputed results To access these results, ensure the precomputed switch is enabled in the Switches section and evaluate the entire notebook This process makes all key results available in the workspace, allowing for further analysis and plotting based on existing examples.

Stages of the calculation

Because some parts of the calculation are time consuming and not always of interest, the calculation is divided up into stages as follows

In Stage 0A, potential terms for gravity, spring elements, and longitudinal wire-stretching are generated, followed by minimization to find the equilibrium position; wire bending terms can also be included as of toolkit version 2.5 Kinetic energy is processed to create the mass matrix, while potential terms yield stiffness matrices, leading to a preliminary normal mode calculation The key outcomes include eigenvalues0A, a descending list of eigenvalues, eigenvectors0A, corresponding eigenvectors, and Hz0A, which converts eigenvalues to frequencies in Hz This stage, taking only a few minutes, provides a good approximation of mode shapes and frequencies However, the stiffness matrices do not account for dissipation dilution, resulting in no valid calculations for damping, transfer function, or thermal noise information Additionally, mode shapes and frequencies may be slightly inaccurate if any damping function has a real part that deviates from 1 at zero frequency.

In Stage 0B, the potential terms for spring elements and longitudinal wire-stretching are recalibrated with static forces set to zero The unstretched length of wires is temporarily adjusted to the equilibrium position, while the preload for springs is also set to zero The remaining stiffness arises from first-order length changes in wires and springs, contributing to damping and thermal noise The stiffness that was previously present in Stage 0A, attributed to static forces through a variable mechanical advantage, is now incorporated into the gravity stiffness matrix, which is reinterpreted as the stiffness matrix for lossless restoring forces Although the resulting damping calculations are limited, as they do not account for wire bending elasticity, they still accurately represent the losses from the included elastic sources.

The equation of motion function, referred to as eom0, characterizes the dynamics of a pendulum by taking a numerical frequency input It outputs a complex matrix that transforms a vector of generalized force inputs into a corresponding vector of generalized displacement outputs.

The coupling function, known as coupling0, characterizes the interaction between the support and the pendulum By accepting a numerical frequency value, it generates a complex matrix that transforms a vector of displacement inputs from the support into a corresponding vector of generalized forces acting on the pendulum.

A simple one-wire pendulum exemplifies a restoring force influenced by variable mechanical advantage Contrary to the common belief that gravitational force causes dissipation dilution, it is actually the sideways component of the wire's tension that serves as the restoring force, as gravity acts directly downwards The mechanical advantage allows the tension to affect the sideways force on the mass, which varies with the wire's angle Despite the wire's potential for longitudinal loss, it does not significantly impact the pendulum's performance during small amplitude oscillations, as there are no first-order changes in tension or length The wire's contribution to loss primarily arises from the damping associated with the small restoring force that resists bending at the flexure point.

Gravity being lossless is misleading; alternative methods of applying static tension to a wire, without first-order length changes, yield similar dissipation dilution For instance, a bead placed at the center of a taut wire acts like a pendulum, where gravity is substituted by a second wire, demonstrating effective dissipation dilution Similarly, the modes of taut violin strings exhibit dissipation dilution due to the sideways component of the tension serving as the restoring force.

In Stage 1A, the potential terms for wire torsion are incorporated into the analysis, yielding results similar to those in Stage 0 However, the output is distinguished by the suffix “1,” resulting in updated identifiers such as eigenvalues1A, eigenvectors1A, Hz1A, and eom1A.

In Stage 1B, the potential terms for wire bending are processed and integrated, typically requiring a few hours, which highlights the advantage of precomputed results The outcomes mirror those of Stage 0, but the symbol names are suffixed with “1,” resulting in eigenvalues1, eigenvectors1, Hz1, eom1, and more Additionally, thermal noise plots derived from these results serve as effective approximations.

In Stage 2, we incorporate the potential terms for the minor longitudinal stretch caused by wire bending The outcomes mirror those of Stage 0, with the results now denoted as eigenvalues2, eigenvectors2, and so on This stage requires a few additional hours to complete, but it is often deemed unnecessary due to the minimal impact of the effect.

The Calculate[] function enforces the order of calculations by computing all results dependent on a specified symbol before calculating the symbol itself For instance, invoking Calculate[stage] for any of the stages—Stage0A, Stage0B, Stage1, or Stage2—will generate all relevant results for that stage These function calls are strategically integrated into the sample case notebooks to ensure that necessary results are preloaded prior to the execution of example analysis commands Further details about the Calculate[] function can be found in the section discussing the model's calculations.

Available listing and plotting commands

Frequencies

The frequencies can be accessed through the variable Hz0A, which includes options like Hz0, Hz1, or Hz2 To efficiently identify the interesting low-frequency modes, particularly the second lowest frequency, you can use Mathematica’s syntax to count from the end of the array, denoted as Hz0A[[-2]].

Mode shape tables

Eigenvectors are identified in the eigenvectors0A series, where the order aligns with the corresponding frequencies in Hz0A For instance, eigenvectors0A[[-2]] represents the second lowest frequency eigenvector The coefficients within each vector are ordered according to allvars, with allvars[[-6]] denoting x3, the x-coordinate of the optic Therefore, eigenvectors0A[[-2]][[-6]] indicates the amplitude of x3.

Eigenvectors can be displayed in an organized table format with the function pretty[] To enhance clarity, it is beneficial to utilize Chop[] to eliminate insignificant values Additionally, premultiplying by the matrix e2ni allows for the conversion of the eigenvector into laboratory yaw, pitch, and roll coordinates For example, using pretty[Chop[e2ni.eigenvectors0A[[-2]], 10^-4]] yields a clear representation of the results.

Mode shape plots

To obtain a 3D rendering of a normal mode, use the eigenplot function with the syntax eigenplot[eigenvector, amplitude, {viewpoint}] For xtra-lite triple and quad models, and other models with a non-zero number of float coordinates, include an additional floatmatrix argument at the end It is essential to select the amplitude parameter through trial and error to ensure the mode shape is clear yet undistorted, with typical values ranging from 0.1 to 0.5 Additionally, the viewpoint should be carefully chosen; for instance, using eigenplot[eigenvectors0A[[-2]], 5, {0, -2, 0}] will yield a visually informative result.

Force transfer function plots

To calculate and visualize transfer functions from generalized force to displacement in a pendulum system, utilize the functions calcTFf[eom, ivec, ovec, f] and plotTFf[eom, ivec, ovec, f1, f2] Here, eom represents the equations of motion, ivec is the vector of generalized force inputs, ovec denotes the vector of displacement outputs, and f, f1, and f2 are numeric frequencies Construct force input basis vectors with makefinputvector[symbol], which generates a vector for unit force or torque applied to the specified pendulum coordinate For instance, makefinputvector[yaw3] represents unit torque in yaw on the optic Similarly, output basis vectors can be created using makeoutputvector[symbol].

Displacement transfer function plots

To calculate and plot transfer functions from the support's displacement to the pendulum's displacement, utilize the functions calcTF[eom, ivec, ovec, f] and plotTF[eom, ivec, ovec, f1, f2] Here, eom refers to the equation-of-motion functions, while ivec and ovec represent the vectors for generalized displacement inputs and outputs, respectively The parameters f, f1, and f2 denote numeric frequencies For constructing displacement input basis vectors, the function makeinputvector[symbol] can be employed, which generates a vector for unit force or torque applied to the specified support coordinate For instance, makeinputvector[x00] corresponds to a unit x displacement of the support.

Thermal noise plots

To calculate and plot thermal noise, use the functions noise2[eomfn, iovec, f] and plotTN[eomfn, iovec, f1, f2, scale] Here, eomfn represents an equation-of-motion function, iovec is an input/output vector, and f, f1, and f2 are numeric frequencies, while scale is a scale factor The input/output vector can be created using either makefinputvector[] or makeoutputvector[], both of which serve the same purpose This vector symbolizes an ideal frictionless mechanism that moves a point based on a specified linear combination of coordinates The thermal noise measured corresponds to the thermal noise of the notional output point of this mechanism, with the temperature assumed based on the substitution provided for the symbol temperature in defaultvalues or overrides.

Default numerical values

Each model is equipped with a predefined set of property values represented as Mathematica substitution rules in a list known as "defaultvalues." For the triple model, these default values include gravitational acceleration (g) set at 9.8, and the variables ux, uy, and uz assigned values of 0.1, 0.3, and 0.07, respectively Additionally, the density (den1) is defined as 2700, while the mass (m1) is calculated using the formula m1 = den1 * ux * uy * uz.

The complete, annotated version of this list is available in the model definition file, while the model's calculations using the default values are located in the default subdirectory.

To enhance version control, users should modify default parameters in a separate calculation notebook rather than altering the model definition notebook This approach involves supplying a list of additional substitutions that override the default values, which can be easily added to the predefined list of overrides at the beginning of the calculation notebook The following sections will detail the mechanics of this process.

Creating new cases of the existing models

To create a new case with new numeric values for the properties of the pendulum, proceed as follows:

(i) Duplicate one of the existing case subdirectories, such as default Give the new subdirectory a name reflecting the combination of properties to be tried, such as heavieroptic.

Rename the calculation notebook in the new subdirectory to include a fragment of the subdirectory name, such as ASUS3ModelCalcHO.nb While the specific name is not crucial, ensuring it is unique can be beneficial if you have multiple notebooks open simultaneously.

(iii) Delete all the files in the precomputed subdirectory within the new case directory.

In the Switches section of the calculation notebook, locate the assignment for modelcase and modify the right-hand side (RHS) to match the case subdirectory name precisely, such as “heavieroptic”.

To implement the new case, locate the assignment to overrides in the Switches section and modify it to include the necessary overriding substitutions, such as changing m3 to 50 to set the optic mass to 50 kg Ensure to add clear comments in this section and at the top of the file to explain the changes made Additionally, find the assignment to precomputed in the Switches section and set the RHS to False.

(vii) Evaluate the whole notebook.

(viii) Edit the RHS of the assignment to precomputed back to True.

Using overrides

To achieve numeric values for all properties, you can use substitutions with non-numeric right-hand sides in overrides The old substitutions from defaultvalues and your new overrides are combined and processed recursively, applying substitutions to each other until they ideally result in numeric values, known as constval It is essential that any symbols on the right-hand side of your substitutions have corresponding definitions in overrides or defaultvalues, ensuring that recursive substitution chains conclude with numeric values after a finite number of steps For instance, the substitution a->b followed by b->1 is valid, while a->b and b->a would create an infinite loop, and a->b with b->c would fail if a numeric value is needed for a, b, or c The order of substitutions is not critical, so b->1 and a->b is also acceptable.

The relationship between mass (m1) and moments of inertia (I1x, I1y, I1z) is one-way, meaning they are initially calculated based on density (den1) and dimensions (ux, uy, uz) using standard block formulas While these values can be manually overridden with specific figures from a CAD program for normal mode calculations, this action severs the link to the original density and size parameters Consequently, if no further adjustments are made, the mass and moments of inertia will revert to their initial, potentially inconsistent values.

Overrides can be applied using the format symbol -> scale[factor] or symbol -> increment[difference], allowing for adjustments to default values rather than complete replacements For instance, using m3->scale[2.0] will effectively double the mass of the optic.

7 The definition of the model

To implement significant changes or create entirely new asymmetric models, a comprehensive understanding of the definition and calculation code is essential This section provides a detailed walkthrough of the code in the definition notebook, highlighting the crucial elements that model writers must provide to successfully define a new model.

Version History

To ensure accurate model loading, specify the model type and version by assigning a descriptive text to 'modelcomment' and a numeric version number to 'modelversion' in the Version history section at the beginning of the file The calculation notebook verifies these values to confirm the correct model is in use Additionally, for each new version, include a text cell detailing the changes made since the previous version.

Preliminaries

The Preliminaries section loads the toolkit package and any other packages that may be necessary. Most models will require all of the following:

• PendUtil` (the pendulum toolkit utilities)

• Graphics`Graphics` (standard package for general graphics)

• Graphics`Polyhedra` (standard package for drawing polyhedra)

• LinearAlgebra`MatrixManipulation` (standard package for matrix manipulation)

• RotationsXYZ` (custom package for rotations in yaw, pitch and roll)

• MyShapes` (custom package similar to Graphics`Shapes` but with rotation bug fixed)

• StatusWindow` (custom package to display text messages in a status window)

The model definition proper

The master variable list: allvars

The variable list, referred to as allvars, represents the coordinates defining the state of the pendulum for normal mode calculations This list includes various parameters for the triple model, organized in a logical and memorable order The variables encompass positions and orientations, such as x, y, z coordinates, along with yaw, pitch, and roll values for different components, including upper left, upper right, lower left, and lower right sections, as well as additional states denoted by x1, x2, and x3.

The list of “floats”

The symbol allfloats represents the vector q, as discussed in the theory section It should consist of the coordinates of junctions between massless elastic elements, with no moment of inertia (MOI) linked to them If allfloats is not specified, it defaults to an empty list Notably, there are no defined floats in the complete triple or quad models; for an example, refer to one of the "xtralite" models.

The parameter list: allparams

In the context of the theory discussed, the symbol allparams represents the vector s and is defined as a list of parameters that remain constant during normal mode calculations but vary for displacement-input transfer functions For the current models, this includes the six coordinates of the structure, but additional coordinates of nearby objects can also be included if their displacement effects on the pendulum are of interest For the triple model, the parameter list is specified as allparams = { x00, y00, z00, yaw00, pitch00, roll00 }.

Coordinate lists for rigid bodies and points on them

For improved readability, it's essential to assign names to the coordinate lists that represent each rigid body These names must follow the required format for geometry functions, which consists of six coordinates arranged in the order of x, y, z, yaw, pitch, and roll For instance, in the triple model, the optic can be defined as optic = {x3, y3, z3, yaw3, pitch3, roll3}.

The elements in the list can include both symbols from allvars and constants from defaultvalues For instance, the expression constrainedbody = {l Sin[theta], l Cos[theta], 0, 0, 0, 0}; illustrates a rigid body that is constrained to move without rotation along a line at a fixed angle theta relative to the x-axis In this case, the variable l must be included in allvars, while the constant theta should be defined in defaultvalues.

When defining points of interest on rigid bodies, it is essential to represent them as lists of local coordinates in the x, y, and z axes For instance, in the case of a triple pendulum, the left wire-attachment point on the upper mass can be denoted as massUl={0, -n1, d0}.

Typically the user will also want to define coordinate lists for static objects For example, in the triple model the support structure is support = {x00, y00, z00, yaw00, pitch00, roll00};

(This happens to be the same list as allparams, but is conceptually different in that the order and interpretation of items in allparams is not important.)

Items with gravitational potential energy: gravlist

To effectively manage the potential terms associated with gravity, they should be organized into a designated list known as "gravlist." The initialization of this list, along with the addition of a term representing the potential energy of the optic, is accomplished through a specific code fragment from the triple model, as demonstrated by the line: gravlist = {};

(Building up a list with AppendTo[] is overkill for something so simple but it’s good practice for the more complicated structures to come There it makes things rather more readable.)

Wires: wirelist

The various wires in the model are specified in a list called wirelist Each entry in wirelist describes a single wire and has the following format:

The article outlines the essential components for defining two masses in a system It includes a coordinate list for the first mass, specifying its attachment point in local coordinates and the corresponding attachment vector Similarly, it provides a coordinate list for the second mass, detailing its attachment point in local coordinates and its attachment vector.

Young's modulus is a fundamental property that describes the longitudinal elasticity of materials, defined by the ratio of stress to strain in the elastic region It is crucial to consider the unstretched length of a material when analyzing its elastic behavior The principal axes, particularly axis 1, play a significant role in determining the moment of area, which is essential for understanding the material's response to various loading conditions In addition to linear elasticity, materials also exhibit angular and torsional elasticity, which are governed by the shear modulus and the cross-sectional area used in torsional calculations The torsional stiffness geometric factor further influences the material's ability to withstand twisting forces, making it vital for engineering applications.

To ensure backward compatibility for models created prior to the introduction of torsion support, the last four items are optional for each wire Each wire connects two rigid bodies, with items 1 and 4 representing the coordinate lists for these bodies, which can either be massive, utilizing variables from allvars, or massless, using coordinates from allfloats Items 2 and 5 denote the attachment points in body coordinates, while items 3 and 6 provide local coordinate vectors that indicate the angle of attachment for the wires For instance, in a simple pendulum, the vectors would be {0,0,-1} (down) at the top and {0,0,1} (up) at the bottom Notably, if a three-item list is not used in these positions, the calculation disregards it and instead determines the necessary vector to ensure the wire remains straight when the pendulum reaches equilibrium.

Items 7 and 8 are obvious: the Young’s modulus for the wire and the unstretched length.

Item 9 is the elasticity of the wire considered as a longitudinal spring The reason for having the user work this out manually, rather than taking the cross-sectional area as a parameter, is to allow for the case where the area varies along the length of a fibre.

Items 10-12 relate to the bending of the wire near the endpoints The wire is allowed to have an oblong cross-section with different rigidities along different axes Item 10 is a vector in local coordinates specifying the axis along which the rigidity is maximum, Item 11 is the moment of area along that axis, and Item 12 is the moment of area along the axis at right angles.

Items 13, 14, and 15 serve as identifiers for the damping functions associated with longitudinal, bending, and torsional elasticities Each damping function must be defined as a substitution in the default values; if no specification is provided, the default settings will be 1 for the real part and 0 for the imaginary part.

In the triple model, initializing wirelist and adding a definition for the wire from the top left blade spring to the upper mass looks like this: wirelist = {};

AppendTo[wirelist,{ bladeUL, bladeULa, bladeULavec, massU, massUl, massUlvec, Y1, ul1,kw1,{1,0,0},

Springs: springlist

The elastic elements in the model other than wires are specified in springlist Note that a

“spring” element only models elasticity To model the mass of a physical spring as well requires a separate rigid body element.)

Each entry in springlist describes a single spring element and has the following format:

The article outlines the essential parameters for two masses in a mechanical system, including the coordinate lists that define each mass It specifies the local coordinates for the attachment points of both the first and second masses, along with their corresponding attachment angles, which are defined by yaw, pitch, and roll Additionally, the article addresses the type of damping used in the system, ensuring a comprehensive understanding of the configuration and dynamics involved.

1*6 pre-load force/torque vector

Items 1–6 outline the properties of wires and the connection points of the spring, with a key distinction: while wires use a vector to define attachment angles, springs require a more complex specification involving yaw, pitch, and roll angles This three-angle approach, although more comprehensive and refined, complicates the calculations for wire-bending elasticity The spring operates within its own x/y/z coordinate system, and the attachment angles indicate the necessary rotations to position the spring correctly from its initial alignment with the mass's coordinate system.

Item 7 is a symbol specifying a damping function, as for the wires.

Item 8 is a 6x6 elasticity matrix giving elastic constants with respect to differential displacements in the spring local coordinate system.

Item 9 is a vector giving the amount of preload force or torque in the spring x, y, z, yaw, pitch and roll directions when the attachment points on the two masses are coincident and aligned according to the attachment angles.

The following fragment from the triple model shows the entry for the upper left blade spring being added to the list: springlist = {};

AppendTo[springlist, { support, bladeULnom, {0,pitchbul,rollbul}, bladeUL,

DiagonalMatrix[{kbux,kbuy,kbuz,kbyawu,kbpitchu,kbrollu}], {0,0,bdu*kbuz,0,0,0}

The kinetic energy: kinetic

To enhance the readability of kinetic energy specifications, it is beneficial to organize the moment-of-inertia constants into tensors, as demonstrated in the triple model for optics.

To express kinetic energy in Mathematica, use total derivatives of the variables with respect to time (t) and assign it to the symbol "kinetic." While this process may not be user-friendly, it is essential for accurate calculations For reference, follow the pattern demonstrated in the kinetic energy term for the upper mass (massU) in the triple model: kinetic = (

… +(1/2) m3 Plus@@(Dt[b2s[optic,COM],t]^2) +(1/2) omegaB[yaw3, pitch3, roll3].IM3.omegaB[yaw3, pitch3, roll3]

In Mathematica, the shortcut Plus@@(vector)^2 efficiently sums the squares of elements, while Dt[coordinate, t] represents the total time derivative The function b2s[object, point] provides the coordinates of a specific local point on an object Additionally, the center of mass, denoted as COM and defined as {0,0,0}, serves as the reference point in local coordinates for any body Lastly, omegaB[] indicates the angular velocity vector associated with the system.

Values of constants: defaultvalues

The defaultvalues list includes substitutions for the pendulum's properties, specifically targeting all non-variable elements, which are not coordinates associated with normal modes In addition to the pendulum's inherent characteristics, this list must also encompass substitutions for specific constants related to the system.

• temperature (temperature, for the thermal noise calculations)

• boltzmann (Boltzmann’s constant, for the thermal noise calculations)

Second, it should contain substitutions for the usual static values of the “parameters” (i.e., the coordinates of the structure or other objects involved only in transfer functions).

The function call constraintsubstitutions[] generates a list of substitutions formatted as kconvariablename -> 0 for each variable in allvars, representing elastic forces that connect each degree of freedom (DOF) to mechanical ground Although additional potential terms associated with these constants are created in the calculation notebook, they typically have no impact since the constants default to zero For debugging, however, you can adjust specific constraint elasticities to higher values to restrict the movement of certain parts of the pendulum.

In the context of defining frequency-dependent elasticity and damping for potential terms, substitutions such as damping[real,dampingtype] -> (function&) and damping[imag,dampingtype] -> (function&) are utilized Here, the & operator denotes a pure function in Mathematica, which is an unnamed function operation The arguments are represented as #1, #2, etc., and the parentheses around the pure function are necessary due to the lower precedence of the & operator compared to the -> operator These functions must accept frequency values in Hz and return a multiplier for the real or imaginary component of complex elasticity, relative to the purely real elasticity defined by the potential If no substitutions are provided for damping[real,dampingtype] or damping[imag,dampingtype] in defaultvalues, they default to damping[real,dampingtype] -> (1&) and damping[imag,dampingtype] -> (0&), indicating frequency-independent elasticity without damping Typically, unless there are concerns regarding the Kramers-Kronig relationship or large loss angles, the default for the real part can be used, allowing for specification of only the imaginary component Structural damping can be defined as damping[imag,dampingtype] -> (phi&), while velocity-proportional damping is expressed as damping[imag,dampingtype] -> (2*Pi*b*#/k&), where b represents the damping in N/(m/s) relative to the elasticity of k N/m.

Approximation to equilibrium position: startpos

The startpos list should contain substitutions for the variables in allvars, aiming to achieve an approximate equilibrium state for the system This serves as a foundation for determining the precise equilibrium through numerical minimization of the potential Additionally, the substitutions may include symbols on the right-hand side, as long as corresponding substitutions exist in defaultvalues.

Extra potential terms for debugging: preeqtermlist and posteqtermlist

In the model case notebook, a preeqtermlist can be defined as a collection of {potentialterm, dampingtype} pairs to alter the model's default structure These terms are incorporated into the main potential prior to determining the equilibrium position, and the potential expressions in the preeqtermlist are evaluated twice, utilizing the tensionoffswitch.

>False and once with tensionoffswitch->True If a particular term has a component representing astatic tension, it should be zeroed out in the latter case.

In the model case notebook, the posteqtermlist can be defined as a list of {potentialterm, dampingtype} pairs to alter the model's default structure These terms are incorporated into the main potential after determining the equilibrium position, similar to constraint forces For the equilibrium position to be valid, any static forces represented must balance out The equilibrium position can be accessed using expressions like allvars[[i]]/.optval/.nonoptval To avoid premature evaluation errors from optval and nonoptval, it is advisable to define posteqtermlist using the := operator.

In the evaluation process, the expressions in preeqtermlist and posteqtermlist will be assessed two times: first with tensionoffswitch set to False and then with it set to True It is essential to note that if any term includes a component indicating a static tension, it must be zeroed out during the second evaluation.

Model dependent diagnostic utilities

Angular velocity transformation matrices: e2s, e2b and e2ni

The coefficients associated with angle variables in raw eigenvectors are not presented in a convenient basis, as they denote infinitesimal increments in yaw, pitch, and roll angles during normal mode motion Due to non-linearity and non-commutativity, the transition from (yaw, pitch, roll) to (yaw+dyaw, pitch+dpitch, roll+droll) differs from the increments (dyaw, dpitch, droll), except when yaw, pitch, and roll are all zero Additionally, the rotations represented in (yaw+dyaw, pitch+dpitch, roll+droll) do not occur around mutually orthogonal axes under the same conditions To address this, the toolkit offers transformation matrices that convert eigenvector coefficients into more practical forms, such as "space" coordinates, which utilize infinitesimal rotations around the global x, y, and z axes This conversion is particularly beneficial for interpreting normal mode motion as angular velocity, facilitated by the 3x3 matrix function omegaIS[].

Body coordinates utilize infinitesimal rotations around the object's x, y, and z axes, making them valuable when used alongside the moment of inertia (MOI) tensor, which is inherently defined in body coordinates These rotations can be computed using the formula omegaIB[yaw, pitch, roll].{dyaw, dpitch, droll}.

Non-incremental yaw, pitch, and roll coordinates are based on infinitesimal rotations around the z, y, and x axes This approach effectively permutes the space coordinates, represented as omegaSNI.omegaIS[yaw, pitch, roll].{dyaw, dpitch, droll}, where omegaSNI is defined as {{0,0,1},{0,1,0},{1,0,0}}.

The provided utilities are limited to the angle variables of a single object at a time, leaving the user responsible for creating matrices such as e2b, e2s, and e2ni to process an entire eigenvector simultaneously This requires the user to construct the matrices following specific guidelines, such as using the DiagonalBlockMatrix function.

The article discusses the use of IdentityMatrix[3] in conjunction with omegaSNI.omegaIS for various yaw, pitch, and roll parameters, including yawul, pitchul, rollul, yawur, pitchur, rollur, yaw1, pitch1, roll1, yawllf, pitchllf, rollllf, yawllb, pitchllb, rollllb, yawlrf, pitchlrf, rolllrf, yawlrb, pitchlrb, rolllrb, yaw2, pitch2, roll2, yaw3, pitch3, and roll3 This combination highlights the importance of rotational transformations in three-dimensional space.

Plotting routines: eigenplot[]

To create 3D visualizations of normal modes, a customized version of the eigenplot routine is necessary, utilizing the existing models as a template These models employ the MyShapes` package, which offers enhancements over the standard Graphics`Shapes` package for this specific purpose The toolkit function tosub[eigenvector] converts displacements from the eigenvector into absolute values through a list of substitutions Since eigenvectors primarily define variable behavior, an additional argument, floatmatrix, is required in the eigenplot[] function when floats are defined and objects dependent on them need to be plotted By calling tosub[eigenvector,floatmatrix], substitutions for both floats and variables are generated effectively.

Note that eigenvectors should not be processed with e2ni before being given to eigenplot[].

Listing routines: pretty[]

To effectively display eigenvectors, a customized version of the routine pretty[eigenvector] should be created to present the coefficients in a structured table format with appropriate headings While it is often beneficial for users to process eigenvectors using e2ni prior to listing, this step should ultimately be at the discretion of the end-user instead of being automatically integrated into the pretty[] function.

Input and output vectors

For effective utilization of transfer function routines, it's essential to have input and output vectors for relevant coordinates, including those of the structure and final payload The toolkit provides convenient functions such as makeinputvector[parameter], makefinputvector[variable], and makeoutputvector[variable] to simplify this process.

8 The calculation of the model

The Calculate[] function

The Calculate[] function is primarily utilized to compute or load results for an entire stage simultaneously It operates on any symbol that represents standard intermediate or final results A typical definition of the Calculate[] function includes clauses that reflect this functionality.

Status["Computing symbol"]; code to compute symbol; saveprecomputed["symbol.m", symbol];

• Before attempting to compute or load the requested symbol, Calculate[] calls itself recursively to compute or load all the symbols on which the requested one depends.

• If the switch useprecomputed is True, Calculate[] attempts to load an archived value for the symbol from the precomputed subdirectory within the case directory.

The condition "exceptdamping" is excluded from the clauses for result symbols that are independent of the frequency dependence of elasticity, particularly in the case of potential matrices By enabling both useprecomputed and exceptdamping to True, users can investigate the impacts of varying magnitudes and frequency dependencies of damping efficiently, avoiding unnecessary recalculations.

Recursion affects the computation of intermediate results in a specific order, which is crucial for debugging new models To identify errors in stages, manually call Calculate[] on each result symbol sequentially It's important to note that Calculate[] does not impact symbols that are already loaded To recalculate after correcting an error, use Clear[symbol] or, for an entire stage, employ Reset[stage] (e.g., Stage0A).

Stage 0A – normal modes without wire bending elasticity

Numerical Substitutions: constval

The seminumeric substitutions in defaultvalues and overrides are merged usingOverride[] and then processed using Recurse[] to propagate the numeric values throughout,producing a list called constval.

Numerical start position for minimization of the potential: startval

The starting position startpos suggested by the model writer is converted to fully numeric form called startval by processing with constval.

Coordinates that don’t participate in the minimization: nonoptcoords and nonoptval

To effectively minimize potential, it is essential to consider all variables and floats in the lists allvars and allfloats, while excluding those in the nonoptcoords list for debugging purposes This exclusion aids in identifying issues related to wire and spring specifications During the minimization process, the variables in nonoptcoords are fixed to the values in startval Additionally, the list nonoptval serves as a subset of startval, containing substitutions exclusively for the variables in nonoptcoords.

Variables that participate in the minimization: optcoords

The list optcoords is set to the complement of nonoptcoords with respect to allvars and allfloats (For backward compatibility, nonoptvars is also accepted but this is deprecated.)

The base list of potential terms for the minimization: potentialtermlist

The default set of potential terms that are to be considered in the minimization are assembled into a list together with their damping tags: potentialtermlist = {{term,tag},{term,tag},…}

The comprehensive list comprises terms generated from gravlist and springlist, along with terms for simple longitudinal wire extension from wirelist, and any additional terms manually defined in preeqtermlist Initially, this constituted the complete list; however, starting with version 2.5 of the toolkit, it can now be enhanced with optional extra wire terms, as detailed in the following section.

Additional wire terms for the minimization: potentialtermlistWBnr, potentialtermlistWTnr, potentialtermlistWEnr

In version 2.5 of the toolkit, setting wiretermsearly to True or EqOnly—either directly or through constval substitution—enables the accumulation of wire potential terms for bending and torsion These terms are collected in the lists potentialtermlistWBnr for bending, potentialtermlistWTnr for torsion, and potentialtermlistWEnr for extra longitudinal extension.

Certain calculations may be unfeasible due to the feature that wire attachment angles, designated as dummy symbols, are determined post-minimization to ensure the associated wires are straight at equilibrium Bending terms can only be computed for endpoints with explicitly provided wire attachment angles, while torsion terms require explicit angles for both endpoints Any calculations that do not satisfy these conditions will be postponed to Stages 1 or 2, as previously established.

The full expression for the potential: potential

The total potential is calculated by combining terms from potentialtermlist with those from potentialtermlistWBnr, potentialtermlistWTnr, and potentialtermlistWEnr This combination is then multiplied by the real part of the damping multiplier evaluated at frequency f=0 (damping[real,dampingtype][0]) and summed to create a unified expression for the total potential.

The numeric potential: potentialNN

The symbolic expression for the potential is processed with constval and nonoptval to produce potentialNN, an expression containing only the coordinates in optcoords.

The minimization: potential0 and optval

The minimization gives potential0, the value of the potential at the minimum, and optvals, a specification of the minimum as a list of substitutions for the variables in optcoords.

Velocity variables: velocities

A list of velocity names is created by adding “v” to all the variable names in allvars.

The kinetic energy matrix: kineticN and kineticmatrix

Kinetic energy is expressed using symbolic constants and variables, along with their total time derivatives By substituting time derivatives with velocity variables and utilizing constval, optval, and nonoptval to eliminate extraneous symbols, we derive kineticN Subsequently, we calculate partial derivatives for all pairs of velocity variables to create the kineticmatrix.

The potential used for the normal mode calculation: potentialtermlist0

Additional items in the form of {constraintterm, constrainttype} are incorporated into the potentialtermlist to create potentialtermlist0 These extra terms symbolize elastic forces that connect the different degrees of freedom (DOFs) to the equilibrium position established in the prior step Additionally, manually defined terms from posteqtermlist are included at this stage.

As of toolkit v2.5, if wiretermsearly is defined to be True (but not EqOnly), either directly or as a substitution in constval, any terms in potentialtermlistWBnr,potentialtermlistWTnr or potentialtermlistWEnr are appended.

The Stage 0A damping-specific potential matrices: potentialmatrices0T

The potential term components from potentialtermlist0 are analyzed concerning variables, floats, and parameters to create specific damping-related potential matrices for each T i Matrices sharing the same damping tags are merged, resulting in the final list potentialmatrices0T formatted as {{dampingtype, matrix}, {dampingtype, matrix},…} Notably, the damping tag is positioned first in this instance It is important to handle these potential matrices carefully at this stage, as they have not been adjusted for dissipation dilution.

The Stage 0 potential matrix: potentialmatrix0

The individual potential matrices in potentialmatrices0T are multiplied by the real part of the complex elasticity multiplier evaluated at f=0 (damping[real, dampingtype][0]) and summed to produce a net stiffness matrix.

The Stage 0 normal modes: eigenvalues0, eigenvectors0 and Hz0

The potential and kinetic energy matrices are simultaneously diagonalized to obtain eigenvalues and eigenvectors The eigenvalues, expressed in (rad/s)², are subsequently converted to Hertz (Hz) to yield the final results.

Stage 0B – damping without wire bending elasticity

Potential matrices without tension: potentialmatrices0NT

The potential matrix calculation from stage 0A is repeated with wire tension and spring preload set to zero, resulting in potentialmatrices0NT This matrix, along with potentialmatrices0T, is analyzed by dissipationdilution[], which correlates them to identify the elasticity components responsible for damping, ultimately generating a new list of potentialmatrices0.

The equations of motion function and the coupling function: eom0 and coupling0

These are calculated from kineticmatrix and potentialmatrices0 Thus they neglect wire bending elasticity but correctly incorporate dissipation dilution on the remaining sources of damping.

Preparation for Stages 1 and 2

Wire angles: relaxval

Wire definitions can include placeholder symbols for attachment angles, which are analyzed to determine the optimal angles based on the pendulum's equilibrium position These calculated values are compiled into a substitution list called relaxval.

Additional potential term lists: potentialtermlistWB and potentialtermlistWE

In preparation for Stages 1 and 2, new terms for wire bending are generated and stored in the lists potentialtermlistWB and potentialtermlistWE, formatted as {{term,tag},…} like potentialtermlist0 The first list, used in Stage 1, focuses on the potential from pure angular bending of the wire, while the second list, utilized in Stage 2, addresses the potential arising from the additional longitudinal stretch of the wire due to its displacement from the straight line between the endpoints defined in Stage 0.

The wire bending phase of the calculation utilizes elasticity theory, originally derived by Mark Barton through Mathematica, based on insights from Matt Husman’s thesis The function wirebendingPE[T, l, EE, I1, I2, alpha1, beta1, alpha2, beta2] calculates the bending potential energy of a wire under tension T, incorporating Young's modulus EE and moments of area I1 and I2 along its principal axes, while being stretched between two points separated by distance l and forming angles alpha1 and alpha2 at one end and beta1 and beta2 at the other.

Similarly, wirebendingdelta[T,l,EE,I1,I2,alpha1,beta1,alpha2,beta2] computes the extra longitudinal extension of the wire due to the curvature of the wire

The code for wire torsion was kindly provided by Ben Lee of the UWA Gravity Group.

The functions wirepotential1[], wirepotential1T[] and wirepotential2[] do the 3D geometry required to apply the above functions to wires at the angles implied by the equilibrium position of the model.

The new terms are tagged based on their corresponding entries in the wirelist, with potentialtermlistWB receiving the bending tag and potentialtermlistWE assigned the stretching tag.

Stage 1A – normal modes and damping with wire bending elasticity

The Stage 1A calculation utilizes entries from potentialtermlistWB, which represent wire lateral bending, to generate potentialmatricesWB These matrices are then combined with potentialmatrices0 to create potentialmatrices1A Following the same processing method as Stage 0, this leads to the production of potentialmatrix1A, eom1A, coupling1A, eigenvalues1A, eigenvectors1A, and Hz1A.

Stage 1B – normal modes and damping with wire torsional elasticity

The Stage 1B calculation processes entries from potentialtermlistWT, which represent torsion, to generate potentialmatricesWT These matrices are then combined with potentialmatrices1A to create potentialmatrices1 Following this, the data undergoes similar processing to yield potentialmatrix1, eom1, coupling1, eigenvalues1, eigenvectors1, and Hz1.

Stage 2 – normal modes and damping with additional wire stretch due to bending

The Stage 2 calculation utilizes the entries from potentialtermlistWE to generate potentialmatricesWE, which are subsequently combined with potentialmatrices1 to create potentialmatrices2 This output is then processed similarly to Stages 0 and 1, resulting in potentialmatrix2, eom2, coupling2, eigenvalues2, eigenvectors2, and Hz2.

Exporting state-space matrices

Building state-space matrices with model results

The PendUtil.nb package offers various functions for creating the A, B, C, and D matrices used in state space representation It includes multiple variants tailored for specific applications, each accommodating different input and output configurations, with function names generally prefixed by ssA, ssB, ssC, and ssD.

The typical inputs consist of displacement inputs related to the structure coordinates in allparams, along with force and torque inputs associated with the variables in allvars The essential outputs include displacements corresponding to the variables in allvars The variant ssC and ssD matrix functions enhance this output by adding forces and torques on the structure that correspond to the coordinates in allparams, which is beneficial for coupling the state spaces of two distinct models, as demonstrated in the accompanying diagram.

The block structure of all four matrices is annotated with the physical interpretation of each block and how it is constructed using the quantities described in Section 2.2.

Exporting state-space matrices

The MatlabExport.nb and E2EExport.nb packages offer utility functions designed for exporting specific quantities to text files compatible with Matlab and the LIGO E2E group's simulation environment, Alfi While the Matlab utilities cater to a broader range of applications, enabling the export of scalars, vectors, and matrices with some support for symbolic results, the E2E routines are tailored specifically for state-space matrices.

Mathematica v6 created four compatibility issues, two easily fixed and two not:

Version 1.1 of the StatusWindow package encountered a critical bug in Mathematica v6, where the status window, previously functioning as a "ModelessDialog" in v4 and v5, became a "MoveableModalDialog," effectively locking users out of the GUI until dismissed This oversight led to a fatal lockup since there was no option to close the window Additionally, some date functions utilized by the package were deprecated and later reintroduced under different names.

All users are advised to upgrade to StatusWindow v1.2 released on June 14, 2007, which is compatible with Mathematica v6.0 and earlier versions down to v4.x This update not only resolves the modal dialog issue but also incorporates version-specific date functions to prevent error messages.

• Several standard packages have been deprecated In particular,

The `LinearAlgebra`MatrixManipulation` package, which includes the BlockMatrix[] function for assembling state-space matrices, has been deprecated, and there appears to be no replacement functionality available While it continues to function for toolkit purposes, users will encounter a bothersome warning message upon loading it.

To ensure optimal performance, all users are advised to upgrade to PendUtil v3.0 and MatlabExport v1.3, released on June 14, 2007 These versions are compatible with Mathematica v6.0 and maintain backward compatibility with v4.x PendUtil now includes a reassuring message prior to loading LinearAlgebra`MatrixManipulation` and prevents the loading of deprecated graphics-related packages if $VersionNumber is 6.0 or higher Additionally, MatlabExport has been updated to avoid loading LinearAlgebra`MatrixManipulation`, which was not utilized in the package.

In earlier versions of Mathematica, drawing commands produced output as a side effect, resulting in a non-printing placeholder This meant that output appeared regardless of the position of drawing commands in a compound expression However, in Mathematica v6, output is now considered the result and only appears if the drawing command is the last in the chain, breaking a commonly used idiom in calculation notebooks.

Status["Plotting mode n"];eigenplot[ ];Done[];