{
  "node": {
    "id": "block:battery-module",
    "type": "Block",
    "label": "Battery module",
    "properties": {
      "id": "battery-module",
      "name": "Battery module",
      "kind": "studio",
      "summary": "Generated series/parallel cell hierarchy with individual SOC, RC and temperature states, KCL current sharing and optional thermal links. Causal pack-current boundary.",
      "behavior": "Builds an explicit series/parallel hierarchy with a separate SOC, two RC voltages and temperature for every cell. Subtree voltage/resistance reduction and Kirchhoff current sharing determine each cell current. Optional thermal links exchange equal and opposite heat. Per-cell overrides introduce controlled variation.",
      "ports": [
        {
          "name": "current",
          "direction": "input",
          "unit": "A",
          "description": "Signed pack current; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "current"
        },
        {
          "name": "ambient",
          "direction": "input",
          "unit": "K",
          "description": "Cell ambient temperatures; 6 channels at the default configuration.",
          "shape": [
            6
          ],
          "elementType": "real",
          "quantity": "temperature"
        },
        {
          "name": "externalHeat",
          "direction": "input",
          "unit": "W",
          "description": "External cell heat inputs; 6 channels at the default configuration.",
          "shape": [
            6
          ],
          "elementType": "real",
          "quantity": "heat"
        },
        {
          "name": "voltage",
          "direction": "output",
          "unit": "V",
          "description": "Pack terminal voltage; scalar.",
          "shape": [],
          "elementType": "real",
          "quantity": "voltage"
        },
        {
          "name": "cellVoltage",
          "direction": "output",
          "unit": "V",
          "description": "Individual cell voltages; 6 channels at the default configuration.",
          "shape": [
            6
          ],
          "elementType": "real",
          "quantity": "voltage"
        },
        {
          "name": "cellCurrent",
          "direction": "output",
          "unit": "A",
          "description": "Individual cell currents; 6 channels at the default configuration.",
          "shape": [
            6
          ],
          "elementType": "real",
          "quantity": "current"
        },
        {
          "name": "cellSoc",
          "direction": "output",
          "unit": "1 (fraction)",
          "description": "Individual cell SOC; 6 channels at the default configuration.",
          "shape": [
            6
          ],
          "elementType": "real",
          "quantity": "fraction"
        },
        {
          "name": "cellTemperature",
          "direction": "output",
          "unit": "K",
          "description": "Individual cell temperatures; 6 channels at the default configuration.",
          "shape": [
            6
          ],
          "elementType": "real",
          "quantity": "temperature"
        },
        {
          "name": "cellHeat",
          "direction": "output",
          "unit": "W",
          "description": "Individual cell heat generation; 6 channels at the default configuration.",
          "shape": [
            6
          ],
          "elementType": "real",
          "quantity": "heat"
        },
        {
          "name": "nodeVoltage",
          "direction": "output",
          "unit": "V",
          "description": "Hierarchy node voltages; 10 channels at the default configuration.",
          "shape": [
            10
          ],
          "elementType": "real",
          "quantity": "voltage"
        },
        {
          "name": "nodeCurrent",
          "direction": "output",
          "unit": "A",
          "description": "Hierarchy node currents; 10 channels at the default configuration.",
          "shape": [
            10
          ],
          "elementType": "real",
          "quantity": "current"
        }
      ],
      "parameters": [
        {
          "key": "parallelCells",
          "label": "Parallel cells in each group",
          "unit": "1",
          "default": 2,
          "description": "Parallel cells in each group. This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "seriesGroups",
          "label": "Series groups in each module",
          "unit": "1",
          "default": 3,
          "description": "Series groups in each module. This is an editable model input; the default belongs to the synthetic worked example."
        },
        {
          "key": "cellProfile",
          "label": "Cell parameters [Ah, Ω, Ω, F, Ω, F, J/K, W/K, SOC, K, V offset]",
          "unit": "See field order",
          "default": [
            5,
            0.02,
            0.02,
            500,
            0.01,
            2000,
            100,
            1,
            0.8,
            298.15,
            0
          ],
          "description": "Ordered fields: capacity (Ah), R0 (Ω), R1 (Ω), C1 (F), R2 (Ω), C2 (F), heat capacity (J/K), ambient conductance (W/K), initial SOC, initial temperature (K), OCV offset (V)."
        },
        {
          "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."
        },
        {
          "key": "cellOverrides",
          "label": "Overrides [cell index, parameter index, value]",
          "unit": "See field order",
          "default": [],
          "description": "Rows contain zero-based cell index, zero-based cell-profile parameter index and replacement value. Empty means every cell uses the base profile."
        },
        {
          "key": "thermalEdges",
          "label": "Thermal links [cell index, cell index, W/K]",
          "unit": "See field order",
          "default": [],
          "description": "Rows contain two distinct zero-based cell indices and conductance (W/K). Each edge exchanges equal and opposite heat. Empty means no cell-to-cell links."
        }
      ],
      "equations": [
        "series: current is shared; voltages add",
        "parallel: terminal voltage is shared; branch currents sum to imposed current",
        "Icell = (Ecell - Vparallel) / Rcell",
        "Qij = Gij*(Ti-Tj); Qji = -Qij"
      ],
      "example": {
        "title": "Battery module worked example",
        "text": "Use the defaults below with Signed pack current = 6 A, Cell ambient temperatures = [298.15, 298.15, 298.15, 298.15, 298.15, 298.15] K, External cell heat inputs = [0, 0, 0, 0, 0, 0] W. At 0 s, Pack terminal voltage is 10.92 V. Additional checks are listed below.",
        "url": "https://design.lemonergy.com/cosim.html?example=block-battery-module",
        "label": "Open Studio example",
        "checks": [
          {
            "port": "voltage",
            "atS": 0,
            "value": 10.92,
            "tolerance": 1e-08,
            "label": "Pack terminal voltage",
            "unit": "V"
          },
          {
            "port": "cellCurrent",
            "atS": 0,
            "value": [
              3,
              3,
              3,
              3,
              3,
              3
            ],
            "tolerance": 1e-08,
            "label": "Individual cell currents",
            "unit": "A"
          },
          {
            "port": "cellSoc",
            "atS": 0,
            "value": [
              0.8,
              0.8,
              0.8,
              0.8,
              0.8,
              0.8
            ],
            "tolerance": 1e-08,
            "label": "Individual cell SOC",
            "unit": "1 (fraction)"
          },
          {
            "port": "cellSoc",
            "atS": 10,
            "value": [
              0.7983333333333333,
              0.7983333333333333,
              0.7983333333333333,
              0.7983333333333333,
              0.7983333333333333,
              0.7983333333333333
            ],
            "tolerance": 1e-08,
            "label": "Individual cell SOC",
            "unit": "1 (fraction)"
          }
        ],
        "inputs": [
          {
            "port": "current",
            "label": "Signed pack current",
            "value": 6,
            "unit": "A"
          },
          {
            "port": "ambient",
            "label": "Cell ambient temperatures",
            "value": [
              298.15,
              298.15,
              298.15,
              298.15,
              298.15,
              298.15
            ],
            "unit": "K"
          },
          {
            "port": "externalHeat",
            "label": "External cell heat inputs",
            "value": [
              0,
              0,
              0,
              0,
              0,
              0
            ],
            "unit": "W"
          }
        ]
      },
      "limits": [
        "Bounded to 256 cells with the supported series/parallel construction. External pack current is imposed causally; no arbitrary geometry, conserving terminal adapter or topology reconfiguration. Each cell parameter set still needs characterization.",
        "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-module"
      ],
      "exampleTraces": [
        {
          "id": "battery-module",
          "url": "https://lemonergy.com/learn/glossary/api/traces/battery-module.json?v=36868c05ddb3",
          "title": "Battery module recorded example",
          "exampleId": "block-battery-module",
          "source": "Executed synthetic Lemonergy Studio example",
          "recordedOn": "2026-10-28",
          "points": 103,
          "channels": 12,
          "omittedChannels": 39,
          "interpolation": "linear",
          "solver": {
            "method": "dormand-prince-45",
            "reason": "non-stiff-time-scales"
          }
        }
      ],
      "type": "battery-module",
      "implementationId": "battery-module",
      "url": "https://lemonergy.com/learn/glossary/blocks/battery-module/",
      "documentationUrl": "https://lemonergy.com/learn/glossary/blocks/battery-module/",
      "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-module"
        ]
      }
    }
  },
  "incoming": [
    {
      "id": "edge:usesBlock/native-battery-module/0",
      "type": "usesBlock",
      "source": "workflow:native-battery-module",
      "target": "block:battery-module",
      "properties": {
        "sourceFile": "wiki-blocks.json",
        "position": 0,
        "name": "Battery module",
        "type": "battery-module",
        "role": "Builds an explicit series/parallel hierarchy with a separate SOC, two RC voltages and temperature for every cell. Subtree voltage/resistance reduction and Kirchhoff current sharing determine each cell current. Optional thermal links exchange equal and opposite heat. Per-cell overrides introduce controlled variation.",
        "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-module/reference:bernardi-energy",
      "type": "cites",
      "source": "block:battery-module",
      "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-module/reference:plett-modeling",
      "type": "cites",
      "source": "block:battery-module",
      "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-module",
      "type": "Workflow",
      "label": "Battery module worked example",
      "properties": {
        "id": "native-battery-module",
        "title": "Battery module worked example",
        "kind": "studio",
        "summary": "Generated series/parallel cell hierarchy with individual SOC, RC and temperature states, KCL current sharing and optional thermal links. Causal pack-current boundary.",
        "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 pack current = 6 A, Cell ambient temperatures = [298.15, 298.15, 298.15, 298.15, 298.15, 298.15] K, External cell heat inputs = [0, 0, 0, 0, 0, 0] W. At 0 s, Pack terminal voltage is 10.92 V. Additional checks are listed below.",
        "observe": "Inspect the outputs and numerical checks on the block reference page.",
        "limits": "Bounded to 256 cells with the supported series/parallel construction. External pack current is imposed causally; no arbitrary geometry, conserving terminal adapter or topology reconfiguration. Each cell parameter set still needs characterization. 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-module",
        "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"
      }
    }
  ]
}