# README: Minimum Lap Time Simulation Framework (MLTP) in MATLAB


### 1. Description
The Minimum Lap Time Problem (MLTP) framework is designed to find the fastest possible lap time by optimising the race-line, control inputs, and vehicle configuration along a given track.

This framework is built using an optimal control approach with direct collocation and leverages CasADi and the IPOPT solver to define and solve the optimisation problem.

The MLTP is based on the original MLTP framework by Zarzuelo & Siampis [1] and the progression by Jiménez et al. [2], but extends its capabilities with:
- Enhanced vehicle model featuring advanced active aerodynamics and torque distribution.
- Expanded optimisation functionalities to explore performance improvements across different aerodynamic and drivetrain configurations.


### 2. System Requirements
To run MLTP, you will need:
- MATLAB: R2021b to R2022b (older versions may work but are not tested).
- Simulink: R2021b to R2022b.
- CasADi: Version 3.5.5 (Download from https://web.casadi.org/get/). After downloading, add CasADi's folder to MATLAB path.


### 3. Case-Specific Information
The optimisation framework is utilised for the DrivAer hp-F vehicle model exclusively on the Circuit de Barcelona-Catalunya.
The DrivAer hp-F vehicle model features: 
- A split front wing:         Independent left and right angle of attack control.
- A tilt rear wing:           Adjustable angle of attack and tilt angle.
- An all-wheel-drive system:  Fixed front-to-rear drive and brake torque distribution.
- Active Torque Distribution: Individual drive and brake torque control per wheel.

## Aerodynamic configurations include:
- Static:   Fixed symmetric front and rear wing angles.
- ActiveRW: Fixed symmetric front wing, active symmetric rear wing.
- Active:   Active symmetric front and rear wing control.
- AALB:     Active asymmetric front and rear wing control.

## Torque distribution configurations include:
- ATD Off: Standard all-wheel-drive.
- ATD On:  Active torque distribution.


### 4. Framework Structure
The MLTP framework consists of six main folders:

## 1. Aerodynamics/
- .mat file containing data on the vehicle's nominal aerodynamic performance and polynomial coefficients describing the influence of each element on aerodynamic performance.
- The data is derived from Computational Fluid Dynamics (CFD) simulations on the DrivAer hp-F model with active aerodynamics, detailed further in [3].
- The data includes: 
  - FW_L, FW_R, RW, TW: Polynomial aerodynamic relationship coefficients for front left wing, front right wing, rear wing, and rear wing tilt angle.
  - veh: Nominal aerodynamic coefficients representing the vehicle's baseline aerodynamic performance without all aerodynamic elements at the neutral position.

## 2. Circuits/
- Contains track data for various circuits.

## 3. Data/
- Initialisation/ contains data used for initialising the considered vehicle configuration cases.
- Results/ contains results for all aerodynamic and torque distribution configurations.
  - AA/ contains results for all aerodynamic configurations using all-wheel drive, with optimised vehicle design parameters.
  - AA_TV/
    - ParamOpt/ contains results for all aerodynamic configurations using active torque distribution, with optimised vehicle design parameters.
    - TyreOpt/  contains results for various aerodynamic and torque distribution configurations, with optimised tyre characteristics. 

## 4. Functions
- Contains various functions used throughout the framework.

## 5. Parameters
- "Powertrain.m": Defines powertrain parameters.
- "vehParams.m": Defines vehicle parameters used in the vehicle model.

## 6. Scripts
This folder contains the core simulation scripts:

# Simulation Scripts:
- "MLTP.m": Standard MLTP case, optimising trajectory and control inputs.
- "MLTP_paramOptim.m": Optimises trajectory, control inputs, and selected vehicle design parameters (torque, brake, and roll stiffness distribution).
- "MLTP_TyreOptim.m": Optimises trajectory, control inputs, and nominal tyre load shift parameter (shifts nominal tyre load at which peak force occurs without influencing the peak tyre force magnitude).
- "MLTP_initial.m": Runs a simplified optimisation that can be used to initialise MLTP scripts.

# Supporting Scripts:
- "plotSDI.m": Visualises results using Simulink Data Inspector.
- "userOpts.m": Defines user options for vehicle configuration, track, and optimisation settings.
- "vehModel.m": Defines the vehicle model using symbolic equations with CasADi.
- "vehModel_initial.m": Simplified vehicle model used for initialisation.


### 5. Getting Started

## Step 1: Install Dependencies
1. Install MATLAB & Simulink (R2021b to R2022b).
2. Download CasADi v3.5.5 and add its folder to the MATLAB path.

## Step 2: Set Up the Framework
1. Download the MLTP repository.
2. Add all MLTP folders to the MATLAB path.

## Step 3: Define vehicle and powertrain parameters in "vehParams.m" and "Powertrain.m".

## Step 4: Define vehicle configuration, track, and optimisation settings in "userOpts.m".

## Step 5: Run a Simulation
The framework provides several simulation options, depending on the scope of the optimisation.
- For lap time optimisation with the selected vehicle parameters: run the "MLTP.m" script.
- For lap time optimisation including design parameter optimisation: run the "MLTP_paramOptim.m" script.
- For lap time optimisation including tyre characteristics optimisation: run the "MLTP_TyreOptim.m" script.
- For lap time optimisation of a single-track initialisation case: run the "MLTP_initial.m" script.
Each script calls the "plotSDI.m" script to visualise the results once the simulation has finished.


### 6. Usage Notes

## Case-Specific Optimisation Setup
The MLTP framework is specifically tuned for the DrivAer hp-F model with active aerodynamics and torque distribution on the Circuit de Barcelona-Catalunya.
Running the framework on a different vehicle or track without modifications may lead to poor optimisation performance or convergence issues.
Key case-specific elements include:
- Regularisation factors and solver settings adjusted for numerical stability and performance.  
- Predefined initialisation data and initial conditions, ensuring a robust starting point for this case study.  

## Extending the Framework
The MLTP framework is adaptable to different vehicles, tracks, and configurations, and users are encouraged to extend it.
However, users should carefully review and implement changes consistently across all relevant scripts.
Applying the framework to a new scenario requires:  
1. Defining a new initialisation case and initial conditions suited to the updated vehicle and/or track.  
2. Re-tuning optimisation settings, including regularisation factors, solver parameters, and constraints.  
3. Ensuring consistency across scripts, particularly:
   - vehModel.m: Must reflect updated vehicle dynamics and capabilities.  
   - Optimisation scripts (MLTP.m, MLTP_paramOptim.m, MLTP_TyreOptim.m): Should align with the new case.  
   - Aerodynamic, powertrain, and vehicle parameters: Must be updated to match the new application.  


### 7. Publication Reference:
This dataset is associated with the following publications:

# Rijns, S., Teschner, T. R., Blackburn, K., Siampis, E., & Brighton, J. (2024). 
  Optimising Vehicle Performance with Advanced Active Aerodynamic Systems [In Review]. 
  Advanced Vehicle Engineering Centre, Cranfield University.

# Rijns, S., Teschner, T. R., Blackburn, K., Siampis, E., & Brighton, J. (2024). 
  Performance Optimisation of High-Performance Vehicles with Active Aerodynamics and Active Torque Distribution Capabilities [In Review]. 
  Advanced Vehicle Engineering Centre, Cranfield University.

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

References:
[1] Adrián Zarzuelo, Efstathios Siampis (2022). MLTP (https://www.mathworks.com/matlabcentral/fileexchange/119398-mltp), MATLAB Central File Exchange.
[2] Jiménez Elbal, A., Zarzuelo Conde, A., & Siampis, E. (2024). 
    Simultaneous Optimisation of Vehicle Design and Control for Improving Vehicle Performance and Energy Efficiency Using an Open Source Minimum Lap Time Simulation Framework.
    World Electric Vehicle Journal, 15(8), 366. https://doi.org/10.3390/wevj15080366
[3] Steven Rijns, Tom-Robin Teschner, Kim Blackburn, James Brighton; 
    Performance analyses of active aerodynamic load balancing designs on high-performance vehicles in cornering conditions. 
    Physics of Fluids. 2024; 36 (8): 085199. https://doi.org/10.1063/5.0222780