{
  "node": {
    "id": "block:battery-pack-soc-ekf",
    "type": "Block",
    "label": "Pack-average SOC EKF",
    "properties": {
      "id": "battery-pack-soc-ekf",
      "name": "Pack-average SOC EKF",
      "kind": "studio",
      "summary": "Homogeneous series-cell average observer. Voltage, resistance and observation slope scale by series count; output is an average, not individual cell SOC.",
      "behavior": "Estimates the average SOC of homogeneous series cells. Voltage, resistance and observation slope scale by series count. Predicts a charge or energy fraction from signed throughput and corrects it using terminal voltage and a calibrated fraction-to-OCV table. Scalar Joseph covariance updates preserve nonnegative variance. Invalid voltage measurements skip correction; flat OCV regions report limited observability. Adaptive variants bound an innovation-based voltage-noise estimate.",
      "ports": [
        {
          "name": "current",
          "direction": "input",
          "unit": "A",
          "description": "Series pack current; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "current"
        },
        {
          "name": "voltage",
          "direction": "input",
          "unit": "V",
          "description": "Measured pack voltage; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "voltage"
        },
        {
          "name": "valid",
          "direction": "input",
          "unit": "true / false",
          "description": "Voltage valid; scalar.",
          "shape": [],
          "elementType": "bool",
          "quantity": "dimensionless"
        },
        {
          "name": "reset",
          "direction": "input",
          "unit": "true / false",
          "description": "Reset; scalar.",
          "shape": [],
          "elementType": "bool",
          "quantity": "dimensionless"
        },
        {
          "name": "fraction",
          "direction": "output",
          "unit": "1 (fraction)",
          "description": "Average SOC; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "fraction"
        },
        {
          "name": "variance",
          "direction": "output",
          "unit": "1",
          "description": "Average SOC variance; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "dimensionless"
        },
        {
          "name": "innovation",
          "direction": "output",
          "unit": "V",
          "description": "Pack voltage innovation; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "voltage"
        },
        {
          "name": "gain",
          "direction": "output",
          "unit": "1",
          "description": "Correction gain; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "dimensionless"
        },
        {
          "name": "noise",
          "direction": "output",
          "unit": "1",
          "description": "Pack voltage-noise variance; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "dimensionless"
        },
        {
          "name": "status",
          "direction": "output",
          "unit": "1",
          "description": "Observer status; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "dimensionless"
        }
      ],
      "parameters": [
        {
          "key": "sampleTimeS",
          "label": "Sample interval (s)",
          "unit": "s",
          "default": 1,
          "description": "Positive sample interval. Initialization has zero elapsed time; subsequent accepted samples update memory."
        },
        {
          "key": "capacity",
          "label": "Charge capacity (Ah)",
          "unit": "Ah",
          "default": 2,
          "description": "Charge capacity (Ah). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "initialFraction",
          "label": "Initial SOC (0–1)",
          "unit": "0–1",
          "default": 0.75,
          "description": "Initial SOC (0–1). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "initialVariance",
          "label": "Initial fraction variance",
          "unit": "1",
          "default": 0.01,
          "description": "Initial fraction variance. This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "processNoise",
          "label": "Process variance rate (fraction²/s)",
          "unit": "fraction²/s",
          "default": 0,
          "description": "Process variance rate (fraction²/s). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "measurementNoise",
          "label": "Voltage measurement variance (V²)",
          "unit": "V²",
          "default": 0.04,
          "description": "Voltage measurement variance (V²). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "resistanceOhm",
          "label": "Series resistance (Ω)",
          "unit": "Ω",
          "default": 0.05,
          "description": "Series resistance (Ω). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "adaptationRate",
          "label": "Noise adaptation weight (0–1)",
          "unit": "0–1",
          "default": 0,
          "description": "Noise adaptation weight (0–1). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "minimumNoise",
          "label": "Minimum voltage variance (V²)",
          "unit": "V²",
          "default": 1e-06,
          "description": "Minimum voltage variance (V²). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "maximumNoise",
          "label": "Maximum voltage variance (V²)",
          "unit": "V²",
          "default": 1,
          "description": "Maximum voltage variance (V²). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "ocvTable",
          "label": "Open-circuit voltage table [SOC fraction, V]",
          "unit": "See field order",
          "default": [
            [
              0,
              3
            ],
            [
              1,
              4
            ]
          ],
          "description": "Open-circuit voltage table [SOC fraction, V]. Rows are ordered coordinate/value pairs; the first column must be strictly increasing."
        },
        {
          "key": "seriesCells",
          "label": "Number of series cells",
          "unit": "1",
          "default": 4,
          "description": "Number of series cells. This is an editable model input; the default belongs to the synthetic worked example."
        }
      ],
      "equations": [
        "innovation = Vmeasured - Vpredicted",
        "K = Ppredicted*H / (H^2*Ppredicted + R)",
        "fraction = predictedFraction + K*innovation",
        "P = (1-K*H)^2*Ppredicted + K^2*R",
        "Vpack,predicted = seriesCells * (OCV(averageSOC) - I*Rcell)"
      ],
      "example": {
        "title": "Pack-average SOC EKF worked example",
        "text": "Use the defaults below with Series pack current = 1 A, Measured pack voltage = 15 V, Voltage valid = 1 true / false, Reset = 0 true / false. At 0 s, Average SOC is 0.79 1 (fraction). Additional checks are listed below.",
        "url": "https://design.lemonergy.com/cosim.html?example=block-battery-pack-soc-ekf",
        "label": "Open Studio example",
        "checks": [
          {
            "port": "fraction",
            "atS": 0,
            "value": 0.79,
            "tolerance": 1e-08,
            "label": "Average SOC",
            "unit": "1 (fraction)"
          },
          {
            "port": "variance",
            "atS": 0,
            "value": 0.002,
            "tolerance": 1e-08,
            "label": "Average SOC variance",
            "unit": "1"
          },
          {
            "port": "innovation",
            "atS": 0,
            "value": 0.2,
            "tolerance": 1e-08,
            "label": "Pack voltage innovation",
            "unit": "V"
          },
          {
            "port": "gain",
            "atS": 0,
            "value": 0.2,
            "tolerance": 1e-08,
            "label": "Correction gain",
            "unit": "1"
          }
        ],
        "inputs": [
          {
            "port": "current",
            "label": "Series pack current",
            "value": 1,
            "unit": "A"
          },
          {
            "port": "voltage",
            "label": "Measured pack voltage",
            "value": 15,
            "unit": "V"
          },
          {
            "port": "valid",
            "label": "Voltage valid",
            "value": 1,
            "unit": "true / false"
          },
          {
            "port": "reset",
            "label": "Reset",
            "value": 0,
            "unit": "true / false"
          }
        ]
      },
      "limits": [
        "One-state extended Kalman observers, without an unscented transform, RC polarization states or automatic cell identification. SOE requires its own energy-fraction-to-OCV calibration. Synthetic filter settings are not accuracy guarantees.",
        "The estimate is a pack average, without independently estimated cell states.",
        "The example verifies numerical behavior for synthetic parameters. Cell characterization and validation for an intended use are separate tasks."
      ],
      "availability": {
        "status": "released",
        "label": "Available in Lemonergy Studio",
        "detail": "The bundled example is available in the production release verified on 28 October 2026. The parameters and examples here are synthetic teaching fixtures, not a characterized cell or a validated operating limit."
      },
      "references": [
        "plett-estimation",
        "plett-modeling"
      ],
      "evidence": [
        "docs/glossary/native-block-verification.json"
      ],
      "sourceRepository": "Lemonergy Studio public contract",
      "sourceRevision": "verification-2026-10-27",
      "caseIds": [
        "native-battery-pack-soc-ekf"
      ],
      "exampleTraces": [
        {
          "id": "battery-pack-soc-ekf",
          "url": "https://lemonergy.com/learn/glossary/api/traces/battery-pack-soc-ekf.json?v=bdbb2729551f",
          "title": "Pack-average SOC EKF recorded example",
          "exampleId": "block-battery-pack-soc-ekf",
          "source": "Executed synthetic Lemonergy Studio example",
          "recordedOn": "2026-10-28",
          "points": 2,
          "channels": 6,
          "omittedChannels": 0,
          "interpolation": "step",
          "solver": {
            "method": "dormand-prince-45",
            "reason": "no-continuous-states"
          }
        }
      ],
      "type": "battery-pack-soc-ekf",
      "implementationId": "battery-pack-soc-ekf",
      "url": "https://lemonergy.com/learn/glossary/blocks/battery-pack-soc-ekf/",
      "documentationUrl": "https://lemonergy.com/learn/glossary/blocks/battery-pack-soc-ekf/",
      "sourceFile": "block-library.json",
      "reviewed": "2026-10-27",
      "releaseEvidence": {
        "environment": "production",
        "status": "verified",
        "revision": "e76cadfc203e15eb41f3478d8b1044a5b851953d",
        "verifiedOn": "2026-10-28",
        "exampleUrls": [
          "https://design.lemonergy.com/cosim.html?example=block-battery-pack-soc-ekf"
        ]
      }
    }
  },
  "incoming": [
    {
      "id": "edge:usesBlock/native-battery-pack-soc-ekf/0",
      "type": "usesBlock",
      "source": "workflow:native-battery-pack-soc-ekf",
      "target": "block:battery-pack-soc-ekf",
      "properties": {
        "sourceFile": "wiki-blocks.json",
        "position": 0,
        "name": "Pack-average SOC EKF",
        "type": "battery-pack-soc-ekf",
        "role": "Estimates the average SOC of homogeneous series cells. Voltage, resistance and observation slope scale by series count. Predicts a charge or energy fraction from signed throughput and corrects it using terminal voltage and a calibrated fraction-to-OCV table. Scalar Joseph covariance updates preserve nonnegative variance. Invalid voltage measurements skip correction; flat OCV regions report limited observability. Adaptive variants bound an innovation-based voltage-noise estimate.",
        "settings": [
          "Use the parameter values in the block reference.",
          "Bundled example verified on the production release of 28 October 2026."
        ]
      }
    }
  ],
  "outgoing": [
    {
      "id": "edge:cites/block:battery-pack-soc-ekf/reference:plett-estimation",
      "type": "cites",
      "source": "block:battery-pack-soc-ekf",
      "target": "reference:plett-estimation",
      "properties": {
        "sourceFile": "block-library.json",
        "scope": "Scientific or mathematical background; implementation scope is stated by the block contract"
      }
    },
    {
      "id": "edge:cites/block:battery-pack-soc-ekf/reference:plett-modeling",
      "type": "cites",
      "source": "block:battery-pack-soc-ekf",
      "target": "reference:plett-modeling",
      "properties": {
        "sourceFile": "block-library.json",
        "scope": "Scientific or mathematical background; implementation scope is stated by the block contract"
      }
    }
  ],
  "neighbors": [
    {
      "id": "workflow:native-battery-pack-soc-ekf",
      "type": "Workflow",
      "label": "Pack-average SOC EKF worked example",
      "properties": {
        "id": "native-battery-pack-soc-ekf",
        "title": "Pack-average SOC EKF worked example",
        "kind": "studio",
        "summary": "Homogeneous series-cell average observer. Voltage, resistance and observation slope scale by series count; output is an average, not individual cell SOC.",
        "steps": [
          "Review the block inputs, units and model limits.",
          "Open the Studio example and run its bundled model.",
          "Compare the output channels with the numerical checks; change one input and run again."
        ],
        "example": "Use the defaults below with Series pack current = 1 A, Measured pack voltage = 15 V, Voltage valid = 1 true / false, Reset = 0 true / false. At 0 s, Average SOC is 0.79 1 (fraction). Additional checks are listed below.",
        "observe": "Inspect the outputs and numerical checks on the block reference page.",
        "limits": "One-state extended Kalman observers, without an unscented transform, RC polarization states or automatic cell identification. SOE requires its own energy-fraction-to-OCV calibration. Synthetic filter settings are not accuracy guarantees. The estimate is a pack average, without independently estimated cell states. The example verifies numerical behavior for synthetic parameters. Cell characterization and validation for an intended use are separate tasks.",
        "url": "https://design.lemonergy.com/cosim.html?example=block-battery-pack-soc-ekf",
        "label": "Open Studio example",
        "evidence": [
          "docs/glossary/native-block-verification.json"
        ]
      }
    },
    {
      "id": "reference:plett-estimation",
      "type": "Reference",
      "label": "Extended Kalman filtering for battery management systems of LiPB-based HEV battery packs: Part 3. State and parameter estimation",
      "properties": {
        "title": "Extended Kalman filtering for battery management systems of LiPB-based HEV battery packs: Part 3. State and parameter estimation",
        "publisher": "Journal of Power Sources",
        "url": "https://doi.org/10.1016/j.jpowsour.2004.02.033",
        "type": "Research article",
        "scope": "Model-based battery state-of-charge and parameter estimation with extended Kalman filtering, including uncertainty and model dependence.",
        "year": 2004,
        "authors": [
          "Gregory L. Plett"
        ],
        "accessed": "2026-10-27"
      }
    },
    {
      "id": "reference:plett-modeling",
      "type": "Reference",
      "label": "Extended Kalman filtering for battery management systems of LiPB-based HEV battery packs: Part 2. Modeling and identification",
      "properties": {
        "title": "Extended Kalman filtering for battery management systems of LiPB-based HEV battery packs: Part 2. Modeling and identification",
        "publisher": "Journal of Power Sources",
        "url": "https://doi.org/10.1016/j.jpowsour.2004.02.032",
        "type": "Research article",
        "scope": "Battery charge balance, open-circuit voltage, ohmic loss, polarization dynamics and model identification; parameters require cell-specific data.",
        "year": 2004,
        "authors": [
          "Gregory L. Plett"
        ],
        "accessed": "2026-10-27"
      }
    }
  ]
}