pybamm-team / pybamm-cookiecutter

A cookiecutter template for battery modeling projects using PyBaMM

pybamm-cookiecutter

This repository contains a copier template for battery modeling projects using PyBaMM, released under the BSD-3-Clause license. Currently under active development.

📄 Using pybamm-cookiecutter

Generating projects with pybamm-cookiecutter manually using copier

This template is not on PyPI yet, so it cannot be installed through pip until the first release. Meanwhile, it can be used by cloning this repository and using copier to generate a project with this template.

Install copier and jinja2_time extension using pip.

pip install copier jinja2-time

Generate a project from the pybamm-cookiecutter template. Note: This requires an internet connection. You could manually clone the git repository and run the copy command, or just execute the copy command with the URL to the git repository.

copier copy https://github.com/pybamm-team/pybamm-cookiecutter.git name_of_your_project/ --trust

Copier will prompt you with various configurations and you may choose the ones that suit your use case.

Note: A git repository is automatically initialised when a project is created within a directory.

After generation, you can navigate to the generated project and run nox -s generated-project-tests to ensure if the project units are working as intended.

Installing the pybamm-cookiecutter project

This refers to the project used for the development of this template. There are two ways to install this project: either through nox or pip. nox uses uv pip or pip internally, and in this case, creates a virtual environment for you to activate. To install, navigate to the root directory of this repository and execute either of these commands:

nox -s dev or pip install -e .[dev]

To check if the project was successfully installed, import the project inside Python.

import pybamm_cookiecutter

pybamm_cookiecutter.__version__

🛠️ Contributing to pybamm-cookiecutter

If you'd like to help us develop pybamm-cookiecutter by improving the template's features, writing documentation, or fixing embarrassing bugs, please have a look at these guidelines.

📫 Get in touch

For any questions, comments, suggestions or bug reports, please see the contact page.

📃 License

The pybamm-cookiecutter project is open source code. For more information about its license, see LICENSE.

pybamm-cookiecutter's Issues

Issues when trying the template

I tried copying the template using copier (in WSL, Python 3.11) and I have spotted the following issues:

• User name needs to be passed between quotation marks, but this is not specified. Probably we could keep things as they are an pass the quotation marks ourselves when calling the git config user.name command.
• When calling nox (either generated-project-tests or dev) I get the following error:

nox > Running session dev
nox > Creating virtual environment (virtualenv) using python3.11 in .nox/dev
nox > python -m pip install virtualenv
nox > virtualenv /home/brosaplanella/LTES/encapsulated_LTES/venv
nox > /home/brosaplanella/LTES/encapsulated_LTES/venv/bin/python -m pip install -e '.[dev]'
nox > Warning: /home/brosaplanella/LTES/encapsulated_LTES/venv/bin/python is not installed into the virtualenv, it is located at /home/brosaplanella/LTES/encapsulated_LTES/venv/bin/python. This might cause issues! Pass external=True into run() to silence this message.
Obtaining file:///home/brosaplanella/LTES/encapsulated_LTES
ERROR: Exception:
Traceback (most recent call last):
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/cli/base_command.py", line 179, in exc_logging_wrapper
    status = run_func(*args)
             ^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/cli/req_command.py", line 67, in wrapper
    return func(self, options, args)
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/commands/install.py", line 377, in run
    requirement_set = resolver.resolve(
                      ^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/resolution/resolvelib/resolver.py", line 76, in resolve
    collected = self.factory.collect_root_requirements(root_reqs)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/resolution/resolvelib/factory.py", line 538, in collect_root_requirements
    reqs = list(
           ^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/resolution/resolvelib/factory.py", line 494, in _make_requirements_from_install_req
    cand = self._make_base_candidate_from_link(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/resolution/resolvelib/factory.py", line 210, in _make_base_candidate_from_link
    self._editable_candidate_cache[link] = EditableCandidate(
                                           ^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/resolution/resolvelib/candidates.py", line 328, in __init__
    super().__init__(
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/resolution/resolvelib/candidates.py", line 158, in __init__
    self.dist = self._prepare()
                ^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/resolution/resolvelib/candidates.py", line 235, in _prepare
    dist = self._prepare_distribution()
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/resolution/resolvelib/candidates.py", line 338, in _prepare_distribution
    return self._factory.preparer.prepare_editable_requirement(self._ireq)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/operations/prepare.py", line 698, in prepare_editable_requirement
    dist = _get_prepared_distribution(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/operations/prepare.py", line 72, in _get_prepared_distribution
    abstract_dist.prepare_distribution_metadata(
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/distributions/sdist.py", line 39, in prepare_distribution_metadata
    self.req.load_pyproject_toml()
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/req/req_install.py", line 511, in load_pyproject_toml
    pyproject_toml_data = load_pyproject_toml(
                          ^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_internal/pyproject.py", line 64, in load_pyproject_toml
    pp_toml = tomli.loads(f.read())
              ^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_vendor/tomli/_parser.py", line 102, in loads
    pos = key_value_rule(src, pos, out, header, parse_float)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_vendor/tomli/_parser.py", line 326, in key_value_rule
    pos, key, value = parse_key_value_pair(src, pos, parse_float)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_vendor/tomli/_parser.py", line 369, in parse_key_value_pair
    pos, value = parse_value(src, pos, parse_float)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_vendor/tomli/_parser.py", line 616, in parse_value
    return parse_array(src, pos, parse_float)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_vendor/tomli/_parser.py", line 420, in parse_array
    pos, val = parse_value(src, pos, parse_float)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_vendor/tomli/_parser.py", line 620, in parse_value
    return parse_inline_table(src, pos, parse_float)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/brosaplanella/LTES/encapsulated_LTES/venv/lib/python3.11/site-packages/pip/_vendor/tomli/_parser.py", line 461, in parse_inline_table
    raise suffixed_err(src, pos, "Unclosed inline table")
pip._vendor.tomli.TOMLDecodeError: Unclosed inline table (at line 10, column 14)

• The issue above was caused because in the pyproject.toml we already include quotation marks, so adding them again as I suggested earlier ended up with double quotation marks which upsetted nox. I removed them manually and now it works, so it seems both issues are related.
• The README does not mention that the user needs to manually create and push to the Github repo. Pretty obvious, but given that we ask people the name of the repo when generating the project it is a bit misleading.

Might add more issues later if I find more (edit, previous issue went away when upgrading nox, we should require most recent version or later in the docs).

Documentation about `pybamm-cookiecutter`

A placeholder issue for keeping track of documentation-related tasks.

• Set up an initial draft for documentation pages for the project: installation, technical details, user guide, adding data paths, adding parameter sets, and more
• Surrounding infrastructure for building the documentation locally (tracked by #4)
• In the project's documentation: a basic guide to using Sphinx, adding example notebooks and scripts, adding thumbnail galleries, adding a references page, troubleshooting, and FAQs.
  • Possibly, some utility functions for registering citations in both code and documentation, similar to PyBaMM's citation workflow
• Surrounding infrastructure for deploying the documentation on Read the Docs in the CI. It should have PR builds on each commit, cancelling the build on subsequent pushes to a branch

See also: #1

Tracker for first PyPI release

Overview

This issue tracks all the tasks that need to be checked before the first PyPI release for the pybamm-cookiecutter template.

Tasks

Migrations

• Migrate the following contents of the project to the template -
  • entry points, for both parameter_sets and models. #27
  • tests specifically to be shipped to the user inside the template, i.e. the entry points tests and an example test file for the users to add test cases. #29
  • models & parameter_sets included in the project, i.e. SPM and Chen2020. #27
  • nox-sessions that are not present in the template. They would be - unit tests(yet to be separated), coverage and dev session. #29
  • Move suitable test_on_push CI to the template. #29

Features

• Separate nox sessions for tests for project and tests for template. #29
• Two steps in the CI for tests for project and tests for template. #29
• Add example notebooks for using cookiecutter template and entry points.
• Add the reservoir model. #30
• Script for automatic git init while project generation using the template. Could be referred here. #32 ---> #34
• Add Dependabot for CI. #28
• Migration to copier. #34
• CD for publishing.
• Add a wrapper CLI for generating a project using copier. #36
• Add setuptools backend. #37
• Add a basic CI for gitlab-ci.yml.
• Add versioning support for git archives #42

Misc

• Attribute inspirations #43
• Rename to pybamm-cookie
• More documentation in README (maybe the logo too?)

PS

If there is something else to add or is missing, please feel free to edit this comment and append it.

Implement `nox -s docs` in the CI

This issue is just to keep track of the suggestion made in #17

Repository structure (file layouts, cookiecutter templating engines, distribution options)

Starting this as a placeholder issue for tracking down tasks to be completed and those that are complete. I will be dividing these into separate issues and PRs

Cookiecutters

1. https://github.com/cookieninja-generator/cookieninja
2. https://github.com/cookiecutter/cookiecutter

as suggested by @Saransh-cpp

Examples

1. https://github.com/osl-incubator/scicookie
2. https://github.com/scientific-python/cookie
3. https://github.com/copier-org/copier
4. https://github.com/cruft/cruft/
5. Cookiecutter Data Science (drivendata.github.io)

Suggestions from @brosaplanella:

1. "A bit different, but Julia has DrWatson.jl which has many cool features, maybe we can get some ideas".
2. A figures folder (with a .gitkeep)
3. A data folder (later we could have some pipelines to process it, like the Data Science example above).

Possible layout

The folder structure can look like this

├── .github/workflows
├── src
├── data
└── docs
      ├── examples  # notebooks that can be rendered with nbsphinx
      ├── _static
      ├── sphinxext
      ├── source
      └── conf.py
├── tests  # (optional)
├── parameters
    └── my_parameters.py  # contains the get_parameter_values() function
├── examples/  # alternatively, example scripts or notebooks that are not to be rendered with the Sphinx builder
├── pyproject.toml
├── README.md
├── .pre-commit-config.yaml
├── .readthedocs.yaml
├── .env # contains DATA_PATH
├── noxfile.py  # (or tox.ini, if users want to use tox)

The required documentation should

• Explain how to clone this template to start a new project
• Explain how to rename the project in pyproject.toml and docs/conf.py
• Explain how to structure a typical project with source files and utility classes and methods (in src/), unit tests with
• Parameter entry points in pyproject.toml, with

[project.entry-points.pybamm_parameter_sets]
MyParameters = "package_name.parameters.my_parameters:get_parameter_values"

• Point to the PyBaMM documentation wherein the developments and advancements in this repository shall be reflected on a separate page or section in the user guide

which can then be accessed as pybamm.ParameterValues(“MyParameters”) in the source code.

Tracked in #6.

Configuration options

Build-backends

1. hatch
2. flit
3. poetry
4. setuptools (later)

Documentation

1. Theme
2. Sphinx extensions

Project structure

1. Project metadata in pyproject.toml
2. and so on

Available licenses (#2)

1. MIT
2. Apache-2.0
3. BSD-3-Clause
4. and so on (should be permissive licenses suitable for collaborative research practices and open science)

---

Addendum 27/02/2024: another thing we would want would be entry points for models in the PyBaMM model structure rather than just parameter sets, please see pybamm-team/PyBaMM#3839 (comment)

Test `nox -s dev` on CI?

I tried this locally and it isn't working – uv doesn't seem to properly install dependencies into a virtualenv-created environment. I think it needs itself to create the virtual environment, i.e., using uv venv. I don't wish to hold the PR, so maybe we can use the original, non-uv solution and fix this later?

Originally posted by @agriyakhetarpal in #15 (comment)