Training 

Part 2A 
‐ Organization –
Software 
Software

Sponsored by Lee Slezak

“This presentation does not contain any proprietary or confidential information”
Outline

 Folder Organization
g
 Units
 g
Parameter Naming Nomenclature
 Structure

2
Core Software Directories

GUI files, including aStart.exe

Project files defined by users
Files used to define what type of 
p
simulation should be performed

Folder containing all the models and 
Folder containing all the models and
files used to define the different 
systems

F ld
Folder specific to each user
ifi t h

3
User Folder
This folder contains one folder per user name to be used as a working directory

 This folder is first in the Matlab path, so 
versions of files in your user folder will 
override other files
 Run files (.a_run) that define a simulation 
run are written here
 Results from a simulation are under the 
save_simu directory 
– This directory will be covered under the “Analyze 
Results” portion of the training

4
GUI Directory
Matlab
M tl b files, including code 
fil i l di d
related to legacy model 
integration

Picture / icons used in the GUI

Predefined plot functions for each 
component

Compiled Graphical User Interface

5
Simulation Setup Directory

Folder contains files used to define what type of simulation should be 
performed
Files used for both process 
Fil d f b th
and operator

An operator is defined as an 
option of a process that 
cannot be performed on its 
own

A process represents what the 
p
user wants to perform

6
Simulation Setup Directory

Files used to build the model 
from a blank Simulink page

Files used to calculate 
g
generic parameters such as 
p
energy, efficiencies…

Files used to save the results 
from the simulation

7
Simulation Setup Directory

Performance test
Only build model (for development)
CarSim process
Coastdown test
User defined processes 

Fuel consumption test
Gradeability test
Generate lookup table from GTPower
Generate lookup table from GTPower
Test single component
Standard test procedures
SIL model buildingg
Steady‐state test

8
Simulation Setup Directory

Debug Model

Monte Carlo Uncertainties
l
Run optimization algorithms

Run parametric study
Load specific reports
SSize vehicle components
e e c e co po e ts
Run SOC correction for HEVs

9
Systems Directory
Thi i h
This is the main folder containing all the files to define a vehicle in Autonomie
i f ld i i ll h fil d fi hi l i A i

 Like the architecture folder, files go in the 
directory tree where they would go in the 
vehicle
– For example, a model that represents a battery 
plant would be stored under 
systems ‐> veh ‐>  vpa ‐> ess ‐> plant ‐> <Model name>
 Each system is composed of 
Each system is composed of
– A folder describing the architecture options (e.g., 
number of components, their linkage…)
– A list of folders where each component is further 
described

10
Systems Directory
Each system, at any level, has the 
Each system at any level has the
same information: architecture, 
systems and model directories

List of number of models options and 
their linkages

Each model available from an 
architecture has its own directory

List of saved systems (e.g., driver for 
conventional vehicle with manual 
transmission) and templates. A 
template is a system without
template is a system without 
initialization or scaling file

11
Systems Directory – Engine Example

 As described previously, the models that can be 
selected for the different architectures each 
have their own directories Under the plant:
have their own directories. Under the plant:
– Eng_plant_hot_map can be selected to model 
the engine under a single mdl
– Charging, cooling, cylinder, egr… should each be 
selected is the user selects an architecture that 
model the engine based on different files, so that 
each of them can be selected with different level 
of fidelity
 Under each folder containing mdl files, the 
following folders can be found:
– Init ‐> initialization files
– Postproc ‐> specific post processing (e.g., power 
> specific post processing (e g power
calculations)
– Preproc ‐> pre‐processing (e.g., engine best efficiency 
curve)
– Scale ‐>> scaling files
Scale  scaling files

12
Systems Directory
There are different types of files that can be associated with a system, and each one 
Th diff f fil h b i d ih d h
has a metadata file associated with it

1
1. Model Files ‐ .mdl and .a_model
Model Files  mdl and a model
– Simulink that defines that system
2. Initialization Files ‐ .m and .a_init
– File to initialize the parameters of the model
File to initialize the parameters of the model
3. Scaling Files ‐ .m and .a_scale
– File to automatically scale the model
4
4. Pre‐processing Files ‐ .m and .a_preproc
Pre‐processing Files ‐ m and a preproc
– Calculations that must be performed before a model can be run
5. Post‐processing Files ‐ .m and .a_postproc
– Calculations to perform after a model is run
Calculations to perform after a model is run

 Model and Initialization files are required for all lowest‐level systems.
 Scaling, Pre‐proc and Post‐proc files are not required at any level, but may 
g p p q y y
be included at any level.

13
Systems Directory - Examples

VPA contains subsystem directories

VPA contains processing files, even though it doesn’t 
y
directly have a model

Init files specific to the model 
ess_plant_generic_map are under that model’s 
folder

Init files that are generic across multiple 
models are directly under the system directory

14
Systems Directory - Vehicles
Th
The vehicle directory contains vehicle files (.a_vehicle) stored by vehicle type
hi l di i hi l fil ( hi l ) db hi l

 Once a vehicle is completed in the GUI, it 
can be saved here for re‐use
 A vehicle file fully defines all of the systems 
in a vehicle including all selected 
configurations, models, init files, 
parameter values, etc.

15
Outline

 Folder Organization
g
 Units
 g
Parameter Naming Nomenclature
 Structure

16
SI Units Recommended for All Models

Value Units
Torque Nm
Rotational Speed Rad/s
Force N
Linear Speed m/s
Current Amps
Voltage Volt
Power Watt
Energy Joule
Rotational Acceleration Rad/s2
Linear Acceleration m/s2
Weight Kg

17
Outline

 Folder Organization
g
 Units
 g
Parameter Naming Nomenclature
 Structure

18
Name Nomenclature - Component Models

 Based on four parts:
 Type of component (e.g.: eng = engine
Type of component (e.g.: eng = engine))
 Type of model (e.g.: ctrl = control)
 Type of data (e.g.: 
Type of data (e.g.: trq
trq = torque)
 Complement of information (e.g.: max = maximum)
Complement of information (e g : max = maximum)
 All the model parameters and variables are composed using 
these parts
p

19
Name Nomenclature - Type Of Component

vpa= vehicle 
vpa = vehicle powertrain
powertrain architecture fc = fuel cell
vpc=vehicle 
vpc=vehicle powertrain
powertrain controller fd = final drive
accelec = electrical acc gc = generator
accmech = mechanical acc mc = motor 
cpl
p = clutch / torque conv.
/ q sft = shiftingg
cyc = cycle tc = torque coupling
drv = driver
= driver gb = gearbox
= gearbox
ess = energy storage chas = chassis
eng = engine
eng  = engine wh = wheel…

20
Name Nomenclature - Type Of Data

trq = torque mass = mass

spd = rotational speed soc = state‐‐of‐
soc = state of‐charge
linear_spd = linear speed temp = temperature
temp = temperature
curr = current tau = time constant 
volt = voltage
g voc = open circuit voltage
p g
pwr = power cmd = command…
energy
energy = energy
= energy
inertia = inertia

21
Name Nomenclature – Complement of Information

chg = charge map = map 
map = map 
dis = discharge loss = loss
accel = acceleration in = input
decel = deceleration out = output
dnshift = downshift drag = drag
g g
upshift = 
= upshift
upshift aero = aerodynamic
min
min = minimum
= minimum dmd = demand
= demand
max = maximum trs = transient
avg = average
= average cstr = constraint…

22
Outline

 Folder Organization
g
 Units
 g
Parameter Naming Nomenclature
 Structure

23
Core Structure

The core structure provides the high level information about the 
simulation (e.g., date, time, units…)

High level information

List of units chosen by the user

Type of study (simulation/testing)

24
Core Structure

The global field provides information about the user name, date, time…

25
Core Structure

 The unit field provides information the 
selected default units from the user. 
 These
These units will be used to (1) 
units will be used to (1)
overwrite values in the GUI and (2) 
view the results. 
 It is important to note that the user 
can use any units in his model and (2) 
all units in the post‐processing are 
saved in SI
saved in SI.

26
Simulation Structure

The simulation structure describes the type of process used (e.g., fuel 
economy, performance…) along with the model assumptions

27
Simulation Structure

The system field list the configurations used at each level along with the 
names of the files used (e.g., initialization, calculation…)…

28
Simulation Structure

29
Component Structure

Each component has its own structure describing the model assumptions 
(values)  as well as the results

30
Component Structure

Example of component results for the engine

31