Merge pull request #27 from snu-hanaro/feat/mandatory-loadcell-config

Feat/mandatory loadcell config

Author: yunseo-kim

examples/config.xlsx

@@ -1,3 +1,20 @@
+# global_config.py
+# ------------------ Required ------------------
+# ------------ Load Cell Parameters ------------
+# gain = gain_offset + (gain_internal_resistance_kohm * 1000)[Ω] / gain_resistance[Ω]
+# bridge_output_mv [mV] = sensitivity_mv_per_v[mV/V] * excitation_voltage[V] * thrust[N] / (rated_capacity_kgf[kgf] * g[N/kgf])
+# measured_output_v = (bridge_output_mv / 1000)[V] * gain
+# thrust[N] = (bridge_output_mv / sensitivity_mv_per_v)[V] / excitation_voltage[V] * (rated_capacity_kgf * g)[N]
+#           = (measured_output_v * 1000 / gain)[mV] / sensitivity_mv_per_v[mV/V] / excitation_voltage[V]
+#              * (rated_capacity_kgf * g)[N]
+rated_capacity_kgf = 500  # 정격하중: rated capacity of load cell, kgf
+sensitivity_mv_per_v = 3  # 감도: sensitivity of load cell, mV/V
+gain_internal_resistance_kohm = (
+    49.4  # amplifier-specific internal resistor of load cell, kΩ
+)
+gain_offset = 1  # gain offset of load cell, V
+
+# ------------------ Optional ------------------
 # ----------- Thrust Data Processing -----------
 thrust_sep = "[,\t]"  # separator for thrust data, character or Regex
 thrust_header = None  # header for thrust data (row number or None)
@@ -9,9 +26,6 @@
 pressure_time_col_idx = 0  # index of datetime column
 pressure_col_idx = 2  # index of pressure column
 # ------------ Global Configuration ------------
-g = 9.80665  # gravitational acceleration, m/s^2
-rated_load = 500  # rated load of load cell, kgf
-rated_output = 3  # rated output of load cell, V
 frequency = 100  # Sampling rate, Hz
 cutoff_frequency = 30  # LPF, Hz
 gaussian_strong_sigma = 10  # sigma for strong gaussian filter

examples/global_config.py

@@ -54,16 +54,35 @@ def _load_config(execution_root: Path, expt_name: str | None) -> dict[str, Any]:
         "totalmass [g]",
         "Nozzlediameter [mm]",
         "segment",
-        "expt_input_voltage [V]",
+        # Accept both legacy and new column names for excitation voltage
+        # either "expt_excitation_voltage [V]" or legacy "expt_input_voltage [V]"
+        "expt_excitation_voltage [V]",
         "expt_resistance [Ohm]",
     ]
     missing = [col for col in required_columns if col not in config.columns]
+    # Backward-compat: if the only missing item is the new excitation voltage column,
+    # but the legacy column exists, treat as satisfied.
+    if (
+        "expt_excitation_voltage [V]" in missing
+        and "expt_input_voltage [V]" in config.columns
+    ):
+        missing = [col for col in missing if col != "expt_excitation_voltage [V]"]
     if missing:
         raise ValueError(f"Missing columns in configuration: {missing}")
 
+    # Backward-compatible read for excitation voltage
+    if "expt_excitation_voltage [V]" in config.columns:
+        expt_excitation_voltage = config["expt_excitation_voltage [V]"][idx]
+    elif "expt_input_voltage [V]" in config.columns:
+        expt_excitation_voltage = config["expt_input_voltage [V]"][idx]
+    else:
+        raise ValueError(
+            "Missing excitation voltage column in configuration: expected 'expt_excitation_voltage [V]' or legacy 'expt_input_voltage [V]'"
+        )
+
     return {
         "expt_file_name": config["expt_file_name"][idx],
-        "expt_input_voltage": config["expt_input_voltage [V]"][idx],
+        "expt_excitation_voltage": expt_excitation_voltage,
         "expt_resistance": config["expt_resistance [Ohm]"][idx],
         "grain": {
             "OD": float(config["Outerdiameter [mm]"][idx]),
@@ -130,7 +149,7 @@ def cmd_thrust(args: argparse.Namespace) -> None:
     proc = ThrustPostProcess(
         data_raw=thrust_raw,
         file_name=cfg["expt_file_name"],
-        input_voltage=cfg["expt_input_voltage"],
+        excitation_voltage=cfg["expt_excitation_voltage"],
         resistance=cfg["expt_resistance"],
         execution_root=str(exec_root),
     )
@@ -209,7 +228,7 @@ def cmd_process(args: argparse.Namespace) -> None:
     thrust_proc = ThrustPostProcess(
         data_raw=thrust_raw,
         file_name=cfg["expt_file_name"],
-        input_voltage=cfg["expt_input_voltage"],
+        excitation_voltage=cfg["expt_excitation_voltage"],
         resistance=cfg["expt_resistance"],
         execution_root=str(exec_root),
     )

src/static_fire_toolkit/cli.py

@@ -24,16 +24,21 @@
 class Config:
     """Runtime configuration values used by processing modules."""
 
-    rated_output: float = 3.0  # rated output of load cell, V
-    rated_load: float = 500.0  # rated load of load cell, kgf
-    g: float = 9.80665  # gravitational acceleration, m/s^2
+    # Load cell & acquisition (must be explicitly set by user)
+    sensitivity_mv_per_v: float | None = None  # load cell sensitivity (mV/V)
+    rated_capacity_kgf: float | None = None  # load cell rated capacity (kgf)
+    gain_internal_resistance_kohm: float | None = (
+        None  # amplifier internal resistance (kOhm)
+    )
+    gain_offset: float | None = None  # amplifier gain offset (volts)
+    # Other parameters
     frequency: float = 100.0  # Sampling rate, Hz (Δt = 0.01 s)
-    cutoff_frequency: float = 10.0  # Hz for LPF
+    cutoff_frequency: float = 30.0  # Hz for LPF
     lowpass_order: int = 5  # order for lowpass filter
-    gaussian_weak_sigma: float = 2.0  # sigma for weak gaussian filter
-    gaussian_strong_sigma: float = 8.0  # sigma for strong gaussian filter
-    start_criteria: float = 0.15  # Criteria for the starting point of a meaningful interval in thrust data processing
-    end_criteria: float = 0.15  # Criteria for the ending point of a meaningful interval in thrust data processing
+    gaussian_weak_sigma: float = 1.5  # sigma for weak gaussian filter
+    gaussian_strong_sigma: float = 10.0  # sigma for strong gaussian filter
+    start_criteria: float = 0.2  # Criteria for the starting point of a meaningful interval in thrust data processing
+    end_criteria: float = 0.1  # Criteria for the ending point of a meaningful interval in thrust data processing
     thrust_sep: str = ","  # separator for thrust data, character or Regex
     thrust_header: int | None = 0  # header for thrust data (row number or None)
     thrust_time_col_idx: int = 0  # index of time column
@@ -59,10 +64,31 @@ def _load_from_python(path: Path, base: Config) -> Config:
     if spec and spec.loader:
         mod = module_from_spec(spec)
         spec.loader.exec_module(mod)  # type: ignore[reportAttributeAccessIssue]
+        # Backward-compatible mapping from legacy names
+        sensitivity = _read_attr(mod, "sensitivity_mv_per_v", base.sensitivity_mv_per_v)
+        if sensitivity == base.sensitivity_mv_per_v:
+            sensitivity = _read_attr(mod, "rated_output", sensitivity)
+
+        rated_capacity = _read_attr(mod, "rated_capacity_kgf", base.rated_capacity_kgf)
+        if rated_capacity == base.rated_capacity_kgf:
+            rated_capacity = _read_attr(mod, "rated_load", rated_capacity)
+
+        gain_internal_res_kohm = _read_attr(
+            mod, "gain_internal_resistance_kohm", base.gain_internal_resistance_kohm
+        )
+        gain_offset = _read_attr(mod, "gain_offset", base.gain_offset)
+
         return Config(
-            rated_output=float(_read_attr(mod, "rated_output", base.rated_output)),
-            rated_load=float(_read_attr(mod, "rated_load", base.rated_load)),
-            g=float(_read_attr(mod, "g", base.g)),
+            sensitivity_mv_per_v=(None if sensitivity is None else float(sensitivity)),
+            rated_capacity_kgf=(
+                None if rated_capacity is None else float(rated_capacity)
+            ),
+            gain_internal_resistance_kohm=(
+                None
+                if gain_internal_res_kohm is None
+                else float(gain_internal_res_kohm)
+            ),
+            gain_offset=(None if gain_offset is None else float(gain_offset)),
             frequency=float(_read_attr(mod, "frequency", base.frequency)),
             cutoff_frequency=float(
                 _read_attr(mod, "cutoff_frequency", base.cutoff_frequency)

src/static_fire_toolkit/config_loader.py

@@ -56,7 +56,7 @@ def __init__(
         self,
         data_raw: pd.DataFrame,
         file_name: str,
-        input_voltage: float,
+        excitation_voltage: float,
         resistance: float,
         execution_root: str | None = None,
     ) -> None:
@@ -65,7 +65,7 @@ def __init__(
         Args:
             data_raw (pd.DataFrame): Raw data containing time and thrust measurements.
             file_name (str): File name identifier.
-            input_voltage (float): Input voltage used during measurement.
+            excitation_voltage (float): Excitation voltage used during measurement.
             resistance (float): Resistance value used during measurement.
             execution_root (str | None): Base directory for logs/ and results/*.
                 If None, defaults to current working directory.
@@ -79,9 +79,11 @@ def __init__(
 
         # Load configuration parameters explicitly
         self._CFG = load_global_config(self._EXEC_ROOT)
-        self._rated_output = self._CFG.rated_output
-        self._rated_load = self._CFG.rated_load
+        self._sensitivity_mv_per_v = self._CFG.sensitivity_mv_per_v
+        self._rated_capacity_kgf = self._CFG.rated_capacity_kgf
         self._g = 9.80665  # gravitational acceleration, m/s^2
+        self._gain_internal_resistance_kohm = self._CFG.gain_internal_resistance_kohm
+        self._gain_offset = self._CFG.gain_offset
         self._frequency = self._CFG.frequency
         self._cutoff_frequency = self._CFG.cutoff_frequency
         self._lowpass_order = self._CFG.lowpass_order
@@ -155,7 +157,7 @@ def __init__(
         ].copy()
         self._data_raw.columns = ["time", "thrust"]
         self._file_name: str = file_name
-        self._input_voltage: float = input_voltage
+        self._excitation_voltage: float = excitation_voltage
         self._resistance: float = resistance
 
         self._logger.info("0. Initialization complete.")
@@ -200,14 +202,38 @@ def _convert_voltage_to_thrust(self, data: pd.DataFrame) -> pd.DataFrame:
         """
         self._logger.info("   1-1. Converting voltage to thrust.")
         try:
+            # Validate required config parameters
+            missing_params: list[str] = []
+            if self._sensitivity_mv_per_v is None:
+                missing_params.append("sensitivity_mv_per_v")
+            if self._rated_capacity_kgf is None:
+                missing_params.append("rated_capacity_kgf")
+            if self._gain_internal_resistance_kohm is None:
+                missing_params.append("gain_internal_resistance_kohm")
+            if self._gain_offset is None:
+                missing_params.append("gain_offset")
+            if missing_params:
+                self._logger.error(
+                    "Missing required load cell config: %s", ", ".join(missing_params)
+                )
+                raise ValueError(
+                    "Missing required load cell configuration: "
+                    + ", ".join(missing_params)
+                )
             # 전압 값을 추력으로 변환
+            # Convert volts -> thrust(N) using sensitivity (mV/V), capacity(kgf), excitation voltage(V),
+            # amplifier internal resistance (kOhm) and gain offset.
+            # Formula adapted to new config naming; assumes linear behavior.
             data["thrust"] = (
                 data["thrust"]
                 * 1000
-                / (self._rated_output * self._input_voltage)
-                * self._rated_load
+                / (self._sensitivity_mv_per_v * self._excitation_voltage)
+                * self._rated_capacity_kgf
                 * self._g
-                / (1 + 49.4 * 1000 / self._resistance)
+                / (
+                    self._gain_offset
+                    + self._gain_internal_resistance_kohm * 1000 / self._resistance
+                )
             )
         except Exception as e:
             self._logger.error("Error converting voltage to thrust: %s", e)
@@ -636,10 +662,12 @@ def _thrust_plot(self) -> None:
             )
 
             ax.annotate(
-                "Impulse            " + str(round(self._impulse, 2)) + " Ns\n"
-                "Input Voltage   " + str(round(self._input_voltage, 2)) + " V\n"
-                "Resistance       " + str(round(self._resistance, 2)) + r" $\Omega$",
-                xy=(0.72, 0.85),
+                "Impulse                 " + str(round(self._impulse, 2)) + " Ns\n"
+                "Excitation Voltage " + str(round(self._excitation_voltage, 2)) + " V\n"
+                "Resistance            "
+                + str(round(self._resistance, 2))
+                + r" $\Omega$",
+                xy=(0.67, 0.85),
                 xycoords="axes fraction",
                 size=20,
                 font="Arial",
@@ -707,7 +735,15 @@ def run(self) -> pd.DataFrame:
     config = pd.read_excel(config_path, sheet_name=0, header=0, index_col=0)
     idx = len(config) - 1
     expt_file_name = config["expt_file_name"][idx]
-    expt_input_voltage = config["expt_input_voltage [V]"][idx]
+    # Backward-compatible: read excitation voltage from new or legacy column
+    if "expt_excitation_voltage [V]" in config.columns:
+        expt_excitation_voltage = config["expt_excitation_voltage [V]"][idx]
+    elif "expt_input_voltage [V]" in config.columns:
+        expt_excitation_voltage = config["expt_input_voltage [V]"][idx]
+    else:
+        raise ValueError(
+            "Missing excitation voltage column: expected 'expt_excitation_voltage [V]' or legacy 'expt_input_voltage [V]'"
+        )
     expt_resistance = config["expt_resistance [Ohm]"][idx]
 
     print(f"Loaded configuration for experiment: {expt_file_name}")
@@ -738,6 +774,6 @@ def run(self) -> pd.DataFrame:
     print("Successfully loaded input data file.")
 
     process = ThrustPostProcess(
-        thrust_data, expt_file_name, expt_input_voltage, expt_resistance
+        thrust_data, expt_file_name, expt_excitation_voltage, expt_resistance
     )
     _ = process.run()