DP44/enriched-partialglm/Common/DTS.Common.Calculations.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Calculations/ChannelData.cs Common/DTS.Common.Calculations/Integral.cs Common/DTS.Common.Calculations/Resultant.cs Common/DTS.Common.Calculations/HeadInjuryCriterion.cs	2026-04-16T11:35:26.354514+00:00	zai-org/GLM-5-FP8	1	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:

   /// <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.