---
title: "massProps"
output: rmarkdown::html_vignette
bibliography: references.bib
vignette: >
%\VignetteIndexEntry{massProps}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
# Overview
The `massProps` package extends `rollupTree` with functions to recursively calculate mass properties (and optionally, their uncertainties) for arbitrary decomposition trees. Formulas implemented are described in a technical paper published by the Society of Allied Weight Engineers.[@zimmerman:05:sawe]
# Synopsis
## Data Structures
`massProps` operates on two fundamental data structures: a mass properties table and a tree. The mass properties table has an entry for every item in a tree structure of items; the edges of the tree convey the parent-child relations among items. The two data structures are linked by the `id` column of the data frame, which must be a character vector of unique item identifiers, and the vertex names of the tree. The sets of identifiers must be identical.
### Mass Property Table
#### Required Columns for Mass Properties
The Mass Property Table must contain the following columns. Other columns may exist and will remain unmodified.
- `id` unique identifier for each item (row)
- `mass` mass of the item (numeric)
- `Cx` $x$-component of center of mass (numeric)
- `Cy` $y$-component of center of mass (numeric)
- `Cx` $z$-component of center of mass (numeric)
- `Ixx` moment of inertia about the $x$ axis (numeric)
- `Iyy` moment of inertia about the $y$ axis (numeric)
- `Izz` moment of inertia about the $z$ axis (numeric)
- `Ixy` product of inertia relative to the $x$ and $y$ axes (numeric)
- `Ixz` product of inertia relative to the $x$ and $z$ axes (numeric)
- `Iyz` product of inertia relative to the $y$ and $z$ axes (numeric)
- `POIconv` either '+' or '-', indicating the sign convention for products of inertia[^1]
- `Ipoint` logical indicator that this item is considered a point mass (i.e., its inertia contribution is negligible)[^2]
[^1]: In the negative convention, for example, $I_{XY} \equiv -\int xy \rho \thinspace dV$. In the positive convention, $I_{XY} \equiv \int xy \rho \thinspace dV$.
[^2]: The same algebraic result can be achieved by setting all moments and products of inertia to zero, but `rollup_mass_props()` by default ensures that all leaf items in the tree have mass properties that correspond to physically-realizable objects. A zero inertia tensor will fail this check. Rather than relax the check (which is essential for trustworthy results), a `TRUE` value for `Ipoint` indicates that the inertia tensor should be excluded from computations.
#### Required Columns for Mass Properties Uncertainties
The following columns are required for uncertainty calculations:
- `sigma_mass` mass uncertainty (numeric)
- `sigma_Cx` $x$-component of center of mass uncertainty (numeric)
- `sigma_Cy` $y$-component of center of mass uncertainty (numeric)
- `sigma_Cx` $z$-component of center of mass uncertainty (numeric)
- `sigma_Ixx` moment of inertia about the $x$ axis uncertainty (numeric)
- `sigma_Iyy` moment of inertia about the $y$ axis uncertainty (numeric)
- `sigma_Izz` moment of inertia about the $z$ axis uncertainty (numeric)
- `sigma_Ixy` product of inertia relative to the $x$ and $y$ axes uncertainty (numeric)
- `sigma_Ixz` product of inertia relative to the $x$ and $z$ axes uncertainty (numeric)
- `sigma_Iyz` product of inertia relative to the $y$ and $z$ axes uncertainty (numeric)
It is the caller's responsibility to ensure that all values are expressed in appropriate and compatible units.
#### Tree
The tree is an `igraph::graph` with vertices named by identifiers in the mass properties table. It can be of arbitrary depth and shape as long as it satisfies certain well-formedness properties:
- it is connected and acyclic (as an undirected graph), i.e., it is a tree
- it is directed, with edge direction going from child to parent
- it contains neither loops (self-edges) nor multiple edges
- it contains a single root vertex (i.e., one whose out degree is zero)
## Invocation
```{r setup}
library(rollupTree)
library(massProps)
suppressPackageStartupMessages({library(igraph)})
```
Suppose we have the following mass properties table:
```{r}
test_table
```
Suppose we also have this tree:
```{r}
test_tree
```
```{r echo = FALSE}
plot(test_tree,layout=layout_as_tree(test_tree, 2, mode="in"), vertex.shape = 'none', edge.arrow.mode = 0)
```
Then we can compute mass properties for non-leaf elements by calling `rollup_mass_props()`:
```{r}
rollup_mass_props(test_tree, test_table)
```
The input may also contain uncertainties data. This example is from the Society of Allied Weight Engineers:
```{r echo = FALSE}
na_mass_props_and_unc <- function(d, t, v) {
xyz <- c("x", "y", "z")
list(
mass = NA,
center_mass = c(x = NA, y = NA, z = NA),
inertia = matrix(nrow = 3, ncol = 3, dimnames = list(xyz, xyz)),
poi_conv = "+",
point = FALSE,
sigma_mass = NA,
sigma_center_mass = c(x = NA, y = NA, z = NA),
sigma_inertia = matrix(nrow = 3, ncol = 3, dimnames = list(xyz, xyz))
)
}
na_mass_props_and_unc_update <- function(d, t, s) {
update_mass_props_and_unc(d, t, s, override = na_mass_props_and_unc)
}
sawe_input <- rollup(sawe_tree, sawe_table, update = na_mass_props_and_unc_update, validate_ds = validate_mass_props_and_unc_table)
```
```{r}
sawe_input
```
```{r}
rollup_mass_props_and_unc(sawe_tree, sawe_input)
```
# Objectives and Strategy
The objective of this package is to provide a trustworthy, well-documented, reference implementation for computation of mass properties (and their uncertainties) of aggregate objects from those of their parts. Aggregation can be recursive (e.g., indentured Bill of Materials), so it must accommodate trees of arbitrary depth and shape.
Strategies for achieving the objective include
- basing the calculations on published industry references,
- re-casting those lengthy reference equations into concise vector or matrix forms to reduce the error surface for source code and exploit the capabilities of `R`, which treats vectors and matrices as first-class objects,
- delegating orchestration to the `rollupTree` package, which, among other things, verifies that the input tree is well-formed and ensures proper ordering of computations,
- ensuring that all asserted leaf mass properties and uncertainties correspond to physically-realizable objects,
- coding in pure functional style, (i.e., avoiding mutable variables, implying iteration with `Map()` and `Reduce()`), and
- covering the entire code base with unit tests.
The author has intentionally made no effort to micro-optimize for performance. In particular, the author is aware that representing the inertia and its uncertainty as 3 ⨉ 3 matrices is "inefficient" to the degree that it independently calculates values that are redundant by symmetry. "Inefficient", however, does not mean "slow". See [Performance Evaluation] below.
# Theory
\newcommand{\sumwi}{\sum_{i=1}^{n}w_i}
\newcommand{\sumwivi}[1]{\sum_{i=1}^{n}{w_i}{{#1}_i}}
\newcommand{\moia}[3]{
\sum_{i=1}^{n} \left[ {I_{#1}}_i
+ w_i \left( {#2}_i^2 + {#3}_i^2 \right)
- w_i \left( \bar{#2}^2 + \bar{#3}^2 \right)
\right]
}
\newcommand{\moib}[3]{
\sum_{i=1}^{n} \left\{ {I_{#1}}_i
+ w_i \left[ \left( {#2}_i - \bar{#2} \right)^2 + \left( {#3}_i - \bar{#3} \right)^2 \right]
\right\}
}
\newcommand{\di}[1]{({#1}_i - \bar{#1})}
\newcommand{\poia}[3]{\sum_{i=1}^{n} \left[ {I_{#1}}_i + w_i {{#2}_i}{{#3}_i} -w_i (\bar{#2}\bar{#3})\right]}
\newcommand{\poib}[3]{\sum_{i=1}^{n} \left[ {I_{#1}}_i + w_i \di{#2}\di{#3}\right]}
\newcommand{\sigmacm}[2]{
\sqrt{ \sum_{i=1}^n \big\{ (w_i {{#1}}_i)^2 + [{\sigma_w}_i \di{#2}]^2 \big\}}
}
\newcommand{\sigmamoi}[3]{\sqrt{ \sum_{i=1}^n \big\{
\sigma_{{I_{#1}}_i}^2 + \big[ 2 w_i \di{#2} \sigma_{{#2}_i} \big]^2 + \big[ 2 w_i \di{#3} \sigma_{{#3}_i} \big]^2 + \big[ \big(\di{#2}^2 + \di{#3}^2 \big)\sigma_{w_i}\big]^2 \big\} }
}
\newcommand{\sigmapoi}[3]{\sqrt{ \sum_{i=1}^n \big\{
\sigma_{{I_{#1}}_i}^2 + \big[ \di{#2} w_i \sigma_{{#3}_i}\big]^2 + \big[ \di{#2}\di{#3}\sigma_{w_i} \big]^2 + \big[ \di{#3} w_i \sigma_{{#2}_i} \big]^2 \big\} }
}
In this section, we state the reference equations [@zimmerman:05:sawe] and show, where applicable, how those equations can be rewritten in more concise form. The form of the equations actually implemented is displayed within a box, e.g. $\boxed{F = ma}$.
The reference uses the word *weight* and the symbol $w$ in equations. We interpret weight as mass. The reference refers to center of mass by its $x$, $y$, and $z$ components. Symbols for moments ($I_{xx}$) and products ($I_{xy}$) of inertia are conventional. Variables with $i$ subscripts designate properties of parts; those without designate properties of aggregates. The letter $\sigma$ denotes uncertainty. $\sigma_w$, for example, is the mass uncertainty.
## Mass Properties
### Mass
The mass equation is suitable as is.
$$
\boxed{
w = \sum_{i=1}^{n}w_i
}
$$
The corresponding `R` code is
``` r
r$mass <- Reduce(`+`, Map(f = function(v) v$mass, vl))
```
In this and the following code snippets, the variable `vl` is a list of input mass property sets, the variable `v` is a formal parameter of an anonymous function applied to each member of `vl`, and `r` is the resulting mass property set. The line above is an `R` functional programming idiom for "set the mass value of the result to the sum of the mass values of the inputs".
### Center of Mass
$$
\begin{align}
\bar{x} & = \sum_{i=1}^{n}{w_i}{{x}_i} \bigg/ \sum_{i=1}^{n}w_i\\
\bar{y} & = \sum_{i=1}^{n}{w_i}{{y}_i} \bigg/ \sum_{i=1}^{n}w_i\\
\bar{z} & = \sum_{i=1}^{n}{w_i}{{z}_i} \bigg/ \sum_{i=1}^{n}w_i\\
\end{align}
$$
We can express center of mass as a 3-vector:
$$
\boxed{
\begin{align}
\boldsymbol{c}_i & = (x_i \quad y_i \quad z_i)^T \\
\boldsymbol{\bar{c}}& = (\bar{x} \quad \bar{y} \quad \bar{z})^T
\end{align}
}
$$
Then
$$
\boxed{
\boldsymbol{\bar{c}} = \frac{1}{w} \sum_{i=1}^{n}{w_i}{{\boldsymbol{c}}_i}
}
$$
The corresponding `R` code is
``` r
r$center_mass <- Reduce(`+`, Map(f = function(v) v$mass * v$center_mass, vl)) / r$mass
```
### Inertia Tensor
#### Moments of Inertia
$$
\begin{align}
I_{XX} & =
\sum_{i=1}^{n} \left[ {I_{XX}}_i
+ w_i \left( {y}_i^2 + {z}_i^2 \right)
- w_i \left( \bar{y}^2 + \bar{z}^2 \right)
\right]
& =
\sum_{i=1}^{n} \left\{ {I_{XX}}_i
+ w_i \left[ \left( {y}_i - \bar{y} \right)^2 + \left( {z}_i - \bar{z} \right)^2 \right]
\right\}
\\
I_{YY} & =
\sum_{i=1}^{n} \left[ {I_{YY}}_i
+ w_i \left( {x}_i^2 + {z}_i^2 \right)
- w_i \left( \bar{x}^2 + \bar{z}^2 \right)
\right]
& =
\sum_{i=1}^{n} \left\{ {I_{YY}}_i
+ w_i \left[ \left( {x}_i - \bar{x} \right)^2 + \left( {z}_i - \bar{z} \right)^2 \right]
\right\}
\\
I_{ZZ} & =
\sum_{i=1}^{n} \left[ {I_{ZZ}}_i
+ w_i \left( {x}_i^2 + {y}_i^2 \right)
- w_i \left( \bar{x}^2 + \bar{y}^2 \right)
\right]
& =
\sum_{i=1}^{n} \left\{ {I_{ZZ}}_i
+ w_i \left[ \left( {x}_i - \bar{x} \right)^2 + \left( {y}_i - \bar{y} \right)^2 \right]
\right\}
\\
\end{align}
$$
#### Products of Inertia
$$
\begin{align}
I_{XY} & = \sum_{i=1}^{n} \left[ {I_{XY}}_i + w_i {{x}_i}{{y}_i} -w_i (\bar{x}\bar{y})\right] & = \sum_{i=1}^{n} \left[ {I_{XY}}_i + w_i ({x}_i - \bar{x})({y}_i - \bar{y})\right] \\
I_{XZ} & = \sum_{i=1}^{n} \left[ {I_{XZ}}_i + w_i {{x}_i}{{z}_i} -w_i (\bar{x}\bar{z})\right] & = \sum_{i=1}^{n} \left[ {I_{XZ}}_i + w_i ({x}_i - \bar{x})({z}_i - \bar{z})\right] \\
I_{YZ} & = \sum_{i=1}^{n} \left[ {I_{YZ}}_i + w_i {{y}_i}{{z}_i} -w_i (\bar{y}\bar{z})\right] & = \sum_{i=1}^{n} \left[ {I_{YZ}}_i + w_i ({y}_i - \bar{y})({z}_i - \bar{z})\right] \\
\end{align}
$$
#### Matrix Formulation
Let $I$ be the inertia tensor of the aggregate and $I_i$ be that of part $i$. The equations for products of inertia above clearly follow the positive integral convention, so
$$
I =
\left[ \begin{matrix}
I_{xx} & -I_{xy} & -I_{xz} \\
-I_{xy} & I_{yy} & -I_{yz} \\
-I_{xz} & -I_{yz} & I_{zz}
\end{matrix}
\right]
$$
and similarly for $I_i$.
Noting the repeated appearance of terms of the form $({x}_i - \bar{x})({y}_i - \bar{y})$, we form the outer product
$$
\boxed{
\begin{align}
\boldsymbol{d}_i & = (({x}_i - \bar{x}) \quad ({y}_i - \bar{y}) \quad ({z}_i - \bar{z}))^T \\
\boldsymbol{Q}_i & = \boldsymbol{d}_i {\boldsymbol{d}_i}^T
\end{align}
}
$$ Then
$$
\begin{align}
\boldsymbol{Q}_i & =
\begin{bmatrix}
({x}_i - \bar{x})^2 & ({x}_i - \bar{x})({y}_i - \bar{y}) & ({x}_i - \bar{x})({z}_i - \bar{z}) \\
({y}_i - \bar{y})({x}_i - \bar{x}) & ({y}_i - \bar{y})^2 & ({y}_i - \bar{y})({z}_i - \bar{z}) \\
({z}_i - \bar{z})({x}_i - \bar{x}) & ({z}_i - \bar{z})({y}_i - \bar{y}) & ({z}_i - \bar{z})^2 \\
\end{bmatrix}
\end{align}
$$
Let $\boldsymbol{s}_i$ be the matrix of inertia tensor summands from the reference equations. That is,
$$
\boldsymbol{I} = \sum_{i=1}^{n} \boldsymbol{s}_i
$$
where $$
\begin{align}
\boldsymbol{s}_i & = \boldsymbol{I}_i \\
& -
w_i \begin{bmatrix}
-({y}_i - \bar{y})^2 - ({z}_i - \bar{z})^2 & ({x}_i - \bar{x})({y}_i - \bar{y}) & ({x}_i - \bar{x})({z}_i - \bar{z}) \\
({x}_i - \bar{x})({y}_i - \bar{y}) & -({x}_i - \bar{x})^2 - ({z}_i - \bar{z})^2 & ({y}_i - \bar{y})({z}_i - \bar{z}) \\
({x}_i - \bar{x})({z}_i - \bar{z}) & ({y}_i - \bar{y})({z}_i - \bar{z}) & -({x}_i - \bar{x})^2 - ({y}_i - \bar{y})^2 \\
\end{bmatrix} \\
& =
\boldsymbol{I}_i \\
& -
w_i \begin{bmatrix}
({x}_i - \bar{x})^2 & ({x}_i - \bar{x})({y}_i - \bar{y}) & ({x}_i - \bar{x})({z}_i - \bar{z}) \\
({x}_i - \bar{x})({y}_i - \bar{y}) & ({y}_i - \bar{y})^2 & ({y}_i - \bar{y})({z}_i - \bar{z}) \\
({x}_i - \bar{x})({z}_i - \bar{z}) & ({y}_i - \bar{y})({z}_i - \bar{z}) & ({z}_i - \bar{z})^2 \\
\end{bmatrix} \\
& -
w_i \begin{bmatrix}
-({x}_i - \bar{x})^2 - ({y}_i - \bar{y})^2 - ({z}_i - \bar{z})^2 & 0 & 0 \\
0 & -({x}_i - \bar{x})^2 - ({y}_i - \bar{y})^2 - ({z}_i - \bar{z})^2 & 0 \\
0 & 0 &-({x}_i - \bar{x})^2 - ({y}_i - \bar{y})^2 - ({z}_i - \bar{z})^2 \\
\end{bmatrix} \\
& =
\boldsymbol{I}_i
-
w_i \left( \boldsymbol{Q}_i - \mathrm{tr}(\boldsymbol{Q}_i) \boldsymbol{1}_3 \right)
\end{align}
$$
where $\boldsymbol{1}_3$ is the 3 ⨉ 3 identity matrix. Therefore
$$
\boxed{
\boldsymbol{I} = \sum_{i=1}^{n} \left( \boldsymbol{I}_i
-
w_i \boldsymbol{M}_i \right)
}
$$
where
$$
\boxed{
\boldsymbol{M}_i = \boldsymbol{Q}_i - \mathrm{tr}(\boldsymbol{Q}_i) \boldsymbol{1}_3
}
$$
The corresponding `R` code is
``` r
r$inertia <- Reduce(`+`, Map(
f = function(v) {
d <- r$center_mass - v$center_mass
M <- outer(d, d) - sum(d^2) * diag(3)
if (v$point) -v$mass * M else v$inertia - v$mass * M
},
vl
))
```
## Mass Property Uncertainties
### Mass Uncertainty
The mass uncertainty equation is suitable as is.
$$
\boxed{
\sigma_w = \sqrt{ \sum_{i=1}^n {{\sigma_w}_i}^2 }
}
$$
The corresponding `R` code is
``` r
r$sigma_mass = sqrt(Reduce(`+`, Map(f = function(v) v$sigma_mass^2, vl)))
```
### Center of Mass Uncertainty
$$
\begin{align}
\sigma_x & =
\sqrt{ \sum_{i=1}^n \left\{ (w_i {{\sigma_y}}_i)^2 + [{\sigma_w}_i ({y}_i - \bar{y})]^2 \right\} }
\bigg/ \sum_{i=1}^{n}w_i \\
\sigma_y & =
\sqrt{ \sum_{i=1}^n \left\{ (w_i {{\sigma_y}}_i)^2 + [{\sigma_w}_i ({y}_i - \bar{y})]^2 \right\} }
\bigg/ \sum_{i=1}^{n}w_i \\
\sigma_z & =
\sqrt{ \sum_{i=1}^n \left\{ (w_i {{\sigma_z}}_i)^2 + [{\sigma_w}_i ({z}_i - \bar{z})]^2 \right\} }
\bigg/ \sum_{i=1}^{n}w_i \\
\end{align}
$$
As before, we create a 3-vector for center of mass uncertainties. Let
$$
\boxed{
\begin{align}
\boldsymbol{\sigma_c} & = (\sigma_x \quad \sigma_y \quad \sigma_z)^T \\
{\boldsymbol{\sigma_c}}_i & = ({\sigma_x}_i \quad {\sigma_y}_i \quad {\sigma_z}_i)^T
\end{align}
}
$$
If we construe (as `R` does) squaring and taking square roots of vectors element-wise, then
$$
\boxed{
\boldsymbol{\sigma_c} = \frac{1}{w}
\sqrt{ \sum_{i=1}^n \left\{ (w_i {{\boldsymbol{\sigma_c}}}_i)^2 + [{\sigma_w}_i ({\boldsymbol{c}}_i - \bar{\boldsymbol{c}})]^2 \right\}}
}
$$
The corresponding `R` code is
``` r
r$sigma_center_mass = sqrt(Reduce(`+`, Map(
f = function(v) {
(v$mass * v$sigma_center_mass)^2 +
(v$sigma_mass * (v$center_mass - r$center_mass))^2
},
vl
))) / r$mass
```
### Inertia Tensor Uncertainty
#### Moments of Inertia Uncertainties
$$
\begin{align}
\sigma_{I_{XX}} & = \sqrt{ \sum_{i=1}^n \big\{
\sigma_{{I_{XX}}_i}^2 + \big[ 2 w_i ({y}_i - \bar{y}) \sigma_{{y}_i} \big]^2 + \big[ 2 w_i ({z}_i - \bar{z}) \sigma_{{z}_i} \big]^2 + \big[ \big(({y}_i - \bar{y})^2 + ({z}_i - \bar{z})^2 \big)\sigma_{w_i}\big]^2 \big\} }
\\
\sigma_{I_{YY}} & = \sqrt{ \sum_{i=1}^n \big\{
\sigma_{{I_{YY}}_i}^2 + \big[ 2 w_i ({x}_i - \bar{x}) \sigma_{{x}_i} \big]^2 + \big[ 2 w_i ({z}_i - \bar{z}) \sigma_{{z}_i} \big]^2 + \big[ \big(({x}_i - \bar{x})^2 + ({z}_i - \bar{z})^2 \big)\sigma_{w_i}\big]^2 \big\} }
\\
\sigma_{I_{ZZ}} & = \sqrt{ \sum_{i=1}^n \big\{
\sigma_{{I_{ZZ}}_i}^2 + \big[ 2 w_i ({x}_i - \bar{x}) \sigma_{{x}_i} \big]^2 + \big[ 2 w_i ({y}_i - \bar{y}) \sigma_{{y}_i} \big]^2 + \big[ \big(({x}_i - \bar{x})^2 + ({y}_i - \bar{y})^2 \big)\sigma_{w_i}\big]^2 \big\} }
\\
\end{align}
$$
#### Products of Inertia Uncertainties
$$
\begin{align}
\sigma_{I_{XY}} & = \sqrt{ \sum_{i=1}^n \big\{
\sigma_{{I_{XY}}_i}^2 + \big[ ({x}_i - \bar{x}) w_i \sigma_{{y}_i}\big]^2 + \big[ ({x}_i - \bar{x})({y}_i - \bar{y})\sigma_{w_i} \big]^2 + \big[ ({y}_i - \bar{y}) w_i \sigma_{{x}_i} \big]^2 \big\} }
\\
\sigma_{I_{XZ}} & = \sqrt{ \sum_{i=1}^n \big\{
\sigma_{{I_{XZ}}_i}^2 + \big[ ({x}_i - \bar{x}) w_i \sigma_{{z}_i}\big]^2 + \big[ ({x}_i - \bar{x})({z}_i - \bar{z})\sigma_{w_i} \big]^2 + \big[ ({z}_i - \bar{z}) w_i \sigma_{{x}_i} \big]^2 \big\} }
\\
\sigma_{I_{YZ}} & = \sqrt{ \sum_{i=1}^n \big\{
\sigma_{{I_{YZ}}_i}^2 + \big[ ({y}_i - \bar{y}) w_i \sigma_{{z}_i}\big]^2 + \big[ ({y}_i - \bar{y})({z}_i - \bar{z})\sigma_{w_i} \big]^2 + \big[ ({z}_i - \bar{z}) w_i \sigma_{{y}_i} \big]^2 \big\} }
\\
\end{align}
$$
#### Matrix Formulation
Let
$$
\boxed{
\begin{align}
\boldsymbol{d}_i & = (({x}_i - \bar{x}) \quad ({y}_i - \bar{y}) \quad ({z}_i - \bar{z}))^T \\
{\boldsymbol{\sigma_c}}_i & = ({\sigma_x}_i \quad {\sigma_y}_i \quad {\sigma_z}_i)^T \\
\boldsymbol{P}_i & = \boldsymbol{d}_i {\boldsymbol{\sigma_c}}_i^T \\
\boldsymbol{Q}_i & = \boldsymbol{d}_i {\boldsymbol{d}_i}^T
\end{align}
}
$$
Then
$$
\begin{align}
\boldsymbol{P}_i & =
\begin{bmatrix}
(x_i - \bar{x})\sigma_{x_i} &({x}_i - \bar{x})\sigma_{y_i} &({x}_i - \bar{x})\sigma_{z_i} \\
({y}_i - \bar{y})\sigma_{x_i} & ({y}_i - \bar{y})\sigma_{y_i} & ({y}_i - \bar{y})\sigma_{z_i} \\
({z}_i - \bar{z})\sigma_{x_i} & ({z}_i - \bar{z})\sigma_{y_i} & ({z}_i - \bar{z})\sigma_{z_i} \\
\end{bmatrix}
\\
\\
\boldsymbol{Q}_i & =
\begin{bmatrix}
(x_i - \bar{x})^2 &({x}_i - \bar{x})({y}_i - \bar{y}) &({x}_i - \bar{x})({z}_i - \bar{z}) \\
({y}_i - \bar{y})(x_i - \bar{x}) & ({y}_i - \bar{y})^2 & ({y}_i - \bar{y})({z}_i - \bar{z}) \\
({z}_i - \bar{z})(x_i - \bar{x}) & ({z}_i - \bar{z})({y}_i - \bar{y}) & ({z}_i - \bar{z})^2 \\
\end{bmatrix}
\end{align}
$$
Let $\boldsymbol{s}_i^2$ be the matrix of inertia tensor uncertainty summands in the standard formulas for a given subcomponent $i$ above. That is,
$$
\boldsymbol{\sigma_I}^2 = \sum_{i=1}^{} \boldsymbol{s}_i^2
$$
Let ${p_X}_i$, ${p_Y}_i$, and ${p_Z}_i$ be the respective diagonal elements of $P_i$. Let $\boldsymbol{1}_3$ be the 3 ⨉ 3 identity matrix. If we interpret squaring a matrix as the Hadamard (element-wise) product with itself, then $$
\begin{align}
\boldsymbol{s}_i^2 & = {\boldsymbol{\sigma_I}}_i^2 \\
& +
\begin{bmatrix}
2 w_i ({y}_i - \bar{y}) \sigma_{y_i} & w_i({x}_i - \bar{x}) \sigma_{y_i} & w_i({x}_i - \bar{x}) \sigma_{z_i} \\
w_i({x}_i - \bar{x}) \sigma_{y_i} & 2 w_i({x}_i - \bar{x}) \sigma_{x_i} & w_i ({y}_i - \bar{y}) \sigma_{z_i} \\
w_i({x}_i - \bar{x}) \sigma_{z_i} & w_i ({y}_i - \bar{y}) \sigma_{z_i} & 2 w_i({x}_i - \bar{x}) \sigma_{x_i}
\end{bmatrix}^2 \\
& +
\begin{bmatrix}
2 w_i ({z}_i - \bar{z}) \sigma_{z_i} & w_i ({y}_i - \bar{y}) \sigma_{x_i} & w_i ({z}_i - \bar{z}) \sigma_{x_i} \\
w_i ({y}_i - \bar{y}) \sigma_{x_i} & 2 w_i ({z}_i - \bar{z}) \sigma_{z_i} & w_i ({z}_i - \bar{z}) \sigma_{y_i} \\
w_i ({z}_i - \bar{z}) \sigma_{x_i} & w_i ({z}_i - \bar{z}) \sigma_{y_i} & 2 w_i ({y}_i - \bar{y}) \sigma_{y_i}
\end{bmatrix}^2 \\
& +
\begin{bmatrix}
(({y}_i - \bar{y})^2 + ({z}_i - \bar{z})^2)\sigma_{w_i} &({x}_i - \bar{x})({y}_i - \bar{y})\sigma_{w_i} &({x}_i - \bar{x})({z}_i - \bar{z})\sigma_{w_i} \\
({y}_i - \bar{y})(x_i - \bar{x})\sigma_{w_i} & ((x_i - \bar{x})^2 + ({z}_i - \bar{z})^2)\sigma_{w_i} & ({y}_i - \bar{y})({z}_i - \bar{z})\sigma_{w_i} \\
({z}_i - \bar{z})(x_i - \bar{x})\sigma_{w_i} & ({z}_i - \bar{z})({y}_i - \bar{y})\sigma_{w_i} & ((x_i - \bar{x})^2 + ({y}_i - \bar{y})^2)\sigma_{w_i} \\
\end{bmatrix}^2 \\ \\
& = {\boldsymbol{\sigma_I}}_i^2 \\
& + w_i^2 \left(
\boldsymbol{P}_i -
\begin{bmatrix}
(x_i - \bar{x})\sigma_{x_i} - 2 ({y}_i - \bar{y})\sigma_{y_i} & 0 & 0 \\
0 & ({y}_i - \bar{y})\sigma_{y_i} - 2({x}_i - \bar{x})\sigma_{x_i} & 0 \\
0 & 0 & ({z}_i - \bar{z})\sigma_{y_i} - 2({x}_i - \bar{x})\sigma_{x_i} \\
\end{bmatrix}
\right) ^2 \\
& + w_i^2 \left(
\boldsymbol{P}_i^T -
\begin{bmatrix}
(x_i - \bar{x})\sigma_{x_i} - 2 ({z}_i - \bar{z})\sigma_{y_i} & 0 & 0 \\
0 & ({y}_i - \bar{y})\sigma_{y_i} - 2 ({z}_i - \bar{z})\sigma_{z_i} & 0 \\
0 & 0 & ({z}_i - \bar{z})\sigma_{y_i} - 2 ({y}_i - \bar{y})\sigma_{y_i} \\
\end{bmatrix}
\right) ^2 \\
& + \sigma_{w_i}^2 \left(
\boldsymbol{Q}_i - \mathrm{tr}(\boldsymbol{Q}_i)\boldsymbol{1}_3
\right)^2 \\ \\
& = {\boldsymbol{\sigma_I}}_i^2 \\
& + w_i^2 \left(
\boldsymbol{P}_i -
\begin{bmatrix}
{p_X}_i - 2 {p_Y}_i & 0 & 0 \\
0 & {p_Y}_i - 2 {p_X}_i & 0 \\
0 & 0 & {p_Z}_i - 2 {p_X}_i \\
\end{bmatrix}
\right) ^2 \\
& + w_i^2 \left(
\boldsymbol{P}_i^T -
\begin{bmatrix}
{p_X}_i - 2{p_Z}_i & 0 & 0 \\
0 & {p_Y}_i - 2 {p_Z}_i & 0 \\
0 & 0 & {p_Z}_i - 2 {p_Y}_i \\
\end{bmatrix}
\right) ^2 \\
& + \sigma_{w_i}^2 \left(
\boldsymbol{Q}_i - \mathrm{tr}(\boldsymbol{Q}_i)\boldsymbol{1}_3
\right)^2
\end{align}
$$
Finally,
$$
\boldsymbol{\sigma_I} = \sqrt{
\sum_{i=1}^{n} {\left\{
{\boldsymbol{\sigma_I}}_i^2
+ w_i^2 \left(
{{\boldsymbol{M}_1}_i}^2 + {{\boldsymbol{M}_2}_i}^2
\right)
+ \left( \sigma_{w_i} {\boldsymbol{M}_3}_i
\right)^2
\right\}}
}
$$
where
$$
\boxed{
\begin{align}
{\boldsymbol{M}_1}_i & = \boldsymbol{P}_i -
\begin{bmatrix}
{p_X}_i - 2 {p_Y}_i & 0 & 0 \\
0 & {p_Y}_i - 2 {p_X}_i & 0 \\
0 & 0 & {p_Z}_i - 2 {p_X}_i \\
\end{bmatrix} \\
{\boldsymbol{M}_2}_i & = \boldsymbol{P}_i^T -
\begin{bmatrix}
{p_X}_i - 2{p_Z}_i & 0 & 0 \\
0 & {p_Y}_i - 2 {p_Z}_i & 0 \\
0 & 0 & {p_Z}_i - 2 {p_Y}_i \\
\end{bmatrix} \\
{\boldsymbol{M}_3}_i & = \boldsymbol{Q}_i - \mathrm{tr}(\boldsymbol{Q}_i)\boldsymbol{1}_3
\end{align}
}
$$
The corresponding `R` code is
``` r
r$sigma_inertia = sqrt(Reduce(`+`, Map(
f = function(v) {
d <- v$center_mass - r$center_mass
P <- outer(d, v$sigma_center_mass)
p <- as.list(diag(P))
M1 <- P - diag(c(p$x - 2 * p$y, p$y - 2 * p$x, p$z - 2 * p$x))
M2 <- t(P) - diag(c(p$x - 2 * p$z, p$y - 2 * p$z, p$z - 2 * p$y))
M3 <- outer(d, d) - sum(diag(d^2)) * diag(3)
M4 <- v$mass^2 * (M1^2 + M2^2) + (v$sigma_mass * M3)^2
if (v$point) M4 else v$sigma_inertia^2 + M4
},
vl
)))
```
# Testing and Validation
## Comparison With Independently-Calculated Results
In this section we will calculate the results for the SAWE example step by step and compare them with the package results. The inputs are:
```{r echo = FALSE}
sawe_input <- sawe_table[which(sawe_table$id != "Combined"), ]
sawe_input
```
Our computed result is
```{r}
sawe_result <- rollup_mass_props_and_unc(sawe_tree, sawe_table)[3, ]
sawe_result
```
### Mass
```{r echo = FALSE}
agree <- function(l) if (l) "agrees" else "does not agree"
```
```{r}
mass <- sum(sawe_input$mass)
```
The independently-calculated mass is
```{r echo = FALSE}
mass
```
This `r agree(isTRUE(all.equal(mass, sawe_result$mass)))` with the computed result.
### Center of Mass
```{r}
C <- apply(sawe_input$mass / mass * sawe_input[, c("Cx", "Cy", "Cz")], 2, sum)
```
The independently-calculated center of mass is
```{r echo = FALSE}
C
```
This `r agree(isTRUE(all.equal(unname(C), c(sawe_result$Cx, sawe_result$Cy, sawe_result$Cz))))` with the computed result.
### Moments of Inertia
```{r}
moi <- function(I, v1, v2, m, c1, c2) {
I + m * ((v1^2 + v2^2) - (c1^2 + c2^2))
}
MOI <- c(
Ixx = sum(moi(sawe_input$Ixx, sawe_input$Cy, sawe_input$Cz, sawe_input$mass, C["Cy"], C["Cz"])),
Iyy = sum(moi(sawe_input$Iyy, sawe_input$Cx, sawe_input$Cz, sawe_input$mass, C["Cx"], C["Cz"])),
Izz = sum(moi(sawe_input$Izz, sawe_input$Cx, sawe_input$Cy, sawe_input$mass, C["Cx"], C["Cy"]))
)
```
The independently-calculated moments of inertia are
```{r echo = FALSE}
MOI
```
This `r agree(isTRUE(all.equal(MOI, c(Ixx = sawe_result$Ixx, Iyy = sawe_result$Iyy, Izz = sawe_result$Izz))))` with the computed result.
### Products of Inertia
```{r}
poi <- function(I, v1, v2, m, c1, c2) {
I + m * (v1 * v2 - c1 * c2)
}
POI <- c(
Ixy = sum(poi(sawe_input$Ixy, sawe_input$Cx, sawe_input$Cy, sawe_input$mass, C["Cx"], C["Cy"])),
Ixz = sum(poi(sawe_input$Ixz, sawe_input$Cx, sawe_input$Cz, sawe_input$mass, C["Cx"], C["Cz"])),
Iyz = sum(poi(sawe_input$Iyz, sawe_input$Cy, sawe_input$Cz, sawe_input$mass, C["Cy"], C["Cz"]))
)
```
The independently-calculated products of inertia are
```{r echo = FALSE}
POI
```
This `r agree(isTRUE(all.equal(POI, c(Ixy = sawe_result$Ixy, Ixz = sawe_result$Ixz, Iyz = sawe_result$Iyz))))` with the computed result.
### Mass Uncertainty
```{r}
sigma_mass <- sqrt(sum(sawe_input$sigma_mass^2))
```
The independently-calculated mass uncertainty is
```{r echo = FALSE}
sigma_mass
```
This `r agree(isTRUE(all.equal(sigma_mass, sawe_result$sigma_mass)))` with the computed result.
### Center of Mass Uncertainty
```{r}
sigma_cm <- function(m, sigma_v, sigma_m, v, c) {
(m * sigma_v)^2 + (sigma_m * (v - c))^2
}
sigma_C <- c(
sigma_Cx = sqrt(sum(sigma_cm(sawe_input$mass, sawe_input$sigma_Cx, sawe_input$sigma_mass, sawe_input$Cx, C["Cx"]))) / mass,
sigma_Cy = sqrt(sum(sigma_cm(sawe_input$mass, sawe_input$sigma_Cy, sawe_input$sigma_mass, sawe_input$Cy, C["Cy"]))) / mass,
sigma_Cz = sqrt(sum(sigma_cm(sawe_input$mass, sawe_input$sigma_Cz, sawe_input$sigma_mass, sawe_input$Cz, C["Cz"]))) / mass
)
```
The independently-calculated center of mass uncertainties are
```{r echo = FALSE}
sigma_C
```
This `r agree(isTRUE(all.equal(sigma_C, c(sigma_Cx = sawe_result$sigma_Cx, sigma_Cy = sawe_result$sigma_Cy, sigma_Cz = sawe_result$sigma_Cz))))` with the computed result.
### Moments of Inertia Uncertainties
```{r}
sigma_moi <- function(sigma_I, mass, sigma_mass, v1, v2, c1, c2, sigma_v1, sigma_v2) {
sigma_I^2 +
(2 * mass * (v1 - c1) * sigma_v1)^2 +
(2 * mass * (v2 - c2) * sigma_v2)^2 +
(((v1 - c1)^2 + (v2 - c2)^2) * sigma_mass)^2
}
sigma_MOI <- c(
sigma_Ixx = sqrt(sum(sigma_moi(sawe_input$sigma_Ixx, sawe_input$mass, sawe_input$sigma_mass, sawe_input$Cy,
sawe_input$Cz, C["Cy"], C["Cz"], sawe_input$sigma_Cy, sawe_input$sigma_Cz))),
sigma_Iyy = sqrt(sum(sigma_moi(sawe_input$sigma_Iyy, sawe_input$mass, sawe_input$sigma_mass, sawe_input$Cx,
sawe_input$Cz, C["Cx"], C["Cz"], sawe_input$sigma_Cx, sawe_input$sigma_Cz))),
sigma_Izz = sqrt(sum(sigma_moi(sawe_input$sigma_Izz, sawe_input$mass, sawe_input$sigma_mass, sawe_input$Cx,
sawe_input$Cy, C["Cx"], C["Cy"], sawe_input$sigma_Cx, sawe_input$sigma_Cy)))
)
```
The independently-calculated moments of inertia uncertainties are
```{r echo = FALSE}
sigma_MOI
```
This `r agree(isTRUE(all.equal(sigma_MOI, c(sigma_Ixx = sawe_result$sigma_Ixx, sigma_Iyy = sawe_result$sigma_Iyy, sigma_Izz = sawe_result$sigma_Izz))))` with the computed result.
### Products of Inertia Uncertainties
```{r}
sigma_poi <- function(sigma_I, mass, sigma_mass, v1, v2, c1, c2, sigma_v1, sigma_v2) {
sigma_I^2 +
((v1 - c1) * mass * sigma_v2)^2 +
((v1 - c1) * (v2 - c2) * sigma_mass)^2 +
((v2 - c2) * mass * sigma_v1)^2
}
sigma_POI <- c(
sigma_Ixy = sqrt(sum(sigma_poi(sawe_input$sigma_Ixy, sawe_input$mass, sawe_input$sigma_mass, sawe_input$Cx,
sawe_input$Cy, C["Cx"], C["Cy"], sawe_input$sigma_Cx, sawe_input$sigma_Cy))),
sigma_Ixz = sqrt(sum(sigma_poi(sawe_input$sigma_Ixz, sawe_input$mass, sawe_input$sigma_mass, sawe_input$Cx,
sawe_input$Cz, C["Cx"], C["Cz"], sawe_input$sigma_Cx, sawe_input$sigma_Cz))),
sigma_Iyz = sqrt(sum(sigma_poi(sawe_input$sigma_Iyz, sawe_input$mass, sawe_input$sigma_mass, sawe_input$Cy,
sawe_input$Cz, C["Cy"], C["Cz"], sawe_input$sigma_Cy, sawe_input$sigma_Cz)))
)
```
The independently-calculated products of inertia uncertainties are
```{r echo = FALSE}
sigma_POI
```
This `r agree(isTRUE(all.equal(sigma_POI, c(sigma_Ixy = sawe_result$sigma_Ixy, sigma_Ixz = sawe_result$sigma_Ixz, sigma_Iyz = sawe_result$sigma_Iyz))))` with the computed result.
## Comparison With Published Results
The SAWE reference provides computed results for their example. These results match those within a tolerance of 0.2%. The small differences are likely because their actual input values were not identical to the truncated values published in the article.
# Performance Evaluation
```{r echo = FALSE}
mp_tree_depth <- max(dfs(mp_tree, 2, mode = "in", order=FALSE, dist=TRUE)$dist) + 1
nv <- length(igraph::V(mp_tree))
ne <- length(igraph::E(mp_tree))
nl <- length(which(igraph::degree(mp_tree, mode="in") == 0))
ni <- (nv - 1) * 20
no <- (nv - nl) * 20
```
`mp_table` and `mp_tree` are a synthesized data set representing a tree of depth `r mp_tree_depth` with `r nv` vertices and `r ne` edges. `r nl` vertices are leaves, the remaining `r nv - nl` are non-leaves. Rolling up mass properties and uncertainties for this data set combines `r paste(ni)` input values to produce `r no` output values. Mass properties alone halves those values.
Benchmarks were taken on a platform with these CPU characteristics:
```
Python Version: 3.12.7.final.0 (64 bit)
Cpuinfo Version: 9.0.0
Vendor ID Raw:
Hardware Raw:
Brand Raw: Apple M3
Hz Advertised Friendly:
Hz Actual Friendly: 2.4000 GHz
Hz Advertised:
Hz Actual: (2400000000, 0)
Arch: ARM_8
Bits: 64
Count: 8
Arch String Raw: arm64
L1 Data Cache Size:
L1 Instruction Cache Size:
L2 Cache Size:
L2 Cache Line Size:
L2 Cache Associativity:
L3 Cache Size:
Stepping:
Model:
Family: 6
Processor Type:
Flags: acpi, aes, apic, clfsh, cmov, cx16, cx8, de, ds, dscpl, dtse64, est, fpu, fxsr, htt, mca, mce, mmx, mon, msr, mtrr, pae, pat, pbe, pclmulqdq, pdcm, pge, pse, pse36, seglim64, sep, ss, sse, sse2, sse3, sse4.1, sse4.2, ssse3, tm, tm2, tpr, tsc, vme, vmx
```
Benchmark results for rollup of mass properties and uncertainties were taken with and without input validation:
```{r eval=FALSE}
benchmark('mp + unc no validation' = rollup_mass_props_and_unc_fast(mp_tree, mp_table),
'mp + unc validation' = rollup_mass_props_and_unc(mp_tree, mp_table),
'mp no validation' = rollup_mass_props_fast(mp_tree, mp_table),
'mp validation' = rollup_mass_props(mp_tree, mp_table),
replications = 1,
columns = c("test", "replications", "elapsed", "user.self", "sys.self")
)
```
Times reported are in seconds.
```
test replications elapsed user.self sys.self
4 mp validation 1 0.840 0.824 0.016
3 mp no validation 1 0.604 0.594 0.011
2 mp + unc validation 1 1.479 1.454 0.026
1 mp + unc no validation 1 0.993 0.974 0.019
```
# References