UL Battery Research API

A Django REST Framework backend to process, analyze, and serve cycle-life data from UL's Electrochemical Safety Research Institute. This project provides a ranked summary of battery performance based on durability and resilience.

---

Features

• Processes raw, multi-sheet Excel data for 21 battery cells (1.5 million raw data points from UL Research).
• Calculates key performance metrics like State of Health (SOH) and overall averages.
• Implements a weighted ranking algorithm to score battery performance.
• Provides a clean, filterable REST API to serve the analyzed data.
• Includes a health-check endpoint to support client-side caching.

---

Technology Stack

• Backend: Django, Django REST Framework
• Data Processing: Pandas
• Database: PostgreSQL (production), SQLite (development)

---

Getting Started (Local Development)

Prerequisites

• Python 3.10+
• Git LFS (for pulling the data files)

Local Setup

1. Clone the repository:

   git clone [https://github.com/TruLie13/BE-UL-Battery-Project.git](https://github.com/TruLie13/BE-UL-Battery-Project.git)
   cd BE-UL-Battery-Project

2. Pull LFS files:

   git lfs install
   git lfs pull

3. Create and activate the virtual environment:

   # On macOS/Linux
   python3 -m venv venv
   source venv/bin/activate

4. Install dependencies:

   pip install -r requirements.txt

5. Initialize and populate the database:

   # Run migrations to create the database schema
   python manage.py migrate
   
   # Run the heavy script to perform all calculations and populate the local DB.
   # This also generates a summary.csv file needed for production deployment.
   python manage.py load_battery_data

6. Run the development server:

   python manage.py runserver

   The API will be available at http://127.0.0.1:8000/api/.

---

Deployment (Fly.io)

Prerequisites

• A Fly.io account.
• The Fly.io CLI, flyctl.

Deployment Steps

1. Launch the App: This command creates your application on Fly.io and generates a fly.toml configuration file. Answer "no" (N) when asked to deploy immediately.

   fly launch

2. Create a Database: Provision a persistent PostgreSQL database for your application.

   fly postgres create

3. Set Secrets: Securely provide your app with the database connection URL given to you in the previous step.

   fly secrets set DATABASE_URL="postgres://..."

4. Deploy: Deploy your application to Fly.io.

   fly deploy

5. Run Final Commands: After deployment, connect to your app's console to run the final setup commands.

   # Connect to the live server
   fly ssh console
   
   # Inside the SSH session, run migrations and load the pre-calculated data
   python manage.py migrate
   python manage.py load_prod_data

---

API Endpoints

• GET /api/summary/

  • Returns a summary of all batteries, ranked by a balanced performance score.

• GET /api/health-check/

  • Returns the timestamp of the last data import to support client-side caching.

• GET /api/batteries/<voltage_type>/

  • Returns a list of batteries for the specified voltage_type (normal or reduced).

• GET /api/batteries/<voltage_type>/<battery_number>/

  • Returns the full detail for a single battery.

---

Data Source & Acknowledgements

This project uses open-source data provided by UL Research Institutes.

• Original Data Source: UL-FRI Open Science Data
• Specific Dataset: Cycle Life Aging Test – Cylindrical Cell – Part 01 (DOI: 10.5281/zenodo.7658812)