---
source_files:
  - Common/DTS.Common.Calculations/ChannelData.cs
  - Common/DTS.Common.Calculations/Integral.cs
  - Common/DTS.Common.Calculations/Resultant.cs
  - Common/DTS.Common.Calculations/HeadInjuryCriterion.cs
generated_at: "2026-04-16T11:35:26.354514+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "2d2deac012cb62cf"
---

# DTS.Common.Calculations Module Documentation

## 1. Purpose

This module provides mathematical calculation utilities for signal processing, specifically focused on biomechanical injury analysis. It contains a data container class (`ChannelData`) for holding filtered time-series data with associated engineering units, and implements algorithms for numerical integration (`Integral`), vector resultant calculation (`Resultant`), and Head Injury Criterion computation (`HeadInjuryCriterion`). The module is designed to work with pre-filtered sensor data, particularly acceleration channels used in impact testing.

---

## 2. Public Interface

### `ChannelData` Class

A data container for holding filtered channel data with associated engineering units.

| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `ChannelData(string units)` | Constructs a new `ChannelData` instance with the specified engineering units. |
| `Units` | `string Units { get; }` | Read-only property returning the engineering units of the data. |
| `FilteredEU` | `double[] FilteredEU { get; set; }` | Gets or sets the pre-filtered engineering unit data array. |

---

### `Integral` Static Class

Provides numerical integration methods.

| Method | Signature | Description |
|--------|-----------|-------------|
| `DefiniteIntegral` | `static double DefiniteIntegral(double[] input, int start, int end, double SPS)` | Computes the definite integral of `input` from index `start` to `end` (both inclusive) using trapezoidal summation. `SPS` is samples per second (sample rate). Returns the integrated value. |

---

### `Resultant` Static Class

Provides vector resultant calculation from multiple input channels.

| Method | Signature | Description |
|--------|-----------|-------------|
| `GenerateResultantChannel` | `static ChannelData GenerateResultantChannel(List<ChannelData> channels)` | Generates a resultant channel by computing the square root of the sum of squares across all input channels at each sample index. Returns a new `ChannelData` with the resultant values. |

---

### `HeadInjuryCriterion` Static Class

Provides Head Injury Criterion (HIC) calculation for biomechanical analysis.

| Method | Signature | Description |
|--------|-----------|-------------|
| `GetHeadInjuryCriterion` | `static HICResult GetHeadInjuryCriterion(ChannelData resultant, double SPS, int clipLengthMS)` | Calculates the maximum Head Injury Criterion over the input `resultant` acceleration channel for the specified `clipLengthMS` duration. `SPS` is the actual sample rate in samples per second. Returns an `HICResult` containing the maximum HIC value and its location. |

#### `HICResult` Nested Class

A result container for HIC calculations.

| Property | Type | Description |
|----------|------|-------------|
| `StartSample` | `int` | The starting sample index of the maximum HIC window. |
| `EndSample` | `int` | The ending sample index of the maximum HIC window. |
| `HicLengthMS` | `int` | The HIC clip length in milliseconds. |
| `HIC` | `double` | The calculated maximum HIC value. |

| Constructor | Signature |
|-------------|-----------|
| `HICResult` | `HICResult(double hic, int hicLength, int startSample, int endSample)` |

---

## 3. Invariants

- **`Integral.DefiniteIntegral`**: The input data must be tightly time-aligned (uniform sampling interval). The method assumes constant spacing between samples, allowing division by `SPS` rather than computing variable time deltas.

- **`Resultant.GenerateResultantChannel`**: All channels in the input list must have:
  - Identical `FilteredEU` array lengths
  - Identical `Units` values
  
  These constraints are enforced via `Trace.Assert` calls.

- **`HeadInjuryCriterion.GetHeadInjuryCriterion`**:
  - `SPS` must be greater than 0
  - `clipLengthMS` must be greater than 0
  - The `resultant.FilteredEU` array must contain at least `clipLengthMS` worth of data (specifically, at least `maxclip` samples where `maxclip = Ceiling(clipLengthMS * SPS / 1000)`)

---

## 4. Dependencies

### This module depends on:
- `System` (for `Math`, `Convert`, `DateTime`-related types)
- `System.Collections.Generic` (for `List<T>`)
- `System.Linq` (for `Distinct()`, `Max()`, `First()`, `Count()`, `Select()`)
- `System.Diagnostics` (for `Trace.Assert`)

### What depends on this module:
- **Unclear from source alone** — no consumers are shown in the provided files. This appears to be a foundational calculation library intended for use by higher-level analysis modules.

---

## 5. Gotchas

1. **Assertion behavior in production**: All validation is performed using `System.Diagnostics.Trace.Assert`. By default, `Trace.Assert` only triggers a dialog in debug builds and may be silently ignored in release configurations depending on trace listener configuration. Invalid inputs may produce incorrect results rather than explicit failures in production.

2. **Brute-force HIC algorithm**: The `GetHeadInjuryCriterion` method uses an exhaustive brute-force approach, recalculating integrals repeatedly. The source explicitly acknowledges this inefficiency with the comment: *"we are exhaustively recalculating sums, we can do this much better without a doubt."* Performance may be poor for large datasets.

3. **Documentation typo in `HICResult` constructor**: The XML documentation comments for the constructor parameters have the descriptions for `endSample` and `startSample` swapped:
   ```csharp
   /// <param name="endSample">start sample of HIC</param>
   /// <param name="startSample">end sample of HIC</param>
   ```
   The actual parameter order is `(hic, hicLength, startSample, endSample)`.

4. **Future unit conversion not implemented**: The `ChannelData` class stores units but provides no unit conversion functionality. The comment indicates this is planned for future implementation.

5. **Potential parallelization opportunity**: The `Resultant.GenerateResultantChannel` method contains a comment indicating parallelization is planned for a future version, but the current implementation is single-threaded.