DOCSEARCHbyAlgolia
Submit Docs

PyBaMM (Python Battery Mathematical Modelling)

repository·main·Indexed 23 days ago

https://github.com/pybamm-team/pybamm

An open-source Python package for battery simulation. It provides a framework for solving differential equations, a library of battery models and parameters, and tools for simulating experiments and visualizing results. Key features include the pybamm.Simulation and pybamm.Experiment classes, BatchStudy for multiple simulations, a callback system for monitoring, and AOT compilation via CasADi for performance improvement. It also includes the pybammsolvers package for the IDAKLU solver.

Tokens
52.6K
Snippets
90
Records
430
Agent score
81%

What's inside PyBaMM

  1. Overview of PyBaMM

    main

    PyBaMM (Python Battery Mathematical Modelling) is an open-source battery simulation package written in Python. It is designed to accelerate battery modelling research through a framework that includes:

    • A framework for writing and solving systems of differential equations.
    • A library of battery models and parameters.
    • Specialized tools for simulating battery-specific experiments and visualizing results.

    This allows for flexible model definitions and fast simulations to explore battery designs and modeling assumptions under various operating scenarios.

  2. Use pybamm.callbacks for monitoring simulations

    main
    PyBaMM provides a callback system to monitor or log simulation progress and data during execution. You can use individual Callback objects, a CallbackList to manage multiple callbacks, or the LoggingCallback for standard logging. The setup_callbacks function is used to initialize and attach these callbacks to a simulation.

  3. Use Potential Pair models for current collection

    main

    Potential Pair models are used in PyBaMM to model the current collection process by considering the potential difference between the current collector and the electrode.

    There are two primary implementations available:

    • PotentialPair1plus1D: A 1-dimensional model for current collection.
    • PotentialPair2plus1D: A 2-dimensional model for current collection.

    Both inherit from BasePotentialPair, which defines the common interface for these models.

  4. Understand the PyBaMM core framework

    main

    PyBaMM is a battery simulation package composed of three main pillars:

    1. A mathematical framework: Uses a custom computer algebra system and a domain-specific modeling language to define systems of differential equations (usually PDEs).
    2. A model and parameter library: Contains pre-defined battery models (e.g., SPM, DFN) and parameter sets for various chemistries (NMC, LFP, NCA, etc.).
    3. Battery-specific tools: Specialized classes for defining experiments and visualizing results.

    Models are solved using the Method of Lines: equations are first discretized in the spatial dimension using the finite volume method, and the resulting system is then passed to numerical solvers. Depending on the model definition, PyBaMM can solve:

    • ODEs: If only model.rhs is defined.
    • Algebraic equations: If only model.algebraic is defined.
    • DAEs: If both model.rhs and model.algebraic are defined.

  5. Use FunctionControl to manage external circuits

    main

    The pybamm.external_circuit.FunctionControl class and its subclasses allow you to define how an external circuit behaves during a simulation. This is used to control variables like voltage, power, or resistance as functions of time or other simulation parameters.

    Available control types include:

    • VoltageFunctionControl: Controls the voltage applied to the circuit.
    • PowerFunctionControl: Controls the power applied to the circuit.
    • ResistanceFunctionControl: Controls the resistance of the circuit.
    • CCCVFunctionControl: Implements Constant Current Constant Voltage (CCCV) control logic.

  6. Understand External Circuit submodels in PyBaMM

    main

    PyBaMM provides submodels to enforce boundary conditions that simulate an external circuit. These models allow you to specify how the battery behaves under different electrical loads, such as constant current, constant voltage, or constant power.

    There are two primary approaches to implementing these controls:

    1. Current control: Enforces specific electrical behaviors directly through boundary conditions.
    2. Function control: Adds an algebraic equation for the current, which allows you to set any variable to a constant value or define complex relationships between current and voltage.

    To implement these, you should explore the specific submodel implementations for discharge_throughput, explicit_control_external_circuit, and function_control_external_circuit.

  7. Manage battery simulation parameters with ParameterValues

    main

    The pybamm.ParameterValues class is the primary interface for managing battery simulation parameters. It allows you to load, store, update, and inspect parameter sets used in PyBaMM models. You can load predefined parameter sets by name (e.g., "Chen2020") or provide custom values.

    import pybamm

# Load a parameter set
params = pybamm.ParameterValues("Chen2020")

  8. Configure model parameters using ParameterValues

    main

    PyBaMM models are parameterized using a ParameterValues object. This object behaves similarly to a Python dictionary but includes PyBaMM-specific features.

    In a model, parameters are represented as Parameter or FunctionParameter objects. The ParameterValues object replaces these objects with actual values before solving. Supported value types include:

    • Scalars
    • Python functions
    • Expressions of type Symbol

  9. How PyBaMM serialises objects

    main

    PyBaMM uses a single encode/decode kernel (pybamm.expression_tree.operations.serialise_kernel) to serialise expression trees, discretised models, meshes, solvers, and related objects.

    Key Characteristics

    • Safe-or-loud: The kernel follows a strict contract. A value either round-trips perfectly, or encoding raises a SerialisationError that explicitly names the offending class and field. It never silently drops data.
    • Canonical Wire Format: The standard format is plain JSON where every non-native object is a tagged node containing its class-specific fields and a "$type" key holding the dotted module.ClassName path.
    • Recursive Encoding: Child symbols or serialisable sub-objects are recursively encoded under a "children" key.
    • Compatibility: A read-only compatibility layer allows decode to load files written by older PyBaMM versions by normalising them into the canonical format.

  10. Use the Single Particle Model (SPM) in PyBaMM

    main

    PyBaMM provides several variations of the Single Particle Model (SPM) for lithium-ion battery simulation. These models represent the electrochemical behavior of a single particle in the electrode, significantly reducing computational complexity compared to full Doyle-Fuller-Newman (DFN) models.

    Available classes include:

    • pybamm.lithium_ion.SPM: The standard Single Particle Model.
    • pybamm.lithium_ion.BasicSPM: A simplified version of the SPM.
    • pybamm.lithium_ion.Basic3DThermalSPM: A version of the SPM that includes 3D thermal effects.

  11. Customize battery models using the options dictionary

    main
    PyBaMM battery models can be customized by passing an options dictionary to the model constructor. This dictionary allows you to toggle specific physics, submodels, or parameterizations. The pybamm.BaseBatteryModel class defines the structure for these options and provides information regarding which options and models are compatible with one another.