# Breathe Design

A python based api wrapper for running the breathe design model.

# Installation

```
python -m venv venv
```

Activate the virtual environment

```
.\venv\Scripts\activate
```

Install the package in developer mode by cloning the repository and navigating to the main folder in a terminal

```
pip install breathe_design
```

# Running the models

The app requires a connection to our server for which you must log in to receive an api key. Once logged in you can fetch the batteies in your library.

```
from breathe_design import api_interface as api
batteries = api.get_batteries()
print(batteries)
```

Access the base parameters for your battery

```
base_params = api.get_design_parameters("Molicel P45B")
print(base_params)
```

See the equilibrium KPIs and there sensitivities to changes in the base parameters

```
eqm_kpis, fig = api.get_eqm_kpis("Molicel P45B")
print(eqm_kpis)
fig.show()
```

Add any number of new designs

```
designs = [
    {
      "designName": "Lower NP",
      "NPratio": base_params["NPratio"]*0.95
    },
    {
      "designName": "Higher Vmax",
      "Vmax_V": base_params["Vmax_V"]+0.05
    },
    {
      "designName": "Thicker Cathode",
      "cathodeThickness_um": base_params["cathodeThickness_um"]*1.05
    },
    {
      "designName": "Less Porous Anode",
      "anodePorosity": base_params["anodePorosity"]*0.95
    },
    {
      "designName": "Thinner Separator",
      "separatorThickness_um": base_params["separatorThickness_um"]*0.95
    },
  ]
```

Recompute the KPIs

```
eqm_kpis, fig = api.get_eqm_kpis("Molicel P45B", designs)
print(eqm_kpis)
```

Plot the KPIs for all designs `relative` or `delta` with the baseline

```
from breathe_design import plot_kpis
plot_kpis(eqm_kpis, "relative")
plot_kpis(eqm_kpis, "delta")
```

Perform dynamic analysis for your designs

```
from breathe_design import Cycler
from breathe_design import plot_dynamic_kpis
from breathe_design import extract_dynamic_kpis

baseline_capacity = eqm_kpis.loc["Capacity [Ah]", "Baseline"]
cycler = Cycler(selected_unit="C", cell_capacity=baseline_capacity)
cycler_input = cycler.cccv(1.0, -1.0, 0.01, 4.2, 2.6, 60.0, 60.0)
output = api.run_sim(
    base_battery="Molicel P45B",
    cycler=cycler.cccv(1.0, -1.0, 0.01, 4.2, 2.6, 60.0, 60.0),
    designs=designs,
    initialSoC=0.5,
    initialTemperature_degC=21.0,
    ambientTemperature_degC=21.0
    )
plot_dynamic_kpis(output["dynamicData"])
```

Let's now try changing the form factor

```
base_format = api.get_battery_format("Molicel P45B")
smaller_format = base_format.copy()
smaller_format["name"] = "Smaller Format"
smaller_format["height_mm"] = 0.9 * base_format["height_mm"]
thinner_format = base_format.copy()
thinner_format["name"] = "Thinner Format"
thinner_format["diameter_mm"] = 0.9 * base_format["diameter_mm"]
formats = [smaller_format, thinner_format]
eqm_kpis, fig = api.get_eqm_kpis("Molicel P45B", designs=[], formats=formats)
eqm_kpis
```

# Release public repo (docs and examples)

This repo is private, and not intended to be shown to customers.

Instead, there is another public repo that IS intended to be shown to customers.  This public repo is a submodule of this repo for the purposes of this release machinary only.

The scripts in [public_release_scripts](public_release_scripts) manage releasing (copying) select files from this repo, to that public repo.

Run

```
python public_release_scripts\create_public_release.py
```

to perform the release.  This will pull main in the submodule, create a new branch, copy the new files accross, and push the branch.  It will open an MR to merge the public documents (this step requires a gitlab token though - you can skip it and do it manually).

**This step must currently be run manually until the gitlab CI step is fixed**

# Release wheel

The wheel generates by this repo is uploaded to out private repository in JFrog, and also to the public PyPi repository.

On MRs, the wheel is optionally (via a manual CI step) released to `https://test.pypi.org/legacy/`.
See [buildAndUploadPackageToTestPypi.ps1](buildAndUploadPackageToTestPypi.ps1) for

# Changelogs

[CHANGELOG.md](CHANGELOG.md) is an internal changelog.  Note your changes in here as normal, for a developer audience.

[PUBLIC_CHANGELOG.md](PUBLIC_CHANGELOG.md) is a PUBLIC changelog.  It is copied to the public repo on release, so must be worded as for a public audience.

# Troubleshooting

See the [TROUBLESHOOTING.md](TROUBLESHOOTING.md) file for troubleshooting errors.
