pyelectrochemreader 0.1.0__py3-none-any.whl

pyelectrochemreader/__init__.py

@@ -0,0 +1,8 @@
+"""Read electrochemical files using only Python and NumPy."""
+
+from .core import Dataset, Experiment, ReadError, UnsupportedFormatError
+from .reader import read, supported_formats
+
+__version__ = "0.1.0"
+__all__ = ["read", "supported_formats", "Dataset", "Experiment", "ReadError",
+           "UnsupportedFormatError"]

pyelectrochemreader/_biologic_columns.py

@@ -0,0 +1,143 @@
+"""Bio-Logic column layouts, adapted from Galvani (modified 2026-11-02).
+
+SPDX-FileCopyrightText: 2013-2020 Christopher Kerr, "bcolsen"
+SPDX-License-Identifier: GPL-3.0-or-later
+"""
+import numpy as np
+
+VMPdata_colID_dtype_map = {
+    4: ("time/s", "<f8"),
+    5: ("control/V/mA", "<f4"),
+    6: ("Ewe/V", "<f4"),
+    7: ("dq/mA.h", "<f8"),
+    8: ("I/mA", "<f4"),  # 8 is either I or <I> ??
+    9: ("Ece/V", "<f4"),
+    11: ("<I>/mA", "<f8"),
+    13: ("(Q-Qo)/mA.h", "<f8"),
+    16: ("Analog IN 1/V", "<f4"),
+    17: ("Analog IN 2/V", "<f4"),  # Probably column 18 is Analog IN 3/V, if anyone hits this error in the future  # noqa: E501
+    19: ("control/V", "<f4"),
+    20: ("control/mA", "<f4"),
+    23: ("dQ/mA.h", "<f8"),  # Same as 7?
+    24: ("cycle number", "<f8"),
+    26: ("Rapp/Ohm", "<f4"),
+    27: ("Ewe-Ece/V", "<f4"),
+    32: ("freq/Hz", "<f4"),
+    33: ("|Ewe|/V", "<f4"),
+    34: ("|I|/A", "<f4"),
+    35: ("Phase(Z)/deg", "<f4"),
+    36: ("|Z|/Ohm", "<f4"),
+    37: ("Re(Z)/Ohm", "<f4"),
+    38: ("-Im(Z)/Ohm", "<f4"),
+    39: ("I Range", "<u2"),
+    69: ("R/Ohm", "<f4"),
+    70: ("P/W", "<f4"),
+    74: ("|Energy|/W.h", "<f8"),
+    75: ("Analog OUT/V", "<f4"),
+    76: ("<I>/mA", "<f4"),
+    77: ("<Ewe>/V", "<f4"),
+    78: ("Cs-2/µF-2", "<f4"),
+    96: ("|Ece|/V", "<f4"),
+    98: ("Phase(Zce)/deg", "<f4"),
+    99: ("|Zce|/Ohm", "<f4"),
+    100: ("Re(Zce)/Ohm", "<f4"),
+    101: ("-Im(Zce)/Ohm", "<f4"),
+    123: ("Energy charge/W.h", "<f8"),
+    124: ("Energy discharge/W.h", "<f8"),
+    125: ("Capacitance charge/µF", "<f8"),
+    126: ("Capacitance discharge/µF", "<f8"),
+    131: ("Ns", "<u2"),
+    163: ("|Estack|/V", "<f4"),
+    168: ("Rcmp/Ohm", "<f4"),
+    169: ("Cs/µF", "<f4"),
+    172: ("Cp/µF", "<f4"),
+    173: ("Cp-2/µF-2", "<f4"),
+    174: ("<Ewe>/V", "<f4"),
+    178: ("(Q-Qo)/C", "<f4"),
+    179: ("dQ/C", "<f4"),
+    182: ("step time/s", "<f8"),
+    211: ("Q charge/discharge/mA.h", "<f8"),
+    212: ("half cycle", "<u4"),
+    213: ("z cycle", "<u4"),
+    217: ("THD Ewe/%", "<f4"),
+    218: ("THD I/%", "<f4"),
+    220: ("NSD Ewe/%", "<f4"),
+    221: ("NSD I/%", "<f4"),
+    223: ("NSR Ewe/%", "<f4"),
+    224: ("NSR I/%", "<f4"),
+    230: ("|Ewe h2|/V", "<f4"),
+    231: ("|Ewe h3|/V", "<f4"),
+    232: ("|Ewe h4|/V", "<f4"),
+    233: ("|Ewe h5|/V", "<f4"),
+    234: ("|Ewe h6|/V", "<f4"),
+    235: ("|Ewe h7|/V", "<f4"),
+    236: ("|I h2|/A", "<f4"),
+    237: ("|I h3|/A", "<f4"),
+    238: ("|I h4|/A", "<f4"),
+    239: ("|I h5|/A", "<f4"),
+    240: ("|I h6|/A", "<f4"),
+    241: ("|I h7|/A", "<f4"),
+    242: ("|E2|/V", "<f4"),
+    271: ("Phase(Z1) / deg", "<f4"),
+    272: ("Phase(Z2) / deg", "<f4"),
+    301: ("|Z1|/Ohm", "<f4"),
+    302: ("|Z2|/Ohm", "<f4"),
+    331: ("Re(Z1)/Ohm", "<f4"),
+    332: ("Re(Z2)/Ohm", "<f4"),
+    361: ("-Im(Z1)/Ohm", "<f4"),
+    362: ("-Im(Z2)/Ohm", "<f4"),
+    391: ("<E1>/V", "<f4"),
+    392: ("<E2>/V", "<f4"),
+    422: ("Phase(Zstack)/deg", "<f4"),
+    423: ("|Zstack|/Ohm", "<f4"),
+    424: ("Re(Zstack)/Ohm", "<f4"),
+    425: ("-Im(Zstack)/Ohm", "<f4"),
+    426: ("<Estack>/V", "<f4"),
+    430: ("Phase(Zwe-ce)/deg", "<f4"),
+    431: ("|Zwe-ce|/Ohm", "<f4"),
+    432: ("Re(Zwe-ce)/Ohm", "<f4"),
+    433: ("-Im(Zwe-ce)/Ohm", "<f4"),
+    434: ("(Q-Qo)/C", "<f4"),
+    435: ("dQ/C", "<f4"),
+    438: ("step time/s", "<f8"),
+    441: ("<Ecv>/V", "<f4"),
+    462: ("Temperature/°C", "<f4"),
+    467: ("Q charge/discharge/mA.h", "<f8"),
+    468: ("half cycle", "<u4"),
+    469: ("z cycle", "<u4"),
+    471: ("<Ece>/V", "<f4"),
+    473: ("THD Ewe/%", "<f4"),
+    474: ("THD I/%", "<f4"),
+    476: ("NSD Ewe/%", "<f4"),
+    477: ("NSD I/%", "<f4"),
+    479: ("NSR Ewe/%", "<f4"),
+    480: ("NSR I/%", "<f4"),
+    486: ("|Ewe h2|/V", "<f4"),
+    487: ("|Ewe h3|/V", "<f4"),
+    488: ("|Ewe h4|/V", "<f4"),
+    489: ("|Ewe h5|/V", "<f4"),
+    490: ("|Ewe h6|/V", "<f4"),
+    491: ("|Ewe h7|/V", "<f4"),
+    492: ("|I h2|/A", "<f4"),
+    493: ("|I h3|/A", "<f4"),
+    494: ("|I h4|/A", "<f4"),
+    495: ("|I h5|/A", "<f4"),
+    496: ("|I h6|/A", "<f4"),
+    497: ("|I h7|/A", "<f4"),
+    498: ("Q charge/mA.h", "<f8"),
+    499: ("Q discharge/mA.h", "<f8"),
+    500: ("step time/s", "<f8"),
+    501: ("Efficiency/%", "<f8"),
+    502: ("Capacity/mA.h", "<f8"),
+    505: ("Rdc/Ohm", "<f4"),
+    509: ("Acir/Dcir Control", "<u1"),
+}
+
+VMPdata_colID_flag_map = {
+    1: ("mode", 0x03, np.uint8),
+    2: ("ox/red", 0x04, np.bool_),
+    3: ("error", 0x08, np.bool_),
+    21: ("control changes", 0x10, np.bool_),
+    31: ("Ns changes", 0x20, np.bool_),
+    65: ("counter inc.", 0x80, np.bool_),
+}

pyelectrochemreader/_neware_columns.py

@@ -0,0 +1,73 @@
+"""Neware scales and states from NewareNDA (modified 2026-11-02).
+Copyright (c) 2022-2024 SES AI Corporation. BSD-3-Clause; see licenses/NewareNDA.txt.
+"""
+
+state_dict = {
+    1: 'CC_Chg',
+    2: 'CC_DChg',
+    3: 'CV_Chg',
+    4: 'Rest',
+    5: 'Cycle',
+    7: 'CCCV_Chg',
+    8: 'CP_DChg',
+    9: 'CP_Chg',
+    10: 'CR_DChg',
+    13: 'Pause',
+    16: 'Pulse',
+    17: 'SIM',
+    19: 'CV_DChg',
+    20: 'CCCV_DChg',
+    21: 'Control',
+    22: 'OCV',
+    26: 'CPCV_DChg',
+    27: 'CPCV_Chg'
+}
+
+# Define field scaling based on instrument Range setting
+multiplier_dict = {
+    -100000000: 10,
+    -200000: 1e-2,
+    -100000: 1e-2,
+    -60000: 1e-2,
+    -30000: 1e-2,
+    -50000: 1e-2,
+    -20000: 1e-2,
+    -12000: 1e-2,
+    -10000: 1e-2,
+    -6000: 1e-2,
+    -5000: 1e-2,
+    -3000: 1e-2,
+    -2000: 1e-2,
+    -1000: 1e-2,
+    -500: 1e-3,
+    -100: 1e-3,
+    -50: 1e-4,
+    -25: 1e-4,
+    -20: 1e-4,
+    -10: 1e-4,
+    -5: 1e-5,
+    -2: 1e-5,
+    -1: 1e-5,
+    0: 0,
+    1: 1e-4,
+    2: 1e-4,
+    5: 1e-4,
+    10: 1e-3,
+    20: 1e-3,
+    50: 1e-3,
+    100: 1e-2,
+    200: 1e-2,
+    250: 1e-2,
+    500: 1e-2,
+    1000: 1e-1,
+    6000: 1e-1,
+    10000: 1e-1,
+    12000: 1e-1,
+    20000: 1e-1,
+    30000: 1e-1,
+    40000: 1e-1,
+    50000: 1e-1,
+    60000: 1e-1,
+    100000: 1e-1,
+    200000: 1e-1,
+}

pyelectrochemreader/_nrbf.py

@@ -0,0 +1,418 @@
+"""Small, safe decoder for the records used by NOVA BinaryFormatter files.
+
+This module decodes the wire representation into dictionaries and arrays.  It
+does not load .NET assemblies or instantiate any of the serialized classes.
+"""
+
+# SPDX-FileCopyrightText: 2026 OpenAI
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import struct
+
+import numpy as np
+
+
+class NRBFError(ValueError):
+    """Raised when an invalid or unsupported NRBF stream is encountered."""
+
+
+_RECORD_HEADER = 0
+_RECORD_CLASS_WITH_ID = 1
+_RECORD_SYSTEM_CLASS = 4
+_RECORD_CLASS = 5
+_RECORD_STRING = 6
+_RECORD_BINARY_ARRAY = 7
+_RECORD_PRIMITIVE = 8
+_RECORD_REFERENCE = 9
+_RECORD_NULL = 10
+_RECORD_END = 11
+_RECORD_LIBRARY = 12
+_RECORD_NULL_256 = 13
+_RECORD_NULL_MULTIPLE = 14
+_RECORD_PRIMITIVE_ARRAY = 15
+_RECORD_OBJECT_ARRAY = 16
+_RECORD_STRING_ARRAY = 17
+
+_TYPE_PRIMITIVE = 0
+_TYPE_SYSTEM_CLASS = 3
+_TYPE_CLASS = 4
+_TYPE_PRIMITIVE_ARRAY = 7
+
+_ARRAY_OFFSET_TYPES = (3, 4, 5)
+
+# These value-type arrays dominate the size of high-rate NOVA files.  NOVA
+# also serializes the corresponding calculated signal arrays, which are what
+# its own public API exposes.  Decode the records but do not retain them.
+_DISCARDED_ARRAY_CLASSES = (
+    "EcoChemie.Autolab.Adc164RawSample",
+    "EcoChemie.Autolab.Adc164RawCrSample",
+)
+
+_NUMPY_PRIMITIVES = {
+    1: "?",       # Boolean
+    2: "u1",      # Byte
+    6: "<f8",     # Double
+    7: "<i2",     # Int16
+    8: "<i4",     # Int32
+    9: "<i8",     # Int64
+    10: "i1",     # SByte
+    11: "<f4",    # Single
+    12: "<i8",    # TimeSpan
+    13: "<u8",    # DateTime
+    14: "<u2",    # UInt16
+    15: "<u4",    # UInt32
+    16: "<u8",    # UInt64
+}
+
+
+class NRBFParser:
+    """Decode one NRBF stream starting at *offset* in a bytes-like object."""
+
+    def __init__(self, data, offset=0):
+        self.data = memoryview(data)
+        self.offset = offset
+        self.objects = {}
+        self.libraries = {}
+        self.class_definitions = {}
+
+    def parse(self):
+        """Return the unresolved root object and stop just after MessageEnd."""
+        if self._u8() != _RECORD_HEADER:
+            raise self._error("stream does not start with an NRBF header")
+        root_id = self._i32()
+        self._i32()  # header id
+        major = self._i32()
+        minor = self._i32()
+        if (major, minor) != (1, 0):
+            raise self._error("unsupported NRBF version %d.%d" % (major, minor))
+
+        while self.offset < len(self.data):
+            record_offset = self.offset
+            record = self._u8()
+            if record == _RECORD_END:
+                return self.objects.get(root_id)
+            if record == _RECORD_LIBRARY:
+                self._read_library()
+            elif record == _RECORD_CLASS:
+                self._read_class(False)
+            elif record == _RECORD_SYSTEM_CLASS:
+                self._read_class(True)
+            elif record == _RECORD_CLASS_WITH_ID:
+                self._read_class_with_id()
+            elif record == _RECORD_STRING:
+                self._read_string()
+            elif record == _RECORD_PRIMITIVE_ARRAY:
+                self._read_primitive_array()
+            elif record == _RECORD_OBJECT_ARRAY:
+                self._read_object_array()
+            elif record == _RECORD_STRING_ARRAY:
+                self._read_object_array()
+            elif record == _RECORD_BINARY_ARRAY:
+                self._read_binary_array()
+            else:
+                raise self._error(
+                    "unsupported top-level record %d at offset %d"
+                    % (record, record_offset)
+                )
+        raise self._error("NRBF stream has no MessageEnd record")
+
+    def resolve(self, value):
+        """Resolve one MemberReference, without recursively copying a graph."""
+        seen = set()
+        while isinstance(value, dict) and set(value) == {"__ref__"}:
+            object_id = value["__ref__"]
+            if object_id in seen:
+                return None
+            seen.add(object_id)
+            value = self.objects.get(object_id)
+        return value
+
+    def _error(self, message):
+        return NRBFError("%s (offset %d)" % (message, self.offset))
+
+    def _read(self, size):
+        end = self.offset + size
+        if size < 0 or end > len(self.data):
+            raise self._error("unexpected end of file")
+        result = self.data[self.offset:end]
+        self.offset = end
+        return result
+
+    def _unpack(self, fmt):
+        size = struct.calcsize(fmt)
+        return struct.unpack_from(fmt, self._read(size))[0]
+
+    def _u8(self):
+        return self._unpack("<B")
+
+    def _i8(self):
+        return self._unpack("<b")
+
+    def _u16(self):
+        return self._unpack("<H")
+
+    def _i16(self):
+        return self._unpack("<h")
+
+    def _u32(self):
+        return self._unpack("<I")
+
+    def _i32(self):
+        return self._unpack("<i")
+
+    def _u64(self):
+        return self._unpack("<Q")
+
+    def _i64(self):
+        return self._unpack("<q")
+
+    def _f32(self):
+        return self._unpack("<f")
+
+    def _f64(self):
+        return self._unpack("<d")
+
+    def _string(self):
+        length = 0
+        shift = 0
+        while True:
+            byte = self._u8()
+            length |= (byte & 0x7f) << shift
+            if not byte & 0x80:
+                break
+            shift += 7
+            if shift > 35:
+                raise self._error("invalid length-prefixed string")
+        try:
+            return self._read(length).tobytes().decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise self._error("invalid UTF-8 string: %s" % exc)
+
+    def _primitive(self, primitive_type):
+        readers = {
+            1: self._u8,
+            2: self._u8,
+            6: self._f64,
+            7: self._i16,
+            8: self._i32,
+            9: self._i64,
+            10: self._i8,
+            11: self._f32,
+            12: self._i64,
+            13: self._u64,
+            14: self._u16,
+            15: self._u32,
+            16: self._u64,
+        }
+        if primitive_type == 1:
+            return bool(self._u8())
+        if primitive_type == 3:  # Char is UTF-8 encoded by BinaryFormatter.
+            first = self._u8()
+            if first < 0x80:
+                return chr(first)
+            count = 1 if first < 0xe0 else 2 if first < 0xf0 else 3
+            raw = bytes([first] + [self._u8() for unused in range(count)])
+            return raw.decode("utf-8")
+        if primitive_type == 5:  # Decimal is written as a string.
+            return self._string()
+        try:
+            return readers[primitive_type]()
+        except KeyError:
+            raise self._error("unsupported primitive type %d" % primitive_type)
+
+    def _read_library(self):
+        library_id = self._i32()
+        self.libraries[library_id] = self._string()
+
+    def _read_class_info(self):
+        object_id = self._i32()
+        name = self._string()
+        count = self._i32()
+        if count < 0 or count > 100000:
+            raise self._error("invalid class member count %d" % count)
+        names = [self._string() for unused in range(count)]
+        return object_id, name, names
+
+    def _read_type_info(self, count):
+        binary_types = [self._u8() for unused in range(count)]
+        additional = []
+        for binary_type in binary_types:
+            if binary_type in (_TYPE_PRIMITIVE, _TYPE_PRIMITIVE_ARRAY):
+                additional.append(self._u8())
+            elif binary_type == _TYPE_SYSTEM_CLASS:
+                additional.append(self._string())
+            elif binary_type == _TYPE_CLASS:
+                additional.append((self._string(), self._i32()))
+            elif binary_type in (1, 2, 5, 6):
+                additional.append(None)
+            else:
+                raise self._error("unsupported binary type %d" % binary_type)
+        return binary_types, additional
+
+    def _read_class(self, system_class):
+        object_id, name, names = self._read_class_info()
+        binary_types, additional = self._read_type_info(len(names))
+        if not system_class:
+            self._i32()  # library id
+        definition = (name, names, binary_types, additional)
+        self.class_definitions[object_id] = definition
+        obj = self._read_class_value(object_id, definition)
+        return obj
+
+    def _read_class_with_id(self):
+        object_id = self._i32()
+        metadata_id = self._i32()
+        try:
+            definition = self.class_definitions[metadata_id]
+        except KeyError:
+            raise self._error("unknown class metadata id %d" % metadata_id)
+        return self._read_class_value(object_id, definition)
+
+    def _read_class_value(self, object_id, definition):
+        name, names, binary_types, additional = definition
+        discard = name in _DISCARDED_ARRAY_CLASSES
+        if discard:
+            for binary_type, extra in zip(binary_types, additional):
+                self._read_value(binary_type, extra)
+            return None
+        values = [
+            self._read_value(binary_type, extra)
+            for binary_type, extra in zip(binary_types, additional)
+        ]
+        obj = dict(zip(names, values))
+        obj["__class__"] = name
+        self.objects[object_id] = obj
+        return obj
+
+    def _read_value(self, binary_type, additional):
+        if binary_type == _TYPE_PRIMITIVE:
+            return self._primitive(additional)
+        return self._read_inline()
+
+    def _read_inline(self):
+        record_offset = self.offset
+        record = self._u8()
+        if record == _RECORD_STRING:
+            return self._read_string()
+        if record == _RECORD_REFERENCE:
+            return {"__ref__": self._i32()}
+        if record == _RECORD_NULL:
+            return None
+        if record == _RECORD_CLASS:
+            obj = self._read_class(False)
+            return obj
+        if record == _RECORD_SYSTEM_CLASS:
+            return self._read_class(True)
+        if record == _RECORD_CLASS_WITH_ID:
+            return self._read_class_with_id()
+        if record == _RECORD_PRIMITIVE_ARRAY:
+            return self._read_primitive_array()
+        if record in (_RECORD_OBJECT_ARRAY, _RECORD_STRING_ARRAY):
+            return self._read_object_array()
+        if record == _RECORD_BINARY_ARRAY:
+            return self._read_binary_array()
+        if record == _RECORD_PRIMITIVE:
+            return self._primitive(self._u8())
+        if record == _RECORD_LIBRARY:
+            self._read_library()
+            return self._read_inline()
+        raise self._error(
+            "unsupported inline record %d at offset %d" % (record, record_offset)
+        )
+
+    def _read_string(self):
+        object_id = self._i32()
+        value = self._string()
+        self.objects[object_id] = value
+        return value
+
+    def _read_primitive_array(self):
+        object_id = self._i32()
+        length = self._i32()
+        primitive_type = self._u8()
+        value = self._primitive_values(length, primitive_type)
+        self.objects[object_id] = value
+        return value
+
+    def _primitive_values(self, length, primitive_type):
+        if length < 0:
+            raise self._error("negative array length")
+        dtype = _NUMPY_PRIMITIVES.get(primitive_type)
+        if dtype is None:
+            return np.asarray(
+                [self._primitive(primitive_type) for unused in range(length)]
+            )
+        dtype = np.dtype(dtype)
+        raw = self._read(length * dtype.itemsize)
+        return np.frombuffer(raw, dtype=dtype, count=length)
+
+    def _read_object_array(self):
+        object_id = self._i32()
+        length = self._i32()
+        value = self._read_array_values(length)
+        self.objects[object_id] = value
+        return value
+
+    def _read_array_values(self, length, discard=False):
+        if length < 0:
+            raise self._error("negative array length")
+        value = []
+        count = 0
+        while count < length:
+            record_offset = self.offset
+            record = self._u8()
+            if record == _RECORD_NULL:
+                null_count = 1
+            elif record == _RECORD_NULL_256:
+                null_count = self._u8()
+            elif record == _RECORD_NULL_MULTIPLE:
+                null_count = self._i32()
+            else:
+                self.offset = record_offset
+                item = self._read_inline()
+                if not discard:
+                    value.append(item)
+                count += 1
+                continue
+            if null_count < 0 or count + null_count > length:
+                raise self._error("invalid null run in array")
+            if not discard:
+                value.extend([None] * null_count)
+            count += null_count
+        return None if discard else value
+
+    def _read_binary_array(self):
+        object_id = self._i32()
+        array_type = self._u8()
+        rank = self._i32()
+        if rank < 1 or rank > 32:
+            raise self._error("invalid array rank %d" % rank)
+        lengths = [self._i32() for unused in range(rank)]
+        if any(length < 0 for length in lengths):
+            raise self._error("negative array length")
+        if array_type in _ARRAY_OFFSET_TYPES:
+            for unused in range(rank):
+                self._i32()
+        binary_type = self._u8()
+        additional = None
+        if binary_type in (_TYPE_PRIMITIVE, _TYPE_PRIMITIVE_ARRAY):
+            additional = self._u8()
+        elif binary_type == _TYPE_SYSTEM_CLASS:
+            additional = self._string()
+        elif binary_type == _TYPE_CLASS:
+            additional = (self._string(), self._i32())
+        elif binary_type not in (1, 2, 5, 6):
+            raise self._error("unsupported array binary type %d" % binary_type)
+
+        length = 1
+        for dimension in lengths:
+            length *= dimension
+        if binary_type == _TYPE_PRIMITIVE:
+            value = self._primitive_values(length, additional)
+        else:
+            class_name = additional[0] if binary_type == _TYPE_CLASS else additional
+            value = self._read_array_values(
+                length, discard=class_name in _DISCARDED_ARRAY_CLASSES
+            )
+        self.objects[object_id] = value
+        return value