README.Rmd

---
output: github_document
bibliography: vignettes/references.bib
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# massProps

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/massProps)](https://CRAN.R-project.org/package=massProps)
[![R-CMD-check](https://github.com/jsjuni/massProps/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/jsjuni/massProps/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/jsjuni/massProps/graph/badge.svg)](https://app.codecov.io/gh/jsjuni/massProps)
<!-- badges: end -->

The `massProps` package extends `rollupTree` with functions to recursively calculate mass properties (and optionally, their uncertainties) for arbitrary composition trees. Formulas implemented are described in a technical paper published by the Society of Allied Weight Engineers [@zimmerman:05:sawe].

## Installation

```{r eval = FALSE}
install.packages("massProps")
```

You can install the development version of massProps from [GitHub](https://github.com/) with:

``` r
# install.packages("pak")
pak::pak("jsjuni/massProps")
```

## Example

```{r echo = FALSE}
suppressPackageStartupMessages({library(igraph)})
```

Suppose we have the following mass properties table:

```{r}
library(massProps)
test_table
```

`POIconv` indicates the products of inertia sign convention. In the negative convention, for example, $I_{XY} \equiv -\int{xy \rho \, dV}$. In the positive convention, $I_{XY} \equiv \int{xy \rho \, dV}$.

`Ipoint` indicates whether this object is to be considered a point mass. 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.

We construct a graph with edges representing child-parent relations:

```{r}
library(igraph)
E(test_tree)
```
```{r echo = FALSE}
plot(test_tree,layout=layout_as_tree(test_tree, 2, mode="in"), vertex.shape = 'none', edge.arrow.mode = 0)
```

We can roll up mass properties to non-leaf elements as follows:

```{r}
rollup_mass_props(test_tree, test_table)
```

Note that, although the table shows the parent of each element for clarity of exposition, the child-parent relations are coneveyed *only* by the tree passed as the first argument.

The input data may include mass properties uncertainties as well:

```{r}
test_unc_table
```

Mass properties and their uncertainties can be rolled up as follows:

```{r}
rollup_mass_props_and_unc(test_tree, test_unc_table)
```

## References