# ALPHA_REVS3 BEV/P0/P2/PS Peer Review

Overview
--------
EPA’s ALPHA model is a full vehicle simulation model which estimates the greenhouse gas (GHG) emissions from light-duty vehicle sources. ALPHA is a physics-based, forward-looking, full vehicle simulator, capable of simulating various vehicle types and powertrain technologies. 

ALPHA was used by EPA to inform the 2016 Draft Technical Assessment Report of light-duty vehicle greenhouse gas standards for model years 2022-2025, as well as the 2016 Proposed Determination under the Midterm Evaluation.  ALPHA is an in-house vehicle simulation model used by EPA, and is not intended to be a commercial product.

The ALPHA model shares an underlying structure with EPA's Greenhouse Gas Emissions Model (GEM) used for medium- and heavy-duty vehicle compliance calculations. ALPHA is under active development and the versions of the model presented below represent the state of the package at particular points in time.

This repository is the home for pre-public-release ALPHA collaboration and testing.

Documentation
-------------
ALPHA Documentation source code is located at https://github.com/USEPA/EPA_ALPHA_Model

The `EPA_ALPHA_Model` repo will eventually be the home for public ALPHA model releases.

The published documentation homepage is https://epa-alpha-model.readthedocs.io/en/latest/

The latest .pdf docs are available at https://epa-alpha-model.readthedocs.io/_/downloads/en/latest/pdf/

Requirements
------------
Matlab / Simulink 2020a available at www.mathworks.com

Installation
------------
Install Matlab / Simulink

Add `NVFEL_MATLAB_Tools`, and `REVS_Common` folders AND subfolders to the Matlab path.

Quickstart
----------
From the Matlab command window, `cd` to the `ALPHA_DEMO` folder and run the `run_demos.m` script.

Console logs and results .csv files will be located in `ALPHA_DEMO/output`

Individual Simulations
----------------------
run_ALPHA_CVM_DEMO.m sets up and executes a conventional vehicle model ("CVM")

run_ALPHA_P0_DEMO.m sets up and executes a mild-hybrid ("a P0 hybrid") model

run_ALPHA_P2_DEMO.m sets up and executes a strong plug-in hybrid ("PHEV") model with a belt-driven starter-generator and a primary drive motor upstream of the transmission (a "P2 PHEV")

run_ALPHA_PS_DEMO.m sets up and executes a strong hybrid planetary power-split ("PS") model

run_ALPHA_BEV_DEMO.m sets up and executes a battery-electric vehicle ("BEV") model

The Simulation Process
----------------------
Each demo script sets up a simulation "batch" of one or more simulations by defining sets of configuration strings that define the simulation inputs.
The strings consist of keys (as in "XYZ:") followed by values.  The acceptable values depend on the key.
Numeric-value tags can accept multiple values in the form of Matlab vectors.  For example, "ETW_LBS:3750" defines the vehicle Equivalent Test Weight to be 3,750 pounds.
"ETW_LBS:[3000, 3250, 3500]" would define a set of three simulations at 3,000, 3,250 and 3,500 pounds respectively.
If multiple keys define multiple values then the full factorial of all combined values will be simulated (for example multiple test weights combined with multiple roadload coefficients, final drive ratios, etc).
This allows the simple set up of parameter sweeps and large batches with even a single configuration string.

To see the available keys enter `sim_batch.show_keys` in the Matlab Command Window. 
Not all pre-defined keys are applicable to all sim batches, for example "TC_K_factor:" which defines an automatic transmission torque converter K-factor has no effect on a simulation that has no torque converter.

Simulation Inputs
------------------
Each demonstration model has input files located in the appropriate ALPHA_DEMO/param_files folder.
Also included in the folders are image files of the engine and motor maps used by the default simulations.

Simulation Outputs
------------------
Once the demo simulation is complete, the output workspace of the first simulation is "extracted" to the top-level workspace for ease of use.
(Each sim case data structure stores its own workspace in sim_batch.sim_case(n).workspace for sim case "n" if sim_batch.retain_workspace == true).

The primary workspace ouputs are:

    result - drive cycle energy and fuel consumption results by drive cycle phase.  `result.print` will display the results in the console window.
    audit - available if sim_batch.logging_config.audit_phase is true.  `audit.print` will display the energy audit results in the console window.

    datalog - raw time-vector model outputs, grouped by simulation block with raw variable names
    model_data - selected time-vector model outputs grouped by component with user-friendly variable names

    postproc_results - performance times (as in 0-60 MPH acceleration time in seconds, etc) if a performance cycle was run, and other post-processed values

The demo scripts also run a Data Observation Report ("DOR") which creates a set of plots that help illustrate the model behavior.
DORs can be used to compare simulation outputs using a common set of plots.  Pass comparison model_data to the first argument of the DOR.
DORs will be disabled by default when running all the simulations via `run_demos.m` and enabled by default when running individual simulation batches.

Simulation output files:

    *_console.txt - console outputs file
    *.log - batch process log file
    *_results.csv - simulation results summary (MPG, CO2 g/mi etc), one row per simulation in the batch
