================================================================================
FreeTwinEV PROJECT
1S4P Battery Module Multiphysics Simulation Package - Identification and Validation
================================================================================

1. OVERVIEW
-----------
The package documents the high-fidelity multiphysics modelling workflow for the
FreeTwinEV 1S4P battery module prototype. It includes experimental input data,
simulation setup documentation, simulation outputs, solver residuals, and the
main simulation documentation workbook.

The modelled system is a reduced-scale 1S4P battery module consisting of four
Molicel INR-21700-P45B cylindrical lithium-ion cells mounted on a single-channel
liquid-cooled aluminium cold plate. The simulation workflow is used for thermal
parameter identification, coupled electro-thermal validation, and preparation of
a reusable modelling baseline for further FreeTwinEV digital-twin development.

Two simulation cases are included:
- CASE_ID22_CD  - CoolDown case, thermal transient without electrical load
- CASE_ID22_DIS - Discharge case, constant-current discharge with ECM and
                  electric-potential model enabled

2. FOLDER STRUCTURE
-------------------
FTEV_1S4P_IdentValid_SimPackage-V1/
│
├── Experiment data/
│   ├── ID22_20251210_144332381/
│   │   ├── FreeTwinEV_1s4p_ID_22.csv
│   │   ├── FreeTwinEV_1s4p_ID_22.xlsx
│   │   ├── FreeTwinEV_1s4p_ID_22_1305-3500s_Cooldown FULLDATA.xlsx
│   │   ├── FreeTwinEV_1s4p_ID_22_1305-3500s_TempAmbient.xlsx
│   │   ├── FreeTwinEV_1s4p_ID_22_1305-3500s_TempInlet.xlsx
│   │   ├── FreeTwinEV_1s4p_ID_22_4110-8105s_Discharge FULLDATA.xlsx
│   │   ├── FreeTwinEV_1s4p_ID_22_4110-8105s_BatteryCurrent.xlsx
│   │   ├── FreeTwinEV_1s4p_ID_22_4110-8105s_TempAmbient.xlsx
│   │   └── FreeTwinEV_1s4p_ID_22_4110-8105s_TempInlet.xlsx
│   │
│   └── FreeTwinEV_1s4p_experiment protocol.xlsx
│
├── Simulation data/
│   ├── CASE_ID22_CD/
│   │   ├── CASE_ID22_CD_2DresultsFULL.csv
│   │   ├── CASE_ID22_CD_SIMsetup.txt
│   │   └── CASE_ID22_CD_SolverResiduals.csv
│   │
│   └── CASE_ID22_DIS/
│       ├── CASE_ID22_DIS_2DresultsFULL.csv
│       ├── CASE_ID22_DIS_SIMsetup.txt
│       └── CASE_ID22_DIS_SolverResiduals.csv
│
├── FTEV_1S4P_IdentValid_Simulation Protocol_V1.xlsx
├── LICENSE.txt
└── README.txt - this file

3. FILE DESCRIPTIONS
--------------------

3.1 Main Simulation Documentation Workbook
FTEV_1S4P_IdentValid_Simulation Protocol_V1.xlsx

This workbook is the main documentation file for the simulation package. It
summarises the complete modelling workflow, including:
- project and simulation identification,
- physical system and geometry description,
- CAD-to-simulation simplifications,
- mesh settings and mesh quality information,
- material properties and domain assignments,
- solver setup and numerical settings,
- case-specific boundary and initial conditions,
- simulation results and comparison with experimental data,
- conclusions, limitations, and recommended next steps.

The workbook should be treated as the primary reference file for understanding
the simulation setup, modelling assumptions, and interpretation of the results.

3.2 Experiment data/
This folder contains the laboratory measurement data used for simulation input,
parameter identification, and validation.

The folder includes:
- the complete experiment protocol workbook,
- raw and processed measurement files for Experiment ID22,
- time-windowed datasets used as simulation inputs for the CoolDown and Discharge cases:
	- measured battery current profile,
	- measured coolant inlet temperature profile,
	- measured ambient temperature profile.

The experimental data are used to prescribe initial conditions, coolant boundary
conditions, ambient boundary conditions, current profiles, and validation targets
for temperature comparison.

3.3 Simulation data/
This folder contains exported simulation data for the two documented simulation cases/scenarios.

Each case folder contains:
- *_SIMsetup.txt
  Exported simulation setup information from AVL FIRE M. This file documents
  the solver settings, physics activation, material/domain assignments, boundary
  conditions, initial conditions, time stepping, and numerical setup. The ECM battery 
  model parameters are removed, as they are provided by 3rd party and cannot be published openly.

- *_2DresultsFULL.csv
  Exported full simulation result data used for post-processing and comparison with
  the experimental measurements.

- *_SolverResiduals.csv
  Solver residual history used to check numerical convergence during the
  transient simulation.


4. TECHNICAL CONTENT
--------------------
The simulation package documents a high-fidelity 3D multiphysics model including:
- conjugate heat transfer between cells, thermal interfaces, cold plate, and
  coolant,
- CFD solution of the coolant domain,
- anisotropic homogenised representation of the cell active material,
- resolved casing, poles, busbars, thermal pad, cold plate, coolant, and sensor
  domains,
- effective thermal contact resistances between relevant interfaces,
- electrical current-path modelling for the discharge case,
- 3rd party 2RC equivalent circuit model for cell heat generation in the discharge case, 
  without parameters

The CoolDown case is primarily used to validate the thermal and CFD part of the
model. The Discharge case is used as a coupled electro-thermal benchmark and
to evaluate the limitations of the available commercial ECM parameterisation.

5. RELATED DATASETS AND REFERENCES
----------------------------------
Related FreeTwinEV datasets and documentation:
- FreeTwinEV D3.1 CAD model documentation:
  https://doi.org/10.5281/zenodo.19915213

- FreeTwinEV 1S4P experimental measurement dataset:
  https://doi.org/10.5281/zenodo.18405243

The CAD geometry, physical prototype description, and experimental measurement
protocol are documented in the related FreeTwinEV D3.1 and 1S4P module
documentation.

6. TECHNICAL REQUIREMENTS
-------------------------
Recommended software for viewing and processing the files:
- Microsoft Excel or equivalent spreadsheet software for documentation and
  experimental data files.
- Text editor for exported simulation setup files.
- CSV-compatible post-processing tool for result and residual files
  (e.g. Python, MATLAB, Excel, ParaView-compatible workflow, or similar).
- AVL FIRE M 2025 R2 or compatible AVL environment for interpretation of the
  exported simulation setup in the original solver context.

The package is intended primarily for documentation, traceability, validation,
and post-processing. It does not necessarily contain all native solver project
files required to rerun the simulations from scratch.

7. LICENSE & USAGE
------------------
Please refer to the LICENSE.txt file for terms of use, distribution rights, and
citation requirements for the FreeTwinEV project assets.

When using this dataset, cite the final Zenodo record assigned to this simulation
package after publication, together with the related FreeTwinEV CAD and
experimental datasets where appropriate.

8. CONTACT
----------
For questions or additional details regarding the simulation setup, experimental
data, or result interpretation, contact:

Martin Baťa
Slovak University of Technology in Bratislava
martin.bata@stuba.sk

--------------------------------------------------------------------------------
END OF README
--------------------------------------------------------------------------------