DP44/enriched-qwen3-coder-next/Common/DTS.Common.Serialization/Test/Module/Channel.md

---
source_files:
  - Common/DTS.Common.Serialization/Test/Module/Channel/IConvertable.cs
  - Common/DTS.Common.Serialization/Test/Module/Channel/ChannelWithMeta.cs
  - Common/DTS.Common.Serialization/Test/Module/Channel/DataArray.cs
generated_at: "2026-04-16T03:40:40.401644+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "6e59e4819411113f"
---

# Channel

## Documentation: `DTS.Serialization.Test.Module.Channel` Submodule

---

### 1. Purpose

This module defines core serialization abstractions for channel data within the DTS test data serialization framework. It provides interfaces and classes to represent channel metadata, raw data arrays, and conversion mechanisms between domain-specific objects and a canonical `Channel` representation used for persistence or transmission. The module serves as the foundational layer for serializing and deserializing time-series channel data—including scaling, timing, and unit-conversion metadata—into and from XML.

---

### 2. Public Interface

#### `IConvertable` Interface  
*(Nested in `DTS.Serialization.Test.Module.Channel`)*

- **`Channel ToDtsSerializationTestModuleChannel()`**  
  Converts the implementing object into a canonical `Channel` instance.

- **`void FromDtsSerializationTestModuleChannel(Channel channel)`**  
  Initializes the implementing object using data from a `Channel` instance.

> **Note**: This interface is intended to be implemented by domain objects that need to be serialized/deserialized as `Channel` instances. The interface name is intentionally misspelled (`IConvertable` instead of `IConvertible`) per source.

---

#### `ChannelWithMeta` Class  
*(Top-level in `DTS.Serialization`)*

- **`Channel Channel { get; }`**  
  The canonical channel object to be serialized.

- **`DataScaler Scaler { get; }`**  
  Scaling metadata associated with the channel.

- **`double SampleRate { get; }`**  
  Sample rate (in Hz) of the channel.

- **`double StartTime { get; }`**  
  Start time (in seconds) of the channel’s data.

- **`ChannelWithMeta(Channel channel, DataScaler scaler, double samplerate, double starttime)`**  
  Constructor initializing all properties.

- **`static double GetMinStartTime(double start, IList<ChannelWithMeta> channelsWithMeta)`**  
  Computes the earliest *common* start time across all provided channels and the given `start` offset. Uses `Math.Max(start, channelsWithMeta.Min(cwm => cwm.StartTime))`.  
  > **Comment in source**: “Start is a generally a negative value, so to get the value for the start time of the minimum common data set, run Max()”.

- **`static double GetMinStopTime(double stop, IList<ChannelWithMeta> channelsWithMeta)`**  
  Computes the latest *common* stop time across all channels. Uses:  
  `Math.Min(stop, min(cwm.StartTime + (cwm.Channel.PersistentChannelInfo.Length - 1) / cwm.SampleRate))`,  
  with intermediate casting to `decimal` to mitigate floating-point rounding errors.

---

#### `DataArray<DataType>` Class  
*(Nested in `DTS.Serialization.Test.Module.Channel`)*

- **`DataType[] Values { get; set; }`**  
  Underlying array of data values. Returns an empty array if uninitialized or null.

- **`double ScaleFactorMv { get; set; }`**  
  ADC-to-millivolt scaling factor.

- **`double MvPerEu { get; set; }`**  
  Sensitivity: millivolts per engineering unit.

- **`double ScaleFactorEU { get; set; }`**  
  EU scaling factor (unused in current XML schema per tags).

- **`bool UseEUScaleFactors { get; set; }`**  
  Flag indicating whether EU scale factors should be applied.

- **`short DataZeroLevel { get; set; }`**  
  Zero-level offset for ADC data.

- **`double UnitConversion { get; set; }`**  
  Unit conversion multiplier (default `1.0`).

- **`double Multiplier { get; set; }`**  
  General-purpose multiplier (default `1.0`).

- **`double UserOffsetEU { get; set; }`**  
  User-defined offset in engineering units (default `0.0`).

- **`DataArray()`**  
  Default constructor.

- **`DataArray(DataType[] values)`**  
  Constructor initializing `Values` with the provided array.

- **Implicit operator `List<DataType> → DataArray<DataType>`**  
  Converts a `List<DataType>` to `DataArray<DataType>`.

- **Implicit operator `DataArray<DataType> → List<DataType>`**  
  Converts `DataArray<DataType>` to `List<DataType>`.

- **`void WriteXml(XmlWriter writer)`**  
  Serializes the instance to XML with the following structure:
  ```xml
  <Data Length="N" Type="System.Double" ScaleFactorMv="..." SensitivityMvEu="...">
    <Datum Value="..." />
    ...
  </Data>
  ```
  Includes attributes for `Length`, `Type`, `ScaleFactorMv`, and `SensitivityMvEu`. Each datum is serialized as `<Datum Value="..."/>`.

- **`void ReadXml(XmlReader reader)`**  
  Deserializes XML into the instance. Requires:
  - `DataType` to have a public static `Parse(string)` method.
  - `DataType` to be constructible via `Activator.CreateInstance`.
  - XML to contain `Length`, `Type`, `ScaleFactorMv`, and `SensitivityMvEu` attributes.

- **`XmlSchema GetSchema()`**  
  Always returns `null`. Per comment: *“This method is never invoked during XML object serialization.”*

- **`bool Equals(object obj)`**  
  Memberwise equality test: compares `ScaleFactorMv`, `MvPerEu`, `Values.Length`, and element-wise `Values` equality.

- **`int GetHashCode()`**  
  Returns base hash code (no custom hashing implemented).

---

### 3. Invariants

- **`DataArray<DataType>`**  
  - `Values` is never `null` when accessed (returns empty array if uninitialized).
  - XML serialization/deserialization requires `DataType` to implement `Parse(string)` and be instantiable via `Activator.CreateInstance`.
  - `ScaleFactorMv` and `MvPerEu` are always serialized/deserialized as XML attributes (not child elements).
  - `DataZeroLevel`, `UseEUScaleFactors`, `UnitConversion`, `Multiplier`, `UserOffsetEU` are *not* serialized in XML (no corresponding XML tags), though they are properties.

- **`ChannelWithMeta`**  
  - `GetMinStartTime` and `GetMinStopTime` assume `StartTime` and `SampleRate` are non-negative and consistent across channels.
  - `GetMinStopTime` uses `decimal` arithmetic internally to avoid floating-point rounding artifacts.

- **`IConvertable`**  
  - Implementers must ensure `FromDtsSerializationTestModuleChannel` fully initializes the object from the `Channel` argument.
  - `ToDtsSerializationTestModuleChannel` must produce a fully populated `Channel` instance.

---

### 4. Dependencies

#### Imports/Usings
- `System`, `System.Collections.Generic`, `System.Linq` → used in `ChannelWithMeta`.
- `DTS.Common.DAS.Concepts` → provides `DataScaler` type (used in `ChannelWithMeta`).
- `System.Xml`, `System.Xml.Schema`, `System.Xml.Serialization` → used in `DataArray<DataType>`.
- `DTS.Common.Utilities`, `DTS.Common.Utilities.DotNetProgrammingConstructs` → provides `Exceptional` base class and `Property<T>` wrapper (used in `DataArray<DataType>`).

#### Known Dependencies
- `DTS.Serialization.Test.Module.Channel` (itself) — `ChannelWithMeta` references `Channel` and `PersistentChannelInfo.Length`.
- `DataScaler` — assumed to be defined in `DTS.Common.DAS.Concepts`.
- `Property<T>` — internal wrapper used for observable/validated properties in `DataArray<T>`.

#### Dependents (Inferred)
- Serialization/deserialization pipelines (e.g., XML writers/readers) that consume `DataArray<T>`.
- Higher-level serialization modules that use `IConvertable` to bridge domain objects and `Channel`.
- `ChannelWithMeta` consumers (e.g., file writers) that need to align multiple channels in time.

---

### 5. Gotchas

- **Typo in interface name**: `IConvertable` (not `IConvertible`) — likely historical.
- **`DataArray<T>` XML schema is incomplete**: Only `ScaleFactorMv` and `MvPerEu` are serialized; other properties (`ScaleFactorEU`, `DataZeroLevel`, etc.) are ignored in XML.
- **`GetSchema()` always returns `null`**: This is intentional per comment, but may confuse developers expecting a schema for validation.
- **Rounding mitigation in `GetMinStopTime`**: Uses `decimal` cast to avoid floating-point artifacts (e.g., `4.999999999999995` vs `5.0`), but this may be fragile if `StartTime` or `SampleRate` are very large/small.
- **`DataArray<T>` requires `Parse(string)`**: If `DataType` lacks a static `Parse(string)` method, `ReadXml` throws an exception.
- **`Values` property returns empty array if null**: This avoids null-reference exceptions but may mask uninitialized state.
- **Implicit conversions are one-way in practice**: While both implicit operators exist, `DataArray<T>` is not a `List<T>`—conversions copy data, not reference.

> **None identified from source alone** beyond the above.

--- 

*Documentation generated from provided source files. No external assumptions or API speculation applied.*