{
  "node": {
    "id": "block:battery-capacity-observer",
    "type": "Block",
    "label": "Capacity observer",
    "properties": {
      "id": "battery-capacity-observer",
      "name": "Capacity observer",
      "kind": "studio",
      "summary": "Scalar capacity Kalman update from independent SOC change and removed charge.",
      "behavior": "Updates a scalar capacity estimate using an independently obtained SOC decrease and measured removed charge. Invalid windows retain prediction. The capacity estimate is bounded and reports clipping status.",
      "ports": [
        {
          "name": "socChange",
          "direction": "input",
          "unit": "1 (fraction)",
          "description": "Independent SOC decrease; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "fraction"
        },
        {
          "name": "charge",
          "direction": "input",
          "unit": "Ah",
          "description": "Removed charge (Ah); scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "dimensionless"
        },
        {
          "name": "valid",
          "direction": "input",
          "unit": "true / false",
          "description": "Window valid; scalar.",
          "shape": [],
          "elementType": "bool",
          "quantity": "dimensionless"
        },
        {
          "name": "reset",
          "direction": "input",
          "unit": "true / false",
          "description": "Reset; scalar.",
          "shape": [],
          "elementType": "bool",
          "quantity": "dimensionless"
        },
        {
          "name": "capacity",
          "direction": "output",
          "unit": "Ah",
          "description": "Estimated capacity (Ah); scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "dimensionless"
        },
        {
          "name": "variance",
          "direction": "output",
          "unit": "Ah²",
          "description": "Capacity variance (Ah²); scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "dimensionless"
        },
        {
          "name": "innovation",
          "direction": "output",
          "unit": "Ah",
          "description": "Charge innovation (Ah); scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "dimensionless"
        },
        {
          "name": "gain",
          "direction": "output",
          "unit": "1",
          "description": "Correction gain; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "dimensionless"
        },
        {
          "name": "status",
          "direction": "output",
          "unit": "1",
          "description": "Status (0 prediction, 1 correction, 2 clipped); 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": "initialCapacityAh",
          "label": "Initial capacity estimate (Ah)",
          "unit": "Ah",
          "default": 1.8,
          "description": "Initial capacity estimate (Ah). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "initialVariance",
          "label": "Initial capacity variance (Ah²)",
          "unit": "Ah²",
          "default": 0.04,
          "description": "Initial capacity variance (Ah²). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "processNoise",
          "label": "Capacity process variance rate (Ah²/s)",
          "unit": "Ah²/s",
          "default": 0,
          "description": "Capacity process variance rate (Ah²/s). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "measurementNoise",
          "label": "Charge measurement variance (Ah²)",
          "unit": "Ah²",
          "default": 0.0004,
          "description": "Charge measurement variance (Ah²). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "minCapacityAh",
          "label": "Minimum capacity estimate (Ah)",
          "unit": "Ah",
          "default": 0.1,
          "description": "Minimum capacity estimate (Ah). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "maxCapacityAh",
          "label": "Maximum capacity estimate (Ah)",
          "unit": "Ah",
          "default": 10,
          "description": "Maximum capacity estimate (Ah). This is an editable model input; the default belongs to the synthetic worked example."
        }
      ],
      "equations": [
        "predicted removedAh = capacityAh * deltaSOC",
        "innovation = measured removedAh - predicted removedAh"
      ],
      "example": {
        "title": "Capacity observer worked example",
        "text": "Use the defaults below with Independent SOC decrease = 0.2 1 (fraction), Removed charge (Ah) = 0.4 Ah, Window valid = 1 true / false, Reset = 0 true / false. At 0 s, Estimated capacity (Ah) is 1.96 Ah. Additional checks are listed below.",
        "url": "https://design.lemonergy.com/cosim.html?example=block-battery-capacity-observer",
        "label": "Open Studio example",
        "checks": [
          {
            "port": "capacity",
            "atS": 0,
            "value": 1.96,
            "tolerance": 1e-08,
            "label": "Estimated capacity (Ah)",
            "unit": "Ah"
          },
          {
            "port": "variance",
            "atS": 0,
            "value": 0.008,
            "tolerance": 1e-08,
            "label": "Capacity variance (Ah²)",
            "unit": "Ah²"
          },
          {
            "port": "innovation",
            "atS": 0,
            "value": 0.04,
            "tolerance": 1e-08,
            "label": "Charge innovation (Ah)",
            "unit": "Ah"
          },
          {
            "port": "gain",
            "atS": 0,
            "value": 4,
            "tolerance": 1e-08,
            "label": "Correction gain",
            "unit": "1"
          }
        ],
        "inputs": [
          {
            "port": "socChange",
            "label": "Independent SOC decrease",
            "value": 0.2,
            "unit": "1 (fraction)"
          },
          {
            "port": "charge",
            "label": "Removed charge (Ah)",
            "value": 0.4,
            "unit": "Ah"
          },
          {
            "port": "valid",
            "label": "Window valid",
            "value": 1,
            "unit": "true / false"
          },
          {
            "port": "reset",
            "label": "Reset",
            "value": 0,
            "unit": "true / false"
          }
        ]
      },
      "limits": [
        "Capacity is observable only with informative SOC changes. Feeding the same capacity-dependent SOC calculation back into the observer can create circular evidence.",
        "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"
      ],
      "evidence": [
        "docs/glossary/native-block-verification.json"
      ],
      "sourceRepository": "Lemonergy Studio public contract",
      "sourceRevision": "verification-2026-10-27",
      "caseIds": [
        "native-battery-capacity-observer"
      ],
      "exampleTraces": [
        {
          "id": "battery-capacity-observer",
          "url": "https://lemonergy.com/learn/glossary/api/traces/battery-capacity-observer.json?v=1562664f646d",
          "title": "Capacity observer recorded example",
          "exampleId": "block-battery-capacity-observer",
          "source": "Executed synthetic Lemonergy Studio example",
          "recordedOn": "2026-10-28",
          "points": 2,
          "channels": 5,
          "omittedChannels": 0,
          "interpolation": "step",
          "solver": {
            "method": "dormand-prince-45",
            "reason": "no-continuous-states"
          }
        }
      ],
      "type": "battery-capacity-observer",
      "implementationId": "battery-capacity-observer",
      "url": "https://lemonergy.com/learn/glossary/blocks/battery-capacity-observer/",
      "documentationUrl": "https://lemonergy.com/learn/glossary/blocks/battery-capacity-observer/",
      "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-capacity-observer"
        ]
      }
    }
  },
  "incoming": [
    {
      "id": "edge:usesBlock/native-battery-capacity-observer/0",
      "type": "usesBlock",
      "source": "workflow:native-battery-capacity-observer",
      "target": "block:battery-capacity-observer",
      "properties": {
        "sourceFile": "wiki-blocks.json",
        "position": 0,
        "name": "Capacity observer",
        "type": "battery-capacity-observer",
        "role": "Updates a scalar capacity estimate using an independently obtained SOC decrease and measured removed charge. Invalid windows retain prediction. The capacity estimate is bounded and reports clipping status.",
        "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-capacity-observer/reference:plett-estimation",
      "type": "cites",
      "source": "block:battery-capacity-observer",
      "target": "reference:plett-estimation",
      "properties": {
        "sourceFile": "block-library.json",
        "scope": "Scientific or mathematical background; implementation scope is stated by the block contract"
      }
    }
  ],
  "neighbors": [
    {
      "id": "workflow:native-battery-capacity-observer",
      "type": "Workflow",
      "label": "Capacity observer worked example",
      "properties": {
        "id": "native-battery-capacity-observer",
        "title": "Capacity observer worked example",
        "kind": "studio",
        "summary": "Scalar capacity Kalman update from independent SOC change and removed charge.",
        "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 Independent SOC decrease = 0.2 1 (fraction), Removed charge (Ah) = 0.4 Ah, Window valid = 1 true / false, Reset = 0 true / false. At 0 s, Estimated capacity (Ah) is 1.96 Ah. Additional checks are listed below.",
        "observe": "Inspect the outputs and numerical checks on the block reference page.",
        "limits": "Capacity is observable only with informative SOC changes. Feeding the same capacity-dependent SOC calculation back into the observer can create circular evidence. 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-capacity-observer",
        "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"
      }
    }
  ]
}