DiffLiB

DiffLiB is a high-fidelity differentiable modeling framework for lithium-ion batteries, with the backend support of JAX and JAX-FEM. The key features of DiffLiB include:

• High-fidelity finite element modeling of lithium-ion batteries, using the physics-based Doyle-Fuller-Newman (DFN) model
• End-to-end differentiable implementation, enabling efficient gradient-based optimization and parameter identification
• Modular and extensible workflow, allowing users to customize for specific applications

Installation

Follow the JAX installation guide and the JAX-FEM installation guide, then:

git clone https://github.com/CMSL-HKUST/DiffLiB.git
cd DiffLiB
pip install -e .

Consider also installing PyBaMM for parameter export:

pip install pybamm

Quick Start

import pybamm
import jax.numpy as np

from difflibx import Parameter, make_mesh, LiBProblem

# Export parameters from PyBaMM and load them
pybamm.ParameterValues("Marquis2019").to_json("marquis2019.json")
params = Parameter('marquis2019.json')

mesh_cfg = {'z_an': 100., 'n_an': 20, 'z_se': 25., 'n_se': 20,
            'z_ca': 100., 'n_ca': 20, 'y': 10.,  'n_y': 2,
            'r': 1.,      'n_r': 10}
mesh = make_mesh(type='layer3', cfg=mesh_cfg)

problem = LiBProblem(
    params, mesh,
    ground_pos_fn=lambda p: np.isclose(p[0], 0., atol=1e-5),
    current_pos_fn=lambda p: np.isclose(p[0], 225., atol=1e-5),
)

theta = np.array([params.alpha_an, params.alpha_ca, params.alpha_se,
                  params.ks[0], params.ks[1], params.tp,
                  params.ds_an, params.ds_ca, params.cs0_an, params.cs0_ca])
sol = problem.solve(dt=5, c_rate=1.0, t_eval=(0, 3620), theta=theta)
print(sol.macro.shape)  # (n_dofs_macro, n_steps)

This runs a 1 C-rate discharge. See demos/benchmark/forward.py for multi-rate validation against PyBaMM.

Parameters

DiffLiB reads battery parameters from a JSON file using PyBaMM-style keys. To see all required keys, their defaults, and overridable functions:

python -c "from difflibx import Parameter; Parameter.show_schema()"

The recommended workflow is to export from PyBaMM:

import pybamm
pybamm.ParameterValues("Marquis2019").to_json("params.json")
params = Parameter("params.json")

You can also hand-write a JSON using the same key format.

The DFN model currently assumes isothermal conditions (temperature-dependent parameter variations are not coupled into the solve).

Demos

Forward prediction

python -m demos.benchmark.forward

Variation of the terminal voltage during the constant-discharge.(Solid lines: DiffLiB; markers: PyBaMM)

Gradient evaluation

python -m demos.benchmark.gradient

Taylor test results for the validation of gradient computations.

License

This project is licensed under the GNU General Public License v3 — see the LICENSE for details.

Citations

If you found this library useful, we appreciate your support if you consider citing the following paper:

@article{xu2026difflib,
  title={DiffLiB: high-fidelity differentiable modeling of lithium-ion batteries and efficient gradient-based parameter identification},
  author={Xu, Weipeng and Yang, Kaiqi and Zhang, Yuzhi and Zhang, Wenchang and Sun, Shichao and Mao, Sheng and Xue, Tianju},
  journal={Structural and Multidisciplinary Optimization},
  volume={69},
  number={4},
  pages={83},
  year={2026},
  publisher={Springer}
}