init

enriched-qwen3-coder-next/Common/DTS.Common.Calculations.md

@@ -0,0 +1,114 @@
+---
+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-16T14:13:55.996245+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 in biomechanical analysis contexts. It contains data structures for holding filtered channel data (`ChannelData`), numerical integration via trapezoidal summation (`Integral`), resultant vector computation from multiple input channels (`Resultant`), and Head Injury Criterion (HIC) calculation used in impact testing scenarios (`HeadInjuryCriterion`). The module is designed to work with pre-filtered engineering unit data sampled at consistent rates.
+
+---
+
+## 2. Public Interface
+
+### `ChannelData` (Class)
+**Namespace:** `DTS.Common.Calculations`
+
+Simple data container for filtered channel data.
+
+| Member | Signature | Description |
+|--------|-----------|-------------|
+| `Units` | `public string Units { get; }` | Read-only engineering units of the data. Set via constructor. |
+| `FilteredEU` | `public double[] FilteredEU { get; set; }` | Pre-filtered engineering unit data array. Mutable. |
+| Constructor | `public ChannelData(string units)` | Constructs a new `ChannelData` instance with the specified units. `FilteredEU` is not initialized by constructor. |
+
+---
+
+### `Integral` (Static Class)
+**Namespace:** `DTS.Common.Calculations`
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `DefiniteIntegral` | `public 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 (divisor for time normalization). |
+
+---
+
+### `Resultant` (Static Class)
+**Namespace:** `DTS.Common.Calculations`
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `GenerateResultantChannel` | `public static ChannelData GenerateResultantChannel(List<ChannelData> channels)` | Computes the resultant vector from multiple input channels using sum-of-squares: `√(Σ ch[i]²)`. Returns a new `ChannelData` with the resultant values. Units are taken from the first input channel. |
+
+---
+
+### `HeadInjuryCriterion` (Static Class)
+**Namespace:** `DTS.Common.Calculations`
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `GetHeadInjuryCriterion` | `public static HICResult GetHeadInjuryCriterion(ChannelData resultant, double SPS, int clipLengthMS)` | Calculates the maximum Head Injury Criterion over the input data for the specified clip length. Uses brute-force exhaustive search across all clip lengths from 1 sample up to `clipLengthMS`. |
+
+#### `HeadInjuryCriterion.HICResult` (Nested Class)
+
+| Member | Signature | Description |
+|--------|-----------|-------------|
+| `StartSample` | `public int StartSample { get; }` | Start sample index of the maximum HIC window. |
+| `EndSample` | `public int EndSample { get; }` | End sample index of the maximum HIC window. |
+| `HicLengthMS` | `public int HicLengthMS { get; }` | Length of the HIC window in milliseconds. |
+| `HIC` | `public double HIC { get; }` | The calculated HIC value. |
+| Constructor | `public HICResult(double hic, int hicLength, int startSample, int endSample)` | Constructs a new `HICResult`. Note: parameter order is `hic`, `hicLength`, `startSample`, `endSample`. |
+
+---
+
+## 3. Invariants
+
+- **`ChannelData.Units`** is immutable after construction; it can only be set via the constructor.
+- **`ChannelData.FilteredEU`** is not initialized by the constructor and must be set before use.
+- **`Integral.DefiniteIntegral`** assumes input data is tightly time-aligned (uniform sampling interval).
+- **`Resultant.GenerateResultantChannel`** requires all input channels to have identical `FilteredEU.Length` values.
+- **`Resultant.GenerateResultantChannel`** requires all input channels to have identical `Units` values.
+- **`HeadInjuryCriterion.GetHeadInjuryCriterion`** requires `SPS > 0` and `clipLengthMS > 0`.
+- **`HeadInjuryCriterion.GetHeadInjuryCriterion`** requires `resultant.FilteredEU.Length` to be at least as many samples as `clipLengthMS` represents at the given `SPS`.
+
+---
+
+## 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()`, `Select()`)
+- `System.Diagnostics` (for `Trace.Assert`)
+
+### What depends on this module:
+- **Unclear from source alone** — no internal module references indicate consumers. This appears to be a low-level calculation library intended for use by higher-level analysis or data processing modules.
+
+---
+
+## 5. Gotchas
+
+1. **`HICResult` constructor parameter order differs from property order**: The constructor signature is `(double hic, int hicLength, int startSample, int endSample)`, but the XML documentation comments incorrectly describe the parameters in a different order. The actual parameter mapping is:
+   - `hic` → `HIC`
+   - `hicLength` → `HicLengthMS`
+   - `startSample` → `StartSample`
+   - `endSample` → `EndSample`
+
+2. **Assertions in production code**: Both `Resultant.GenerateResultantChannel` and `HeadInjuryCriterion.GetHeadInjuryCriterion` use `System.Diagnostics.Trace.Assert` for input validation. These assertions may not throw exceptions in release builds depending on configuration, potentially allowing invalid states to propagate silently.
+
+3. **Brute-force HIC algorithm**: `GetHeadInjuryCriterion` uses an O(n²) brute-force approach, recalculating integrals exhaustively. The source explicitly acknowledges this inefficiency with a comment: *"we can do this much better without a doubt, but lets get the first method done (brute force)"*.
+
+4. **`ChannelData.FilteredEU` is unset after construction**: The constructor only sets `Units`. Callers must manually assign `FilteredEU` after instantiation, or the property will be `null`.
+
+5. **`Integral.DefiniteIntegral` boundary behavior**: The loop iterates from `start + 1` to `end - 1` (exclusive of `end`), then adds `input[start]` and `input[end]` separately. This is correct trapezoidal integration but may be counterintuitive compared to typical half-open interval patterns in C#.
+
+6. **Future parallelization comment in `Resultant`**: The source contains a comment indicating intent to parallelize the loop in a future version, noting that `values.Add` would need to be replaced with an indexer. Current implementation is single-threaded.