Hysteresis Compensation

Calibration Provider

2 min read

The Calibration Provider system offers centralized management of calibration functions as UCAP DiscreteFunction parameters. It loads calibration data from CSV files packaged within sps-ucap-hysteresis-compensation and publishes them as proper UCAP parameters that can be subscribed to by other converters, enabling reusable and version-controlled calibration data management.

Trigger

SX.CZERO-CTML/StartCycle - Minimal dependency to satisfy UCAP ForwardedSubscriptionsEventDefinition requirements. The calibration function is essentially static data published once per cycle.

Configuration

Calibration File Path: "calibration_functions/SPS_MB_I2BDOT_CALIBRATION_FN_v6.csv"

  • Relative paths resolved from sps_ucap_hystcomp/ package directory
  • Absolute paths supported for external calibration files
  • CSV format with headers (automatically skipped with skiprows=1)

Path Resolution Logic

# Relative path: "calibration_functions/file.csv"
package_dir = pathlib.Path(__file__).parent.parent  # sps_ucap_hystcomp/
resolved_path = package_dir / calibration_path
 
# Absolute path: "/path/to/file.csv" 
# Used as-is without modification

CSV File Format

I_meas_A,B_dot_meas_T
-2.365234375,3.877794315e-04
139.889885200,3.879404963e-04  
160.000000000,3.879860347e-04
...

Column 1: Current values in Amperes Column 2: dB/dI calibration values in Tesla per Ampere Headers: Automatically skipped during loading

Output

Property: Acquisition - DiscreteFunction containing calibration data Device: UCAP.I2BDOT.CALIBRATION Data Structure:

  • x array: Current values (A)
  • y array: dB/dI values (T/A)
  • Current Dataset: 573 calibration points covering -2.4 to 6006.7 A range

Adding New Calibration Devices

To add additional calibration function providers:

1. Create Device Definition

# device_definitions_py/cs_ccr_ml004/pro/UCAP.NEW.CALIBRATION.py
device_definition = DeviceDefinition(
    name="UCAP.NEW.CALIBRATION",
    description="New calibration function provider",
    transformations=[
        EventToOneTransformationDefinition(
            event=ForwardedSubscriptionsEventDefinition(
                forwarded_subscriptions=[
                    PropertySubscriptionDefinition(
                        parameter="SX.CZERO-CTML/StartCycle",
                        selector="SPS.USER.ALL", 
                        alias="STARTCYCLE",
                        ignore_first_updates=True,
                    )
                ]
            ),
            converter=PythonUserCodeDefinition(
                module_name="sps_ucap_hystcomp.calibration_provider",
                configuration={
                    "calibration_file": "calibration_functions/new_calibration.csv"
                }
            ),
            published_property="Acquisition"
        )
    ]
)

2. Add Calibration Data

Place CSV file in sps_ucap_hystcomp/calibration_functions/new_calibration.csv

3. Update Package Configuration

Ensure pyproject.toml includes the new CSV:

[tool.setuptools.package-data]
sps_ucap_hystcomp = ["py.typed", "calibration_functions/*.csv"]

4. Subscribe to Calibration

Other converters can subscribe:

BufferedPropertySubscriptionDefinition(
    parameter="rda3://${NODE_ID}/UCAP.NEW.CALIBRATION/Acquisition",
    selector="SPS.USER.ALL",
    alias="NEW_CALIBRATION"
)

Packaging & Distribution

Calibration files are properly packaged via setuptools configuration and included in wheel distributions. This ensures calibration data travels with the code and works correctly in production environments without external file dependencies.

Benefits

  • Centralized Management: Single source of truth for calibration data
  • Version Control: Calibration functions versioned with code
  • Reusability: Multiple converters can subscribe to same calibration
  • UCAP Native: Calibration becomes proper UCAP parameter with full system integration
  • Easy Updates: Simply replace CSV file and regenerate device configurations

Dependencies

Graph View

Backlinks