outline for documentation

hovey · hovey · commit 03558214ffa5 · 2025-09-05T17:04:02.000-04:00
diff --git a/documentation/mdbook/src/SUMMARY.md b/documentation/mdbook/src/SUMMARY.md
@@ -1,3 +1,34 @@
 # Summary
 
-- [Chapter 1](./chapter_1.md)
+[Abstract](./abstract.md)
+[Nomenclature](./nomenclature.md)
+[Notation](./notation.md)
+- [Introduction](./chapter_01.md)
+
+-----------
+
+# Part I. Rattlesnake Overview
+
+- [Acquiring and Running Rattlesnake](./chapter_02.md)
+- [Using Rattlesnake](./chapter_03.md)
+
+-----------
+
+# Part II. Rattlesnake Hardware Devices
+
+- [NI-DAQMX Devices](./chapter_04.md)
+- [LAN-XI Devices](./chapter_05.md)
+- [Data Physics Quattro Devices](./chapter_06.md)
+- [Data Physics 900-series Devices](./chapter_07.md)
+- [Virtual Control using State Space Matrices](./chapter_08.md)
+- [Virtual Control using Finite Element Results in Exodus Files](./chapter_09.md)
+- [Virtual Control using SDYNPY System Objects](./chapter_10.md)
+- [Implementing New Hardward Devices with Rattlesnake](./chapter_11.md)
+
+-----------
+
+# Part III. Rattlesnake Environments
+
+-----------
+
+[Contributors](contributors.md)
diff --git a/documentation/mdbook/src/abstract.md b/documentation/mdbook/src/abstract.md
@@ -0,0 +1,3 @@
+## Abstract
+
+Rattlesnake is a combined-environments, multiple input/multiple output control system for dynamic excitation of structures under test.  It provides capabilities to control multiple responses on the part using multiple exciters using various control strategies.  Rattlesnake is written in the Python programming language to facilitate multiple input/multiple output vibration research by allowing users to prescribe custom control laws to the controller.  Rattlesnake can target multiple hardware devices, or even perform synthetic control to simulate a test virtually.  Rattlesnake has been used to execute control problems with up to 200 response channels and 24 shaker drives.  This document describes the functionality, architecture, and usage of the Rattlesnake controller to perform combined environments testing.
diff --git a/documentation/mdbook/src/chapter_01.md b/documentation/mdbook/src/chapter_01.md
@@ -0,0 +1,16 @@
+## 1. Introduction
+
+The field of multiple input/multiple output (MIMO) vibration testing has grown substantially in the past few years.  MIMO vibration testing provides the capability to match a field environment more accurately and at more locations on the test article than traditional single-axis vibration testing.  Unfortunately, many existing vibration control systems are proprietary, which makes it difficult to implement new MIMO techniques.  
+
+Currently, MIMO vibration practitioners must either develop a control system from scratch to implement their ideas, or alternatively convince an MIMO vibration software vendor to implement their ideas into existing devices, and neither of these approaches are conducive to the rapid and iterative nature of research.  
+
+The Rattlesnake framework was developed to overcome these limitations and facilitate MIMO vibration research.  Rattlesnake is a MIMO control system that provides the user the ability to overcome testing challenges by providing a flexible framework that can be extended and modified to meet testing demands.  Rattlesnake can run multiple environments simultaneously, providing a combined-environments capability that does not yet exist in commercial software packages.  It can target multiple hardware devices, or even perform control virtually using a state space model, finite element model (FEM) results, or a SDynPy System.
+
+### 1.1 Document Overview
+
+This document provides information about the functionality in the Rattlesnake software, as well as instructions for how to use that functionality.  The document is divided into Parts targeting different aspects of the software.
+
+* [Part I](./chapter_02.md) provides an overview of the software as well as instructions for how to acquire and run the software.  Chapter 2 includes instructions for setting up the Python ecosystem required to run the software, if necessary.  Chapter 3 describes the Rattlesnake userinterface (UI).  Each main portion of the Rattlesnake interface is described along with the parameters that should be defined within that interface.
+* Part II describes the hardware devices available to the Rattlesnake software, as well as the hardware-specific considerations in the controller.  Each Chapter in this Part is dedicated to a specific hardware device.  Synthetic or virtual control is also discussed in this part, as well as instructions to extend Rattlesnake to additional hardware devices.
+* Part III describes the various control environments contained within the Rattlesnake software.  The environments defined within Rattlesnake are where the next output data that will be sent to the exciters are computed based off the previously acquired data.  Each chapter in this Part is dedicated to a environment type within Rattlesnake.  This chapter also provides instructions to combine environments as well as extend Rattlesnake to additional environments.
+* The Appendices contain several example problems.  Users with a reasonable understanding of the Rattlesnake workflow can use these chapters as a kind of "Quick Start" guide to the software.  Appendix B demonstrates a series of tests on a simple beam using a NI cDAQ hardware device.  Appendices C and D demonstrate virtual control problems using SDynPy System and State Space models, respectively, which only require a computer to run.
diff --git a/documentation/mdbook/src/chapter_02.md b/documentation/mdbook/src/chapter_02.md
@@ -0,0 +1,13 @@
+# Part I. Rattlesnake Overview
+
+This Part provides a general overview of Rattlesnake software.  Chapter 2 provides an overview of how to acquire and run the software.  Chapter 3 describes the general software workflow.
+
+This Part with only deal with "global" Rattlesnake paramters. For hardware-specific parameters, see Part II.  For environment-specific parameters, see Part III.
+
+## 2. Acquiring and Running Rattlesnake
+
+Two methods are provided to acquire the Rattlesnake software.  The software can be downloaded as an executable and run directly with no other dependencies.  Alternatively, the software can be downloaded in its Python script form and run using a Python interpreter.  The former approach is simpler, but results in a larger file size and longer software loading time due to the necessity to pack the Python ecosystem into the executable for distribution and unpack it prior to execution.  The latter approach is more suited to users who wish to utilize the full functionality of the Rattlesnake framework, which would include activities such as coding up custom control laws.  In this case, it will be advantageous to have a Python ecosystem installed on the user's computer, so simply downloading the source code and executing it similarly to other Python scripts will potentially be easier than the executable approach.
+
+### Running from an Executable
+
+WIP
diff --git a/documentation/mdbook/src/chapter_03.md b/documentation/mdbook/src/chapter_03.md
@@ -0,0 +1,3 @@
+## 3. Using Rattlesnake
+
+This chapter will describe how
diff --git a/documentation/mdbook/src/chapter_04.md b/documentation/mdbook/src/chapter_04.md
@@ -0,0 +1,13 @@
+# Part II. Rattlesnake Hardware Devices
+
+Designed for flexibility, Rattlesnake can be used with multiple hardware devices and even perform virtual control using a synthetic data acquisition system.  This Part will cover the hardware-specific implementation details that must be considered when running Rattlesnake with each hardware device.
+
+Rattlesnake is designed so there is minimal differences in software workflow when using different hardware devices.  Nonetheless, there are some slight differences in how channels and devices must be specified, and these differences are primarily found on the `Data Acquisition Setup` tab in the Rattlesnake software.
+
+The Chapters in this Part document the hardware devices that are able to be used by Rattlesnake, as well as the virtual devices that can be used to simulate control.  Chapter 4 describes the implementation and utilization of NI-DAQmx devices.  Chapter 5 describes the HBK LAN-XI hardware.  Chapters 6 and 7 describe the Data Physics Quattro and 900-series hardware devices, respectively.  Chapters 8, 9, and 10 describe virtual or synthetic hardware devices that are defined using state space matrices, eigensolution results stored in an exodus file, or a SDynPy System object, respectively.
+
+If a user is interested in implementing a new hardware device, Chapter 11 describes some of the things to be aware of.  Implementation of new hardware devices will require a good amount of knowledge of the Rattlesnake architecture.
+
+## Chapter 4. NIDAQMX Devices
+
+Rattlesnake is able to run National Instruments...
diff --git a/documentation/mdbook/src/chapter_05.md b/documentation/mdbook/src/chapter_05.md
@@ -0,0 +1,3 @@
+## 5. LAN-XI Devices
+
+Rattlesnake is able to run
diff --git a/documentation/mdbook/src/chapter_06.md b/documentation/mdbook/src/chapter_06.md
@@ -0,0 +1,3 @@
+## 6. Data Physics Quattro Devices
+
+Rattlesnakes is able to run Data Physics Quattro devices
diff --git a/documentation/mdbook/src/chapter_07.md b/documentation/mdbook/src/chapter_07.md
@@ -0,0 +1,3 @@
+## 7. Data Physics 900-series Devices
+
+The Data Physics DP900
diff --git a/documentation/mdbook/src/chapter_08.md b/documentation/mdbook/src/chapter_08.md
@@ -0,0 +1,3 @@
+## 8. Virtual Control using State Space Matrices
+
+If not data
diff --git a/documentation/mdbook/src/chapter_09.md b/documentation/mdbook/src/chapter_09.md
@@ -0,0 +1,3 @@
+## 9. Virtual Control using Finite Element Results in Exodus Files
+
+In addition to
diff --git a/documentation/mdbook/src/chapter_1.md b/documentation/mdbook/src/chapter_1.md
diff --git a/documentation/mdbook/src/chapter_10.md b/documentation/mdbook/src/chapter_10.md
@@ -0,0 +1,3 @@
+## 10. Virtual Control using SDYNPY System Objects
+
+The final option
diff --git a/documentation/mdbook/src/chapter_11.md b/documentation/mdbook/src/chapter_11.md
@@ -0,0 +1,3 @@
+## 11. Implementing New Hardward Devices with Rattlesnake
+
+**WARNING:** This chapter contains
diff --git a/documentation/mdbook/src/contributors.md b/documentation/mdbook/src/contributors.md
@@ -0,0 +1,3 @@
+## Contributors
+
+Contributors include...
diff --git a/documentation/mdbook/src/nomenclature.md b/documentation/mdbook/src/nomenclature.md
@@ -0,0 +1,25 @@
+## Nomenclature
+
+abbreviation | description
+--- | ---
+6DoF | six degree-of-freedom
+API | application programming interface
+APSD | auto-power spectral density
+CCLD | constant current line drive
+COLA | constant overlap and add
+CPSD | cross-power spectral density
+FEM | finite element model
+FFT | fast Fourier transform
+FRF | frequency response function
+GUI | graphical user interface
+ICP | integrated circuit piezoelectric
+IDE | integrated development environment
+IEPE | integrated electronics piezoelectric
+IFFT | inverse fast Fourier transform
+JSON | javascript object notation
+MIMO | multiple input/multiple output
+ReST | representational state transfer
+RMS | root-mean-square
+SVD | singular value decomposition
+TRAC | time response assurance criterion
+UI | user interface
diff --git a/documentation/mdbook/src/notation.md b/documentation/mdbook/src/notation.md
@@ -0,0 +1,35 @@
+## Notation
+
+### Accents
+
+* $\mathbf{x}$ (bold, non-italic typeface) Matrix or vector
+* $x$ (non-bold, italic typeface) Scalar or array
+
+### Variables
+
+* $n_f$ Number of frequency lines
+* $n_c$ Number of control channels
+* $n_o$ Number of output signals
+* $n_s$ Number of samples in a signal
+* $n_os$ Number of samples in an oversampled output signal
+* $\mathbf{G}_{vv}$ CPSD matrix for the output signals
+* $\mathbf{G}_{xx}$ CPSD matrix for the responses (i.e. the specification)
+* $\mathbf{H}_{xv}$ Transfer function matrix between the responses and the output signals
+* $\mathbf{X}$ Response spectra (FFT)
+* $\mathbf{V}$ Output spectra (FFT)
+* $\mathbf{T}$ Transformation matrix
+* $\mathbf{A}$ State or system matrix for state space equations of motion
+* $\mathbf{B}$ Input matrix for state space equations of motion
+* $\mathbf{C}$ Output matrix for state space equations of motion
+* $\mathbf{D}$ Feedthrough or feedforward matrix for state space equations of motion
+* $\mathbf{x}$ State vector for state space equations of motion
+* $\mathbf{y}$ Output vector for state space equations of motion
+* $\mathbf{u}$ Input vector for state space equations of motion
+* $\mathbf{M}$ Mass matrix for 2nd-order differential equations of motion
+* $\mathbf{C}$ Damping matrix for 2nd-order differential equations of motion
+* $\mathbf{K}$ Stiffness matrix for 2nd-order differential equations of motion
+
+### Operations
+
+* ⬚$^+$ Pseudoinverse of a matrix
+* ⬚$^H$ Complex-conjugate transpose of a matrix (hermitian)
