My First Json Input

In this page, we present example of json inputs. The parameter names haven hopefully chosen in a way that they will be easily understood by battery modelers. Their description is included in the json schemas, see some links include below, and this documentation this page.

The json input follows the battery model hierarchy as described in BattMo Model Architecture. The input contains also simulation specific parameters, such as solver parameters and time stepping.

The keywords isFile, filename and filenames are recognized by the parser (parseBattmoJson) and used to include inputs from other files, as shown in the next example

Simulation

{
  "isFile" : true,
  "filenames": ["Examples/Documentation/jsonfiles/Example/battery.json",
                "Examples/Documentation/jsonfiles/Example/geometry.json",
                "Examples/Documentation/jsonfiles/Example/modelSpecification.json",
                "Examples/Documentation/jsonfiles/Example/control.json",
                "Examples/Documentation/jsonfiles/Example/timeStepping.json",
                "Examples/Documentation/jsonfiles/Example/stateInitialization.json"]
}

The keyword isFile is recognized. The value of filenames contain an array with a list of the files that we want to include. Those files are also the ones that are presented in this page (all the files are in this directory, which comes with your battmo installation)

The path of the file is first tested as such but if no file is found, the parser will check the path that is obtained relative to your battmo installation path.

You can actually run this illustration example using

jsonstruct = parseBattmoJson('Examples/Documentation/jsonfiles/Example/simulation.json');
output = runBatteryJson(jsonstruct);

Battery

{
  "NegativeElectrode": {
    "isFile": true,
    "filename": "Examples/Documentation/jsonfiles/Example/negativeElectrode.json"
  },
  "PositiveElectrode": {
    "isFile": true,
    "filename": "Examples/Documentation/jsonfiles/Example/positiveElectrode.json"
  },
  "Electrolyte": {
    "isFile": true,
    "filename": "Examples/Documentation/jsonfiles/Example/electrolyte.json"
  },
  "Separator": {
    "isFile": true,
    "filename": "Examples/Documentation/jsonfiles/Example/separator.json"
  },
  "ThermalModel": {
    "isFile": true,
    "filename": "Examples/Documentation/jsonfiles/Example/thermalComponent.json"
  },
  "SOC": 0.9900,
  "initT": 298.1500,
  "use_thermal": true
}

Here, we recognize the battery hierarchy where the sumodels are the negative and positive electrodes, the electrolyte, the separator and the thermal model, if thermal effects are included. The initial temperature and state of charge are also included here.

Negative Electrode

{
  "Coating" : {
    "isFile": true,
    "filename" : "Examples/Documentation/jsonfiles/Example/coating.json"
  },
  "CurrentCollector" : {
    "isFile": true,
    "filename" : "Examples/Documentation/jsonfiles/Example/currentCollector.json"
  }
}

The electrode consists of a current collector and a coating. They are fetched from files. Here, we show only the negative electrode.

Coating

{
  "ActiveMaterial": {
    "isFile": true,
    "filename" : "Examples/Documentation/jsonfiles/Example/activeMaterial.json"
  },
  "Binder": {
    "isFile": true,
    "filename" : "Examples/Documentation/jsonfiles/Example/binder.json"
  },
  "ConductingAdditive": {
    "isFile": true,
    "filename" : "Examples/Documentation/jsonfiles/Example/conductingAdditive.json"
  },
  "effectiveDensity": 1900,
  "bruggemanCoefficient": 1.5
}

The coating consists of the active material, the binder and the conducting additive. The coating has also effective parameters that are set at this level, such as the effectiveDensity and the bruggemanCoefficient. The effective density is used to compute the porosity from the properties of the three coating components.

Active Material

{
  "Interface": {
    "isFile": true,
    "filename" : "Examples/Documentation/jsonfiles/Example/interface.json"
  },
  "SolidDiffusion": {
    "isFile": true,
    "filename" : "Examples/Documentation/jsonfiles/Example/solidDiffusion.json"
  },
  "diffusionModelType": "full",
  "electronicConductivity": 100,
  "density": 2240,
  "massFraction": 0.94,
  "thermalConductivity": 1.04,
  "specificHeatCapacity": 632
}

The submodels in the active material are the interface which collects the parameters related to the surface reaction between the electode and the electrolyte and the solid diffusion model which collects the the parameters related to the solid diffusion in the pseudo particle.

Interface

{
  "saturationConcentration": 30555,
  "volumetricSurfaceArea": 723600,
  "numberOfElectronsTransferred": 1,
  "activationEnergyOfReaction": 5000,
  "reactionRateConstant": 5.031E-11,
  "guestStoichiometry100": 0.88551,
  "guestStoichiometry0": 0.1429,
  "chargeTransferCoefficient": 0.5,
  "openCircuitPotential": {
    "functionFormat": "named function",
    "functionName": "computeOCP_Graphite_Torchio",
    "argumentList": [
      "stoichiometry"
    ]
  },
  "entropyChange": {
    "functionFormat": "named function",
    "functionName": "computeEntropyChange_Graphite_Torchio",
    "argumentList": [
      "stoichiometry"
    ]
  },
  "referenceTemperature": 298.15,
  "density": 2240,
  "includeEntropyChange": true
}

We do not explain in detail here all the parameters. We hope the names are chosen so that they will be easily recognizable by battery modellers. Again, we refer the json schema for a reference, see the description key.

The most important parameter of the electrochemical reaction is certainly the open circuit potential. The open circuit potential is a function. In this example, the function is implemented as a matlab function and we call named function this type of format.

Functional parameters enter the DFN model at several places and we have implemented a specific input for those which is explained in details in Functional Parameters

Solid Diffusion

{
  "activationEnergyOfDiffusion": 5000,
  "referenceDiffusionCoefficient": 3.9e-14,
  "particleRadius": 1e-6,
  "volumetricSurfaceArea": 723600}

The particle radius and the diffusion coefficient governs the time scale of the diffusion. The volumetric surface parameter is an important part of the volume averaging approach the DFN model uses, and it is not easy to estimate.

Binder

{
  "density": {
    "value": 1.1,
    "unit": "gram/((centi*meter)^3)"
  },
  "massFraction": 0.03,
  "electronicConductivity": 100,
  "specificHeatCapacity": 632,
  "thermalConductivity": 1.04
}

The binder contains intrinsic parameters that are used to compute the effective coating material parameters for thermal and electronic conductivity but no other process are modeled at this level.

Conducting Additive

{
  "density": {
    "value": 1.95,
    "unit": "gram/((centi*meter)^3)"
  },
  "massFraction": 0.03,
  "electronicConductivity": 100,
  "specificHeatCapacity": 632,
  "thermalConductivity": 1.04 
}

As binder, conductive additive contains intrinsic parameters that are used to compute the effective coating material parameters for thermal and electronic conductivity but no other process are modeled at this level.

Electrolyte

{
  "specificHeatCapacity": 2055,
  "thermalConductivity": 0.6,
  "density": 1200,
  "initialConcentration": 1000,
  "ionicConductivity": {
    "functionFormat": "named function",
    "functionName": "computeElectrolyteConductivity_Ai2020",
    "argumentList": [
      "concentration",
      "temperature"
    ]
  },
  "diffusionCoefficient": {
    "functionFormat": "named function",
    "functionName": "computeDiffusionCoefficient_Ai2020",
    "argumentList": [
      "concentration",
      "temperature"
    ]
  },
  "species": {
    "transferenceNumber": 0.2594,
    "nominalConcentration": 1000
  },
  "bruggemanCoefficient": 1.5
}

This is an other example where we see functional parameters, the ionic conductivity and the diffusion coefficient, which are functions of concentration and temperature.

Current Collector

{
  "thickness": 1E-5,
  "N": 2,
  "tab": {
    "width": 0.004,
    "height": 0.001,
    "Nw": 3,
    "Nh": 3
  },
  "electronicConductivity": 5.96E+7,
  "thermalConductivity": 398,
  "specificHeatCapacity": 385,
  "density": 8960
}

Thermal effects and electrical current is modeled at the current collector.

Separator

{
  "specificHeatCapacity": 2055,
  "thermalConductivity": 0.6,
  "density": 1200,
  "initialConcentration": 1000,
  "ionicConductivity": {
    "functionFormat": "named function",
    "functionName": "computeElectrolyteConductivity_Ai2020",
    "argumentList": [
      "concentration",
      "temperature"
    ]
  },
  "diffusionCoefficient": {
    "functionFormat": "named function",
    "functionName": "computeDiffusionCoefficient_Ai2020",
    "argumentList": [
      "concentration",
      "temperature"
    ]
  },
  "species": {
    "transferenceNumber": 0.2594,
    "nominalConcentration": 1000
  },
  "bruggemanCoefficient": 1.5
}

The binder enters the model only through thermal effects.

Thermal Model

{
  "externalHeatTransferCoefficientTab": 1000,
  "externalHeatTransferCoefficient": 100,
  "externalTemperature": 298.15
}

The thermal properties, namely the thermal capacity and conductivity, are effective properties which are computed from the intrinsic properties of each components, as we have seen above.

Here, we find the parameters that characterize the heat transfer with the exterior. They are effective parameters, except for the external temperature.

Geometry

We consider the 3D demo model, see here

{
  "Geometry": {
    "case": "3D-demo",
    "width": 0.01,
    "height": 0.02,
    "Nw": 10,
    "Nh": 10
  },
  "NegativeElectrode": {
    "Coating": {
      "thickness": 0.0001,
      "N": 3,
      "ActiveMaterial": {
        "SolidDiffusion": {
          "N": 10 }}},
    "CurrentCollector": {
      "thickness": 1e-05,
      "N": 2,
      "tab": {
        "width": 0.004,
        "height": 0.001,
        "Nw": 3,
        "Nh": 3 }}},
  "PositiveElectrode": {
    "Coating": {
      "thickness": 8e-05,
      "N": 3,
      "ActiveMaterial": {
        "SolidDiffusion": {
          "N": 10
        }}},
    "CurrentCollector": {
      "thickness": 1e-05,
      "N": 2,
      "tab": {
        "width": 0.004,
        "height": 0.001,
        "Nw": 3,
        "Nh": 3}}},
  "Separator": {
    "thickness": 5e-05,
    "N": 3 },
  "ThermalModel": {
    "externalHeatTransferCoefficientTab": 1000,
    "externalHeatTransferCoefficient": 100
  }
}

We consider geometries that are parameterized. It is easy to consider an arbitrary design as long as the user can provide a mesh with tags for the component. We have however not setup a json interface for such usage.

We can see that the geometrical parameters are dispatched in each component where they belong.

Again, we refer to json schema for an explanation of the parameters, see Geometry Setup.

Control

{
  "Control" : {
    "controlPolicy": "CCDischarge",
    "DRate": 1,
    "lowerCutoffVoltage": 2.4}}

Here, we use a discharge scenario with a given discarge rate and lower cutoff voltage. An overview with explanation of the available controls is given in Control models.

Model Specification

{
  "include_current_collectors": true,
  "use_thermal": true
}

Under the model specification key, we include global model setups. In this case, we include thermal effects and the current collector are included.

State Initialization

{
  "initializationSetup": "given SOC",
  "initT": 298.15,
  "SOC": 0.99,
  "Electrolyte" : {
    "initialConcentration" : {
      "value": 1,
      "unit": "mol/litre"}}}

The simulator requires an initial state for the system. The default choice is to provide a state of charge (soc) and set constant concentration and potential values equal to their respective equilibrium values. We provide also the initial electrolyte concentration at the electrolyte level.

Time Stepping

{
  "TimeStepping": {
    "numberOfTimeSteps" : 50,
    "useRampup" : true,
    "numberOfRampupSteps" : 4}}

This information is used by the simulator to setup the time stepping. Default values are also provided, see Time Stepping Parameters.