{
  "node": {
    "id": "block:battery-ecm-cell",
    "type": "Block",
    "label": "Electrothermal ECM cell",
    "properties": {
      "id": "battery-ecm-cell",
      "name": "Electrothermal ECM cell",
      "kind": "studio",
      "summary": "Causal current-to-voltage model with charge and thermal states. Conserving ports are not yet included.",
      "behavior": "Accepts signed discharge current, ambient temperature and external heat. Charge balance drives SOC; an OCV table sets equilibrium voltage. The ECM adds two RC polarization states. Both variants include an ohmic loss and a lumped temperature state.",
      "ports": [
        {
          "name": "current",
          "direction": "input",
          "unit": "A",
          "description": "Signed cell current (discharge positive); scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "current"
        },
        {
          "name": "ambient",
          "direction": "input",
          "unit": "K",
          "description": "Ambient temperature; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "temperature"
        },
        {
          "name": "externalHeat",
          "direction": "input",
          "unit": "W",
          "description": "External heat flow; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "heat"
        },
        {
          "name": "voltage",
          "direction": "output",
          "unit": "V",
          "description": "Terminal voltage; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "voltage"
        },
        {
          "name": "soc",
          "direction": "output",
          "unit": "1 (fraction)",
          "description": "State of charge; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "fraction"
        },
        {
          "name": "temperature",
          "direction": "output",
          "unit": "K",
          "description": "Cell temperature; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "temperature"
        },
        {
          "name": "loss",
          "direction": "output",
          "unit": "W",
          "description": "Irreversible heat; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "heat"
        },
        {
          "name": "ocv",
          "direction": "output",
          "unit": "V",
          "description": "Open-circuit voltage; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "voltage"
        },
        {
          "name": "inRange",
          "direction": "output",
          "unit": "true / false",
          "description": "SOC in characterized range; scalar.",
          "shape": [],
          "elementType": "bool",
          "quantity": "dimensionless"
        }
      ],
      "parameters": [
        {
          "key": "capacityAh",
          "label": "Charge capacity (Ah)",
          "unit": "Ah",
          "default": 5,
          "description": "Charge capacity (Ah). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "resistanceOhm",
          "label": "Series resistance (Ω)",
          "unit": "Ω",
          "default": 0.01,
          "description": "Series resistance (Ω). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "r1Ohm",
          "label": "First polarization resistance (Ω)",
          "unit": "Ω",
          "default": 0.02,
          "description": "First polarization resistance (Ω). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "c1F",
          "label": "First polarization capacitance (F)",
          "unit": "F",
          "default": 500,
          "description": "First polarization capacitance (F). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "r2Ohm",
          "label": "Second polarization resistance (Ω)",
          "unit": "Ω",
          "default": 0.01,
          "description": "Second polarization resistance (Ω). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "c2F",
          "label": "Second polarization capacitance (F)",
          "unit": "F",
          "default": 2000,
          "description": "Second polarization capacitance (F). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "heatCapacityJPerK",
          "label": "Heat capacity (J/K)",
          "unit": "J/K",
          "default": 100,
          "description": "Heat capacity (J/K). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "conductanceWPerK",
          "label": "Ambient thermal conductance (W/K)",
          "unit": "W/K",
          "default": 1,
          "description": "Ambient thermal conductance (W/K). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "initialSoc",
          "label": "Initial SOC (0–1)",
          "unit": "0–1",
          "default": 0.8,
          "description": "Initial SOC (0–1). This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "initialTemperatureK",
          "label": "Initial cell temperature (K)",
          "unit": "K",
          "default": 298.15,
          "description": "Initial cell temperature (K). 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.7
            ],
            [
              1,
              3.7
            ]
          ],
          "description": "Open-circuit voltage table [SOC fraction, V]. Rows are ordered coordinate/value pairs; the first column must be strictly increasing."
        }
      ],
      "equations": [
        "dSOC/dt = -I / (3600 * capacityAh)",
        "dVk/dt = (I - Vk/Rk) / Ck  [ECM branches only]",
        "Vterminal = OCV(SOC) - I*R0 - sum(Vk)",
        "Cthermal*dT/dt = I^2*R0 + sum(Vk^2/Rk) + Qexternal - G*(T-Tambient)"
      ],
      "example": {
        "title": "Electrothermal ECM cell worked example",
        "text": "Use the defaults below with Signed cell current (discharge positive) = 2 A, Ambient temperature = 298.15 K, External heat flow = 0 W. At 0 s, Terminal voltage is 3.68 V. Additional checks are listed below.",
        "url": "https://design.lemonergy.com/cosim.html?example=block-battery-ecm-cell",
        "label": "Open Studio example",
        "checks": [
          {
            "port": "voltage",
            "atS": 0,
            "value": 3.68,
            "tolerance": 1e-08,
            "label": "Terminal voltage",
            "unit": "V"
          },
          {
            "port": "soc",
            "atS": 0,
            "value": 0.8,
            "tolerance": 1e-08,
            "label": "State of charge",
            "unit": "1 (fraction)"
          },
          {
            "port": "voltage",
            "atS": 10,
            "value": 3.646845790452711,
            "tolerance": 1e-06,
            "label": "Terminal voltage",
            "unit": "V"
          }
        ],
        "inputs": [
          {
            "port": "current",
            "label": "Signed cell current (discharge positive)",
            "value": 2,
            "unit": "A"
          },
          {
            "port": "ambient",
            "label": "Ambient temperature",
            "value": 298.15,
            "unit": "K"
          },
          {
            "port": "externalHeat",
            "label": "External heat flow",
            "value": 0,
            "unit": "W"
          }
        ]
      },
      "limits": [
        "The external interface is causal current-to-voltage, without conserving terminals. Parameters are constant except the one-dimensional SOC-to-OCV table. No hysteresis, aging, reversible entropic heat or automatic parameter identification.",
        "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-modeling",
        "bernardi-energy"
      ],
      "evidence": [
        "docs/glossary/native-block-verification.json"
      ],
      "sourceRepository": "Lemonergy Studio public contract",
      "sourceRevision": "verification-2026-10-27",
      "caseIds": [
        "native-battery-ecm-cell"
      ],
      "exampleTraces": [
        {
          "id": "battery-ecm-cell",
          "url": "https://lemonergy.com/learn/glossary/api/traces/battery-ecm-cell.json?v=4bb6ace37339",
          "title": "Electrothermal ECM cell recorded example",
          "exampleId": "block-battery-ecm-cell",
          "source": "Executed synthetic Lemonergy Studio example",
          "recordedOn": "2026-10-28",
          "points": 103,
          "channels": 6,
          "omittedChannels": 0,
          "interpolation": "linear",
          "solver": {
            "method": "dormand-prince-45",
            "reason": "non-stiff-time-scales"
          }
        }
      ],
      "type": "battery-ecm-cell",
      "implementationId": "battery-ecm-cell",
      "url": "https://lemonergy.com/learn/glossary/blocks/battery-ecm-cell/",
      "documentationUrl": "https://lemonergy.com/learn/glossary/blocks/battery-ecm-cell/",
      "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-ecm-cell"
        ]
      }
    }
  },
  "incoming": [
    {
      "id": "edge:usesBlock/native-battery-ecm-cell/0",
      "type": "usesBlock",
      "source": "workflow:native-battery-ecm-cell",
      "target": "block:battery-ecm-cell",
      "properties": {
        "sourceFile": "wiki-blocks.json",
        "position": 0,
        "name": "Electrothermal ECM cell",
        "type": "battery-ecm-cell",
        "role": "Accepts signed discharge current, ambient temperature and external heat. Charge balance drives SOC; an OCV table sets equilibrium voltage. The ECM adds two RC polarization states. Both variants include an ohmic loss and a lumped temperature state.",
        "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-ecm-cell/reference:bernardi-energy",
      "type": "cites",
      "source": "block:battery-ecm-cell",
      "target": "reference:bernardi-energy",
      "properties": {
        "sourceFile": "block-library.json",
        "scope": "Scientific or mathematical background; implementation scope is stated by the block contract"
      }
    },
    {
      "id": "edge:cites/block:battery-ecm-cell/reference:plett-modeling",
      "type": "cites",
      "source": "block:battery-ecm-cell",
      "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-ecm-cell",
      "type": "Workflow",
      "label": "Electrothermal ECM cell worked example",
      "properties": {
        "id": "native-battery-ecm-cell",
        "title": "Electrothermal ECM cell worked example",
        "kind": "studio",
        "summary": "Causal current-to-voltage model with charge and thermal states. Conserving ports are not yet included.",
        "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 Signed cell current (discharge positive) = 2 A, Ambient temperature = 298.15 K, External heat flow = 0 W. At 0 s, Terminal voltage is 3.68 V. Additional checks are listed below.",
        "observe": "Inspect the outputs and numerical checks on the block reference page.",
        "limits": "The external interface is causal current-to-voltage, without conserving terminals. Parameters are constant except the one-dimensional SOC-to-OCV table. No hysteresis, aging, reversible entropic heat or automatic parameter identification. 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-ecm-cell",
        "label": "Open Studio example",
        "evidence": [
          "docs/glossary/native-block-verification.json"
        ]
      }
    },
    {
      "id": "reference:bernardi-energy",
      "type": "Reference",
      "label": "A General Energy Balance for Battery Systems",
      "properties": {
        "title": "A General Energy Balance for Battery Systems",
        "publisher": "Journal of The Electrochemical Society",
        "url": "https://doi.org/10.1149/1.2113792",
        "type": "Research article",
        "scope": "Battery energy balance and irreversible and reversible heat contributions. Reduced thermal models require explicit assumptions and current-sign conventions.",
        "year": 1985,
        "authors": [
          "Dawn Bernardi",
          "Ellen Pawlikowski",
          "John Newman"
        ],
        "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"
      }
    }
  ]
}