What is lion?

lion is a library whose goal is to provide a simulator of the operation of a lithium-ion battery, considering both electrical and thermal behavior, as well as the relations between both of them. It does this by considering a series of models that dictate how electrical operation affects heat generation, and how the cell's temperatures affect electrical performance.

Installation

Here, the installation instructions are detailed for all supported platforms, namely

• Linux
• macOS
• Windows

Installation > Linux

C library

For building in Linux, the GSL library must be installed according to your distribution: for some common distributions, the corresponding instruction would be

sudo apt install libgsl-dev  # Ubuntu
sudo dnf install gsl         # Fedora
sudo pacman -S gsl           # Arch

lion uses CMake as the build system, so you also need to have it installed. Then, simply run

make
sudo make install

to build and install the library, respectively. After this, the library files can be found in /usr/lib, and the headers in /usr/include/lion/.

Python bindings

Additionally, once the C library is installed the Python bindings can be installed by calling

pip install -r requirements.txt
pip install .

after which the packages lion and lion_utils are installed.

Installation > macOS

Installation for both the C library and the Python bindings on macOS is equivalent to Linux. The recommended method to install GSL is using homebrew, by calling brew install gsl, but any other method should work as long as CMake is able to automatically find GSL.

Installation > Windows

The recommended method of using lion in Windows is through WSL, for which the Linux instructions should be followed, but native compilation is possible.

C library

Installation on Windows is only currently supported using vcpkg to handle package installation and configuration of the toolchain. Having both vcpkg and CMake installed, the VCPKG_ROOT environment variable must be pointing towards the directory in which vcpkg was installed: then, simply run

./make.bat
./make.bat install

which will configure and install the library, requesting administrator privileges for installation.

Python bindings

In order to install the Python bindings, it is not necessary to have the C library installed, as installing the Python library will build the binaries and ship them within the source files: thus, if you only intend to use lion as a Python library, it is recommended to only install the bindings. Having CMake and vcpkg installed with the VCPKG_ROOT environment variable properly configured, simply run

pip install -r requirements.txt
pip install .

which will compile the C library and leave the binaries within the Python FFI, as well as install the Python bindings. Currently, the Python FFI only works with the binaries included within the package itself.

Documentation

HTML documentation

Currently, building the documentation is only supported on Linux.

Building the documentation requires Doxygen to compile the API reference into XML and man files, moxygen to transpile the XML files into Markdown files, and mdBook to compile the Markdown documentation (which includes the API reference and more) into HTML files. With these three tools installed, run

make docs

to compile the docs, or

make docs-serve

to compile and open the docs in your browser.

man pages

Doxygen can be used alongside doxy2man to compile the API reference into man pages. To do this, simply run

make man
sudo make man-install

This will compile the documentation and install the man pages to the /usr/share/man/man3/ directory.

This section contains the reference for the C api.

group types

Summary

Members

enum lion_rint_model

Internal resistance models.

enum lion_soh_model

Degradation models.

enum lion_regime

Regime in which the simulation operates.

This enum indicates which domains the temperature model considers. Currently only surface simulation is allowed, but air considerations are planned.

enum lion_stepper

Stepper algorithm for the ode solver.

The types of steppers allowed are those allowed by GSL, and considers both explicit and implicit solvers.

enum lion_minimizer

Minimizer algorithm for the optimization problem.

The types of minimizers allowed are those allowed by GSL.

enum lion_jacobian_method

Jacobian calculation method.

The following methods for jacobian calculation are currently supported:

• LION_JACOBIAN_ANALYTICAL : uses the analytical equations to calculate the jacobian.

• LION_JACOBIAN_2POINT : uses central differences to numerically calculate the jacobian.

enum lion_status

Status of each lion call.

struct lion_params_init

Initialization parameters.

Summary

Members

public double soc

Initial state of charge.

public double temp_in

Initial internal temperature.

public double soh

Initial state of health.

public double capacity

Initial nominal capacity.

public double current_guess

Initial guess for the current, default is 0.

struct lion_params_ehc

Entropic heat coefficient model parameters.

Summary

Members

public double a

public double b

public double mu

public double kappa

public double sigma

public double l

struct lion_params_vft

Vogel-Fulcher-Tammann model for temperature-dependence of capacity.

Summary

Members

public double k1

public double k2

public double tref

Reference temperature.

struct lion_params_temp

Temperature model parameters.

Summary

Members

public double cp

Heat capacity of the cell.

public double rin

Interior-surface thermal resistivity of the cell.

public double rout

Surface-ambient thermal resistivity of the cell.

struct lion_params_ocv

Open-circuit voltage model parameters.

Summary

Members

public double alpha

public double beta

public double gamma

public double v0

public double vl

struct lion_params_rint_fixed

Fixed internal resistance model.

Summary

Members

public double internal_resistance

Internal resistance.

struct lion_params_rint_polarization

Current and state of charge dependent internal resistance model.

Summary

Members

public lion_mf_sigmoid_params_t c40

40A charge fuzzy parameters.

public lion_mf_gaussian_params_t c20

20A charge fuzzy parameters.

public lion_mf_gaussian_params_t c10

10A charge fuzzy parameters.

public lion_mf_gaussian_params_t c4

4A charge fuzzy parameters.

public lion_mf_gaussian_params_t d5

5A discharge fuzzy parameters.

public lion_mf_gaussian_params_t d10

10A discharge fuzzy parameters.

public lion_mf_gaussian_params_t d15

15A discharge fuzzy parameters.

public lion_mf_sigmoid_params_t d30

30A discharge fuzzy parameters.

public double poly

Polynomial coefficients.

struct lion_params_rint

Container for the internal resistance model.

Summary

Members

public lion_rint_model_t model

Model to use.

public lion_params_rint_fixed_t fixed

public lion_params_rint_polarization_t polarization

public union lion_params_rint params

Model parameters.

struct lion_params_soh_vendor

Simple vendor model.

Summary

Members

public uint64_t total_cycles

Nominal number of cycles the cell has.

public double final_soh

Nominal state of health after total_cycles (end of life)

struct lion_params_soh_masserano

Temperature and subcycle aware model.

Summary

Members

public uint64_t nominal_cycles

Nominal number of cycles the cell has.

public double nominal_sr

public double nominal_final_soh

Nominal state of health after total_cycles (end of life).

public double eq_cycles

public double eq_final_soh

public double eq_sr

public double x_table

X values for the kNN regressor.

public double y_table

y values for the kNN regressor.

public lion_vector_t eta_values

Values for the KDE.

public lion_gaussian_kde_bwmethod_t bw_method

Method for bandwidth calculation.

public struct lion_params_soh_masserano kde_params

Parameters for the KDE.

public lion_vector_t X

X values for the kNN.

public lion_vector_t y

y values for the kNN.

public struct lion_params_soh_masserano knn_params

Parameters for the kNN.

public lion_gaussian_kde_t kde

KDE instance.

public lion_knn_regressor_t knn

kNN instance.

struct lion_params_soh

Summary

Members

public lion_soh_model_t model

Model to use.

public lion_params_soh_vendor_t vendor

public lion_params_soh_masserano_t masserano

public union lion_params_soh params

Model parameters.

struct lion_params

Parameters of the system.

Summary

Members

public lion_params_init_t init

Initial conditions.

public lion_params_ehc_t ehc

Entropic heat coefficient.

public lion_params_ocv_t ocv

Open-circuit voltage.

public lion_params_vft_t vft

Temperature-dependence of capacity.

public lion_params_temp_t temp

Temperature model.

public lion_params_rint_t rint

Internal resistance model.

public lion_params_soh_t soh

Degradation model.

struct lion_sim_config

Simulation metaparameters and hyperparameters.

These parameters are not associated to the runtime of the sim itself, but rather with its configurations, choice of algorithms, parameters of those algorithms, etc.

Summary

Members

public const char * sim_name

Name of the simulation.

public lion_regime_t sim_regime

Regime to simulate.

public lion_stepper_t sim_stepper

Stepper algorithm.

public lion_minimizer_t sim_minimizer

Minimizer algorithm.

public lion_jacobian_method_t sim_jacobian

Jacobian method.

public double sim_time_seconds

Total simulation time in seconds.

public double sim_step_seconds

Time of each simulation step in seconds.

public double sim_epsabs

Absolute epsilon for update.

public double sim_epsrel

Relative epsilon for update.

public uint64_t sim_min_maxiter

Maximum iterations of each minimization problem.

public const char * log_dir

Directory for the logs.

public int log_stdlvl

Level of the stderr logger.

public int log_filelvl

Level of the file logger.

struct lion_sim_state

Simulation state variables.

This includes all relevant variables of the simulation, including electrical and thermal variables, degradation variables, etc.

Summary

Members

public double time

Simulation time.

public uint64_t step

Simulation step index (starts at 1).

public double power

Power being drawn from the cell.

public double ambient_temperature

Ambient temperature around the cell.

public double voltage

Voltage in the terminals of the cell.

public double current

Current drawn from the cell.

public double ref_open_circuit_voltage

Reference open circuit voltage of the cell.

public double open_circuit_voltage

Temperature aware open circuit voltage of the cell.

public double internal_resistance

Internal resistance of the cell.

public uint64_t cycle

Number of cycles the battery has been through.

public double soh

State of health of the cell.

public uint64_t _cycle_step

Step within the cycle.

public double _soc_mean

Average state of charge of the cycle.

public double _soc_max

Maximum state of charge of the cycle.

public double _soc_min

Minimum state of charge of the cycle.

public double _acc_discharge

Accumulated discharge.

public double ehc

Entropic heat coefficient according to an empirical model.

public double generated_heat

Heat generated by the cell due to ohmic and entropic heating.

public double internal_temperature

Internal temperature of the cell.

public double surface_temperature

Surface temperature of the cell.

public double kappa

Dimensionless variable which quantifies the changes in electrolite conductivity.

public double soc_nominal

Nominal state of charge.

public double capacity_nominal

Nominal capacity.

public double soc_use

Usable state of charge considering temperature.

public double capacity_use

Usable capacity considering temperature.

public double _next_soc_nominal

Placeholder for the next nominal state of charge.

public double _next_internal_temperature

Placeholder for the next internal temperature.

struct lion_slv_inputs

Inputs for the solver.

Both the current state and the parameters of the system are passed at each iteration of the solver, to be used for the update function as well as the Jacobian calculation.

Summary

Members

public lion_sim_state_t*sys_inputs

System state.

public lion_params_t*sys_params

System parameters.

struct lion_sim

Simulation runtime, used for setup and simulation.

This contains all the variables which will be used by the simulation, both during the setup and during the runtime on a step-by-step basis.

Summary

Members

public lion_sim_config_t*conf

Hyperparameters and sim metadata.

public lion_params_t*params

System parameters.

public lion_sim_state_t state

System state.

public lion_slv_inputs_t inputs

Inputs to the solver.

public lion_status_t(* init_hook

Hook called upon initialization.

public lion_status_t(* update_hook

Hook called on each update of the simulation.

public lion_status_t(* finished_hook

Hook called when the simulation is finished.

public gsl_odeiv2_system sys

Handle to the ode system.

public gsl_odeiv2_driver * driver

Driver for the ode system.

public gsl_min_fminimizer * sys_min

Handle to the minimizer.

public const gsl_odeiv2_step_type * step_type

Stepper used by the ode system.

public const gsl_min_fminimizer_type * minimizer

Minimizer used by the optimizer.

public char log_filename

Name of the log file.

public FILE * log_file

Handle to the log file.

public int64_t _idebug_malloced_total

public size_t _idebug_malloced_size

public _idebug_heap_info_t*_idebug_heap_head

struct lion_version

Version of the simulator.

Summary

Members

public const char * major

Major version.

public const char * minor

Minor version.

public const char * patch

Patch number.

struct lion_vector

Variable length vector of data.

Summary

Members

public void * data

Data container in heap.

public size_t data_size

Size of each element.

public size_t len

Length of the vector.

public size_t capacity

Capacity of the vector.

group functions

Summary

Members

public const char * lion_regime_name(lion_regime_t regime)

Get the name of the regime.

public const char * lion_stepper_name(lion_stepper_t stepper)

Get the name of the stepper.

public const char * lion_minimizer_name(lion_minimizer_t minimizer)

Get the name of the minimizer.

public const char * lion_gsl_errno_name(const int num)

Get the name of the GSL error number.

public const char * lion_jacobian_name(lion_jacobian_method_t jacobian)

Get the name of a jacobian calculation method.

public const char * lion_params_rint_get_name(lion_rint_model_t model)

Get the name of the internal resistance model.

public const char * lion_params_soh_get_name(lion_soh_model_t model)

Get the name of the degradation model.

public lion_params_init_t lion_params_default_init(void)

Get default initial conditions parameters.

public lion_params_ehc_t lion_params_default_ehc(void)

Get default entropic heat coefficient parameters.

public lion_params_ocv_t lion_params_default_ocv(void)

Get default open-circuit voltage parameters.

public lion_params_vft_t lion_params_default_vft(void)

Get default capacity parameters.

public lion_params_temp_t lion_params_default_temp(void)

Get default temperature parameters.

public lion_params_rint_fixed_t lion_params_default_rint_fixed(void)

Get default fixed internal resistance parameters.

public lion_params_rint_polarization_t lion_params_default_rint_polarization(void)

Get default polarization internal resistance parameters.

public lion_params_rint_t lion_params_default_rint(void)

Get default internal resistance parameters.

public lion_params_soh_vendor_t lion_params_default_soh_vendor(void)

Get default vendor degradation model parameters.

public lion_params_soh_masserano_t lion_params_default_soh_masserano(void)

Get default Masserano degradation model parameters.

public lion_params_soh_t lion_params_default_soh(void)

Get default degradation model parameters.

public lion_params_t lion_params_default(void)

Get default system parameters.

public lion_status_t lion_sim_config_new(lion_sim_config_t * out)

Create a new configuration.

Parameters

• out Variable to store the new configuration.

public lion_sim_config_t lion_sim_config_default(void)

Create a default configuration.

public lion_status_t lion_sim_new(lion_sim_config_t * conf,lion_params_t * params,lion_sim_t * out)

Create a new simulation.

Sets up the simulation with a set of configuration and parameters.

Parameters

• conf Pointer to the simulation configuration.

• params Pointer to the simulation parameters.

• out Pointer to where the sim will be created.

public lion_status_t lion_sim_init(lion_sim_t * sim)

Initialize the simulation.

public lion_status_t lion_sim_reset(lion_sim_t * sim)

Reset the simulation.

public lion_status_t lion_sim_step(lion_sim_t * sim,double power,double ambient_temperature)

Step the simulation in time.

Steps the simulation forward considering some power and ambient temperature values.

Parameters

• sim Simulation to step forward.

• power Power extracted from the cell.

• ambient_temperature Ambient temperature around the cell.

public lion_status_t lion_sim_run(lion_sim_t * sim,lion_vector_t * power,lion_vector_t * ambient_temperature)

Runs the simulation.

Runs the simulation considering a vector of values.

Parameters

• sim Simulation to run.

• power Power extracted from the cell at each time step.

• ambient_temperature Ambient temperature around the cell at each time step.

public lion_version_t lion_sim_get_version(lion_sim_t * sim)

Get the version of the simulator.

public int lion_sim_should_close(lion_sim_t * sim)

Check whether the simulation should close.

public uint64_t lion_sim_max_iters(lion_sim_t * sim)

Get the max number of iterations.

public lion_status_t lion_sim_cleanup(lion_sim_t * sim)

Clean up the simulation.

public lion_status_t lion_vector_new(lion_sim_t * sim,const size_t data_size,lion_vector_t * out)

Create new empty vector.

Parameters

• sim Simulation context, can be NULL.

• data_size Size of each element.

• out New vector.

public lion_status_t lion_vector_zero(lion_sim_t * sim,const size_t len,const size_t data_size,lion_vector_t * out)

Create new vector filled with zeros.

Parameters

• sim Simulation context, can be NULL.

• len Number of elements.

• data_size Size of each element.

• out New vector.

public lion_status_t lion_vector_with_capacity(lion_sim_t * sim,const size_t capacity,const size_t data_size,lion_vector_t * out)

Create empty vector with preallocated size.

Parameters

• sim Simulation context, can be NULL.

• capacity Preallocated size.

• data_size Size of each element.

• out New vector.

public lion_status_t lion_vector_from_array(lion_sim_t * sim,const void * data,const size_t len,const size_t data_size,lion_vector_t * out)

Create vector from array.

Parameters

• sim Simulation context, can be NULL.

• data Elements of the array.

• len Number of elements.

• data_size Size of each element.

• out New vector.

public lion_status_t lion_vector_from_csv(lion_sim_t * sim,const char * filename,const size_t data_size,const char * format,lion_vector_t * out)

Create vector from a CSV file.

Parameters

• sim Simulation context, can be NULL.

• filename Name of the file.

• data_size Size of each element.

• format Format of each line.

• out New vector.

public lion_status_t lion_vector_linspace_d(lion_sim_t * sim,double low,double high,int num,lion_vector_t * out)

Create vector of evenly spaced doubles.

Parameters

• sim Simulation context, can be NULL.

• low Lower limit.

• high Upper limit.

• num Number of elements.

• out New vector.

public lion_status_t lion_vector_linspace_f(lion_sim_t * sim,float low,float high,int num,lion_vector_t * out)

Create vector of evenly spaced floats.

Parameters

• sim Simulation context, can be NULL.

• low Lower limit.

• high Upper limit.

• num Number of elements.

• out New vector.

public lion_status_t lion_vector_to_csv(lion_sim_t * sim,lion_vector_t * vec,const char * header,const char * filename)

Save a vector into a CSV file.

Parameters

• sim Simulation context, can be NULL.

• vec Vector to save.

• header Header to use for the CSV file. For no header pass NULL.

• filename Name of the file.

public lion_status_t lion_vector_cleanup(lion_sim_t* sim,constlion_vector_t *const vec)

Destroy a vector.

public lion_status_t lion_vector_get(lion_sim_t* sim,constlion_vector_t * vec,const size_t i,void * out)

Get a given element from the vector.

Parameters

• sim Simulation context, can be NULL.

• vec Vector.

• i Index of the element.

• out Pointer to the location on which to store the output.

public int8_t lion_vector_get_i8(lion_sim_t* sim,constlion_vector_t * vec,const size_t i)

public int16_t lion_vector_get_i16(lion_sim_t* sim,constlion_vector_t * vec,const size_t i)

public int32_t lion_vector_get_i32(lion_sim_t* sim,constlion_vector_t * vec,const size_t i)

public int64_t lion_vector_get_i64(lion_sim_t* sim,constlion_vector_t * vec,const size_t i)

public uint8_t lion_vector_get_u8(lion_sim_t* sim,constlion_vector_t * vec,const size_t i)

public uint16_t lion_vector_get_u16(lion_sim_t* sim,constlion_vector_t * vec,const size_t i)

public uint32_t lion_vector_get_u32(lion_sim_t* sim,constlion_vector_t * vec,const size_t i)

public uint64_t lion_vector_get_u64(lion_sim_t* sim,constlion_vector_t * vec,const size_t i)

public float lion_vector_get_f(lion_sim_t* sim,constlion_vector_t * vec,const size_t i)

public double lion_vector_get_d(lion_sim_t* sim,constlion_vector_t * vec,const size_t i)

public void * lion_vector_get_p(lion_sim_t* sim,constlion_vector_t * vec,const size_t i)

public lion_status_t lion_vector_set(lion_sim_t * sim,lion_vector_t * vec,const size_t i,const void * src)

Set a given element from the vector. Copies the original element.

Parameters

• sim Simulation context, can be NULL.

• vec Vector.

• i Index of the element.

• out Pointer to the location to copy into the vector.

public lion_status_t lion_vector_resize(lion_sim_t * sim,lion_vector_t * vec,const size_t new_capacity)

Resizes the vector.

Parameters

• sim Simulation context, can be NULL.

• vec Vector to resize.

• new_capacity New capacity for the vector.

public lion_status_t lion_vector_push(lion_sim_t * sim,lion_vector_t * vec,const void * src)

Pushes an element into the vector.

Parameters

• sim Simulation context, can be NULL.

• vec Vector to push into.

• src Element to push. Clones this element.

public lion_status_t lion_vector_push_d(lion_sim_t * sim,lion_vector_t * vec,double src)

public lion_status_t lion_vector_push_f(lion_sim_t * sim,lion_vector_t * vec,float src)

public lion_status_t lion_vector_extend_array(lion_sim_t * sim,lion_vector_t * vec,const void * src,const size_t len)

Extends the vector using an array.

Parameters

• sim Simulation context, can be NULL.

• vec Vector to resize.

• src Elements to push. Get cloned.

• len Number of elements to push.

public size_t lion_vector_total_size(lion_sim_t* sim,constlion_vector_t * vec)

Total size of the vector.

Parameters

• sim Simulation context, can be NULL.

• vec Vector to fetch.

public size_t lion_vector_alloc_size(lion_sim_t* sim,constlion_vector_t * vec)

Allocated size of the vector.

Parameters

• sim Simulation context, can be NULL.

• vec Vector to fetch.