README.md 3.48 KB
Newer Older
Gavin Wiggins's avatar
Gavin Wiggins committed
1
# JupyterLab notebooks for VIBE
Gavin Wiggins's avatar
Gavin Wiggins committed
2

Gavin Wiggins's avatar
Gavin Wiggins committed
3
This repository contains JupyterLab notebooks for the VIBE example cases.
4

5
## Notebooks
6

Gavin Wiggins's avatar
Gavin Wiggins committed
7 8
The notebooks can be run using [VIBE cloud](https://vibe.ornl.gov/jupyter) or on a local machine using Docker. A summary of the available Jupyter notebooks is provided below.

Gavin Wiggins's avatar
Gavin Wiggins committed
9 10
**cylindrical-cell** - Demonstrate the coupling of electro-chemistry, electrical flow, and thermal transport models for a cylindrical cell.

Gavin Wiggins's avatar
Gavin Wiggins committed
11 12 13
**ecm-hppc-discharge** - A two RC-circuit equivalent circuit model (ECM) developed from HPPC tests. A thermal component is coupled to the ECM to estimate temperature profiles from discharge tests.

**ecm-thermal** - Example of using a two RC-circuit ECM to provide input parameters to a VIBE simulation which estimates the heat-up of a pouch cell.
14 15 16

**ntg-thermal** - This NTG model describes the overall characteristics of the cell without resolving local kinetics of electrochemical reactions or the internal concentration and potential gradients within the cell-sandwich.

Gavin Wiggins's avatar
Gavin Wiggins committed
17 18 19 20
**pouch-cell** - Pouch cell example where NTG model coefficients are based on NMC-Graphite cell discharge profiles.

**unrolled-cell** - Example of coupling the electro-chemistry and thermal transport models for an unrolled cell.

Gavin Wiggins's avatar
Gavin Wiggins committed
21 22 23
## Docker

The notebooks can be run within a Docker container by using the included Dockerfile to create a local image of the VIBE environment. The Dockerfile is based on the [docker-stacks](https://github.com/jupyter/docker-stacks) SciPy notebook example provided by Jupyter. Commands for running the Jupyter notebooks with Docker are given below.
24 25

```bash
Gavin Wiggins's avatar
Gavin Wiggins committed
26 27 28 29 30 31 32 33 34 35 36 37 38
# Build a Docker image from the Dockerfile
# Run this command from within the folder containing the Dockerfile
# In this example the image will be named `myimage`
docker build -t myimage .

# Create and run a new container and publish its ports to the host machine
# In this example the created container is named `myvibe`
docker run --name myvibe -it -p 8888:8888 myimage bash

# From within the container run JupyterLab using the command shown below. This
# command will create a URL that can be copied and pasted into the web browser
# of the local machine.
jupyter lab --ip 0.0.0.0 --no-browser --allow-root
39

Gavin Wiggins's avatar
Gavin Wiggins committed
40
# Atlernatively you can create, run docker container and jupyterlab using the
41
# command below. The generated URL can be copied into web browser of local
Gavin Wiggins's avatar
Gavin Wiggins committed
42
# machine.
43
docker run --rm -p 8888:8888 -e JUPYTER_ENABLE_LAB=yes -v "$PWD":/home/jovyan/work myimage
44 45
```

Gavin Wiggins's avatar
Gavin Wiggins committed
46 47 48 49 50 51
To quit the Jupyter notebook, choose File then Shutdown from the JupyterLab menu. Then, quit the Docker container by entering the `exit` command in the terminal.

Use the following commands to restart the container and run JupyterLab.

```bash
# Start the existing `myvibe` container and run JupyterLab from the container
52 53
# Don't forget to copy and paste the JupyterLab URL into your local web browser
docker start -i myvibe
Gavin Wiggins's avatar
Gavin Wiggins committed
54 55
jupyter lab --ip 0.0.0.0 --no-browser --allow-root

Gavin Wiggins's avatar
Gavin Wiggins committed
56 57
# After exiting the container terminal session with `exit`, stop the running
# container with the following command
Gavin Wiggins's avatar
Gavin Wiggins committed
58 59 60 61 62 63 64
docker stop myvibe

# If `myvibe` was successfully stopped, it will not show in the list of running
# containers. View the list of running contains with the `ps` command.
docker ps
```

Gavin Wiggins's avatar
Gavin Wiggins committed
65 66 67 68 69
The Docker image and container take up several gigabytes of storage on the local machine. To remove the container and image from your computer, perform the commands shown next.

```bash
# Remove the `myvibe` container
docker rm myvibe
70

Gavin Wiggins's avatar
Gavin Wiggins committed
71 72 73
# Next, remove the Docker image named `myimage`
docker rmi myimage
```