Style Guide

Style guide for Ionworks pipeline and any associated customer repositories. For standards that are specific to battery modeling and parameterization, see the terminology standards.

General

  • Use ruff for formatting (set up pre-commit hook)

  • Use comments where needed but not excessively. Comments should be used to explain why something is done, not what is done. Comments should be understandable by a competent engineer, who may not be familiar with the codebase or the specific problem being solved.

  • Use pathlib instead of os.path for file paths, with / as the path separator.

Variable naming standards

  • Use snake_case for variable names

  • Use descriptive variable names (typically a descriptive variable name is preferred over a comment)

  • Use the variable name to describe the data it holds, not the type of the variable

Some specific variables appear often and should be named consistently:

  • save_dir for the directory where generic results are saved

  • figs_dir for the directory where figures are saved

  • params_dir for the directory where fitted parameters are saved

  • data_dir for the directory where data is stored

  • this_dir for the directory of the current file

Directory naming standards

For each battery parameterization, start a new folder for that specific battery containing the following subdirectories:

  • 00_preprocess: data preprocessing code to convert to the correct format for the pipeline

  • 01_fit: code to parameterize the model

  • 02_validate: code to plot the parameterized model against validation data

The following directory names should be used consistently throughout customer codebases:

  • “figures” for the directory where figures are saved

  • “fitted_parameters” for the directory where fitted parameters are saved