# -*- coding: utf-8 -*-
"""
Native Reader Configurations
============================
Centralized configuration definitions for native (C++/Fortran) file readers.
Why this module exists
----------------------
Native readers typically require *structured metadata* describing how raw
files should be interpreted at the binary or token level. While the actual
parsing logic lives in compiled extensions for performance reasons, the
**semantic meaning of the input data belongs in Python**.
Keeping all native reader configurations in one place provides:
- A single source of truth for native input schemas
- Clear documentation of the Python ↔ native contract
- Stable, reviewable definitions that users can understand and extend
- A natural entry point for documentation and validation
- A clean separation between *what* is read and *how* it is read
This module is intentionally lightweight and declarative.
Design principles
-----------------
- No I/O
- No native imports
- No side effects
- Pure, inspectable Python data structures
- Fully documented public API
These configurations are consumed by native readers such as
``read_ascii_csv`` and ``read_ascii_csv_mt`` via the native bridge.
"""
[docs]
def get_motor_measurement_csv_structure():
"""
Return the column schema for motor measurement ASCII CSV files.
This structure defines the **exact contract** expected by the native
CSV readers. Each entry describes how a column should be interpreted
when parsing the file at native speed.
Column specification format
----------------------------
Each column is defined as a list with three elements::
[column_name, is_string, skip]
where:
- **column_name** : str
Name of the output field as exposed to Python. This will become
a key in the returned dictionary from the native reader.
- **is_string** : bool
Whether the column should be interpreted as a string.
Numerical columns must set this to ``False``.
- **skip** : bool
Whether the column should be skipped entirely during parsing.
This allows the native reader to efficiently ignore unused columns
without modifying the file format.
Notes
-----
- All numerical values are returned as ``float64`` NumPy arrays.
- Column order **must match** the order in the CSV file.
- Header handling is controlled separately by the reader call.
- This structure is intentionally explicit to avoid ambiguity
and silent parsing errors.
Returns
-------
list[list]
A list of column specifications defining the native CSV schema.
Examples
--------
>>> structure = get_motor_measurement_csv_structure()
>>> name, is_string, skip = structure[0]
>>> name
'u_q'
See Also
--------
read_ascii_csv
read_ascii_csv_mt
"""
csv_structure = [
["u_q", False, False],
["coolant", False, False],
["stator_winding", False, False],
["u_d", False, False],
["stator_tooth", False, False],
["motor_speed", False, False],
["i_d", False, False],
["i_q", False, False],
["pm", False, False],
["stator_yoke", False, False],
["ambient", False, False],
["torque", False, False],
["profile_id", False, False],
]
return csv_structure