2.1 Using the GUI (demo)

2.2 Converting old component files to the current version of ADVISOR

2.3 Running ADVISOR without the GUI
2.4 Helper Classes and Functions
* * * * *

This section should get you started using ADVISOR both by using the GUI and by entering simple commands at the Matlab command line.

2.1 Using the GUI

The ADVISOR GUI can be started using one of the two following methods.

Method 1

• Start MATLAB 5.3 (or higher) and using the ‘path browser’, remove any previous ADVISOR paths.  Then change the current (active) directory to be the top-level ADVISOR directory (the folder containing the extracted files).
• To run ADVISOR, type “advisor” at the command prompt in MATLAB.  This will update the MATLAB path for the current MATLAB session and start running ADVISOR.  If the directories needed for ADVISOR have not been saved to the path for future sessions, a window will popup and ask if you want to save the path for future sessions.  It may be necessary to save the path for other programs to have access to ADVISOR.

NOTE: MATLAB runs files from the current working directory first, then the directories in the path from top to bottom.  This may cause problems if you have two files named the same thing in different directories.  Therefore, make sure you delete the paths for the older versions of ADVISOR.
 

Method 2  Creating ADVISOR shortcut icon to launch ADVISOR and  MATLAB

• In the GUI directory, find the ADVISOR shortcut icon to launch ADVISOR and MATLAB.
• Right click on the file and choose ‘properties’.
• Click on the shortcut tab.
• Do a search for the MATLAB executable file.  Under ‘Target’ modify it to point to your MATLAB.EXE file, followed by -r advisor.
• Under ‘Start in’ enter in the main ADVISOR directory.
• Hit the ‘change icon’ button, then hit browse and find the ADVISOR.bmp file, not the shortcut file, in the GUI directory.
• Enter Ok, and double-click on the icon to launch ADVISOR.

The first figure is the startup figure. Here you will have the options to select US or metric units, start using ADVISOR, click helpto go to a local ADVISOR web page, exit ADVISOR or read the copyright and disclaimer.  

MENU PROFILES:  From the startup figure you can also select a menu profile from the pull down menu above the start button.  This profile list contains the names of *.mat files that define what will be listed in the component menus in the input figure and what cycles are listed in the simulation setup figure.  Editing the profile is simply done by having the profile that you want to edit selected and going through each ADVISOR figure and deleting or adding to the component lists using the pushbuttons next to the components.  You may also add, delete or create new profiles by selecting ‘edit list’ from the pull down menu on the startup figure.  See also custom menus.

NOTE: Throughout the GUI there are help buttons which will either access the Matlab help window or open a web page with appropriate context information.

2.1.1 Defining a vehicle

Starttakes you to the input figure. The input figure opens and you will see the default values for a specific vehicle.

Drivetrain selection
From the drivetrain popup menu you will be able to select the drivetrain configuration of the vehicle (Series, Parallel, etc.) which will cause the schematic of the vehicle configuration in the left portion of the figure to change accordingly. This will also modify which components are available for the type of drivetrain chosen.

Selecting components
After selecting the drivetrain configuration, all the components of the vehicle can be selected using the popup menus, or by clicking on the component in the picture. To the left of the component popup menus is a pushbutton that will allow you to add or delete components by selecting their corresponding listed m-files. The m-file of a specific component can be accessed for viewing or modifying from either the component pushbutton or by clicking on the component of the picture.

Editing Variables
After selecting all the desired components for the vehicle, scalar input variables can be modified.  One way this can be done is with the variable list at the bottom of the figure and the Edit Var. button. First select the variable to change and then click the edit button to change its value. The default value is always shown for your reference.  The View All button allows you to see all of the variables you have altered.  You can click on the help button to see a brief description and the units used for the input variables.

A second way in which you can edit variables is by typing in a desired value in the edit boxes next to the component.  For example, adjusting the maximum power of a fuel converter adjusts the variable fc_trq_scale, or increasing the peak efficiency increases the variable fc_eff_scale accordingly.

A final way to edit the mass of the vehicle is to use the override mass button.  The calculated mass is ignored and the value input into the box is used instead.

Loading and Saving vehicle configurations
To load or save a particular vehicle configuration click on the Load Vehicle button on the top of the figure or click on Save at the bottom of the figure. The file will be saved in the format ’filename_in.m’. A saved vehicle can be accessed by pushing the load button.

Viewing component information
At the bottom left portion of the figure there is a popup menu and axes with the ability to view information on components such as their efficiency maps, emissions maps, fuel use maps, etc. These are plotted along with their maximum torque envelopes where appropriate.

Any component m-file can be viewed by clicking the component buttons.

Auto-Size
The auto-size button takes the selected vehicle and adjusts vehicle parameters until it meets acceleration and gradeability goals.  The parameters it alters are the fuel converter torque scale (fc_trq_scale), the motor controller torque scale (mc_trq_scale), the number of energy storage system modules, and the vehicle mass.  The minimum torque scale is set so that its peak power output is 45 kW.  The number of battery modules is limited to yield a maximum nominal voltage of 480 V.  The default performance targets are maintaining at least a 6% grade at 55 mph, and obtaining less than a 12 second 0-60 mph time, 23.4 second 0-85 mph time, and 5.3 second 40-60 mph time.

Back and Continue Buttons
The Back button will take you to the opening screen, losing all unsaved information, and the Continue button will take you to the simulation setup figure.

2.1.2 Running a simulation

The simulation setup figure gives you several options on how to test the currently defined vehicle.

Drive Cycle selection
If the drive cycle radio button is selected you can use the pull down menu to select from a list of available driving cycles. You can then select how many times you want the cycle repeated as well as if you want SOC correction.  Initial conditions can also be set from here. The filtering allows you to smooth out the selected drive cycle.

Trip Builder

A cycle can be created by combining many different cycles back to back using this functionality.  This new cycle is then saved in the normal cycle  format and can be run as such.

Auxiliary Loads
Selecting this button brings up a graphical interface to select different auiliary loads and their on/off times as related to the drive cycle.

SOC Correct
There are two SOC correct options: linear and zero delta.  The Linear SOC correction routine runs two simulations—one that gives a positive change in the state of charge and one that gives a negative change in SOC.  The corrected value of the variables of interest (e.g. miles per gallon and emissions) are then interpolated from the zero change in SOC from a linear fit to the two data points.  The Zero-Delta correction routine adjusts the initial SOC until the simulation run yields a zero change in SOC +/- a 0.5% tolerance band.

Constant Road Grade
By selecting the checkbox you can run the drive cycle using a constant road grade in place of the drive cycle’s elevation profile.

Interactive Simulation
Selecting the Interactive Simulation checkbox causes a real-time interactive simulation interface to activate while the simulation is running.

Multiple Cycles

You can speed up the process of running many different cycles with the same initial conditions using this functionality.    Multiple Cycles saves the setup information including initial conditions and then runs each of the cycles selected and saves the results.  From the results figure you can access all the different results with the aid of a  results list.

Test Procedure
If the test procedure radio button is selected you can use the pull down menu to select what kind of test to run.

Acceleration Test
By selecting this checkbox, an acceleration test will be run in addition to the chose cycle.  Acceleration times, maximum accelerations, and distanced traveled in 5 seconds will be displayed in the results figure.  This test will be run in addition to the chosen cycle.  To see the second by second output of an acceleration test, choose the CYC_ACCEL from the cycle menu.

Gradeability Test
If the gradeability checkbox is selected, a gradeability test will be run in addition to the chosen cycle.  The grade displayed in the results figure will be the maximum grade maintainable at the input mph.

Parametric Study
To see the effect that up to three variables have on the vehicle, select a parametric study.  The low and high values may be set, as well as the number of points desired for that variable.  A parametric study runs a set of simulations to cover the matrix of input points, such that if 3 variables are selected with 3 points each, 27 simulations will run.

Load Sim Setup
A previously saved simulation setup can be reloaded using the Load Sim. Setuppush button.  See Save below.

Optimize cs vars
The Optimize cs vars push button opens the control strategy optimization setup window.  Checking the radio boxes selects the design variables used to optimize for the chosen objectives and constraints below.

Save
Saves the simulation setup.

Run
To run the simulation click Run and wait for the results figure to popup.

2.1.3 Looking at outputs

Results Figure
The results figure presents some summary results (fuel economy, emissions, total distance, etc.) and allows the user to plot up to four time series plots by selecting a variable from the popup menu.  If the acceleration and gradeability checkboxes were picked in the simulation setup screen, appropriate results will also be displayed.

By clicking the Energy Use Figure button, a new figure is opened showing how energy was used and transferred for the vehicle during the simulation.  The Output Check Plots button pulls up plots that show the vehicle’s performance, some of which are not available under the time series plots.  The Replay button replays the dynamic interactive interface.  Replay is not available for Test Procedures or Multiple Cycles.

Fuel used over the simulation run  and the operation points of the fuel converter can be viewed as a function of speed and torque of the fuel converter by clicking on the ‘tools’ menu and selecting ‘FC operation’.

Parametric Results Figure
The parametric results figure plots the summary results as a function of your chosen variable(s).  For two and three variable studies, the Rotate button allows you to view the plot from all sides.  For three variable studies, you can plot any slice of the results.

Trace Miss Analysis
When a simulated vehicle deviates from the requested drive cycle, the trace_miss_analysis class (found in <ADVISOR directory>/gui/@trace_miss_analysis) is automatically called into play. The trace_miss_analysis class displays statistical information on the severity of cycle trace-miss in the “Warnings/Messages” window of the Results screen.

Information includes:

• The absolute average difference between the speed requested and speed achieved
• The percent of simulated time with trace miss greater than 2 mph (absolute)
• The greatest percent difference based on the maximum cycle speed (i.e., abs(speed_requested[time=i]-speed_achieved[time=i])/max(speed_requested)
• The greatest percent difference based upon local cycle speed (i.e., abs(speed_requested[time=i]-speed_achieved[time=i])/speed_requested[time=i]
• The greatest absolute difference

The trace_miss_analysis class is accessible for normal use (ADVISOR start-up not required). For details type: help trace_miss_analysis on the command line.

2.2  Converting old component files to the current version of ADVISOR

Updating files from older versions of ADVISOR can now(4/9/99) be done using the user interface.  First, make sure the file you want to update is on the matlab path or in the current working directory.  We suggest you place it in the ADVISOR main directory.  Second, run ADVISOR and go to the Vehicle Input figure by pressing start.  From there click on the button of the component that you would like to convert.  There is a convert button that will ask you for the file name.  Enter the file name and ok and it will update your file(same name).  If your file is not up to date and you try to add it to a component list, ADVISOR will prompt you to convert it. Details and notes on file auto-update can be found here.

2.3  Using ADVISOR without the GUI

The purpose of the ADVISOR GUI is to help guide and assist the user to use the fundamental data and models that compose ADVISOR. However, at times it is desirable to automate some of the processes in ADVISOR, especially when linking to external tools such as optimization packages. Functionality to run ADVISOR without the GUI has been provided to the user in an m-function called adv_no_gui. This is a function to be called from the Matlab Command window. It accepts 2 arguments and returns 2 arguments. To use ADVISOR without the gui you must select the save path option when you initially start ADVISOR so that Matlab will always be able to find the ADVISOR files. The function takes the following form,

[error_code,resp]=adv_no_gui(action,input)

Action is a string that defines the specific action you want ADVISOR to take. The list of available actions includes the following,
 

Input is a structure that contains the input parameters to be passed to ADVISOR while executing the specific actions. Only the data contained in the field associated with the specified action will be used any other data will be ignored. The fields of input may include,
 

After execution, the function will return to arguments. The first, error_code will be a boolean value identifying whether the action was completed successfully (error_code=0) or of there was an error during execution (error_code=1). The second, is a structure that contains the default results of the specified action.
 

Example 1: Evaluation of a single design point

1. Start Matlab. (Do not start ADVISOR.)
2. At the command line type,

input.init.saved_veh_file='Parallel_defaults_in';[a,b]=adv_no_gui('initialize',input)

This will load the default parallel hybrid configuration and initialize the workspace.

3. Now to run the grade test type the following,

input.grade.param={'speed'};input.grade.value={55};[a,b]=adv_no_gui('grade_test',input)

This will run the grade test using all defaults other than the specified speed of 55 mph. b.grade.grade will contain the maximum grade achieved.

4. Next change the mass of the mass of the vehicle to 1500 kg and reevaluating the grade performance by typing the following,

input.modify.param={'veh_mass'};input.modify.value={1500};[a,b]=adv_no_gui('modify',input)

input.grade.param={'speed'};input.grade.value={55};[a,b]=adv_no_gui('grade_test',input)

You should see a decrease in the grade performance.
 
 

Example 2: Mapping of a design space

To map out the design space of a certain configuration (i.e. similar to a parametric study), do the following;

1. Start Matlab.
2. In a new m-file called my_script.m add the following script,

input.init.saved_veh_file='Parallel_defaults_in';[a,b]=adv_no_gui('initialize',input)

% to load the default parallel hybrid configuration and initialize the workspace.

trq_range=[0.25:0.25:1.25];

for I=1:length(trq_range)

input.modify.param={'fc_trq_scale'};input.modify.value={trq_range(I)};[a,b]=adv_no_gui('modify',input)

% to modify the engine torque scale (i.e. change the peak power output of the engine)

input.procedure.param={'test.name'};input.procedure.value={'TEST_CITY_HWY'};[a,b]=adv_no_gui('test_procedure',input)

fuel(I)=b.procedure.mpgge

% to run the city hwy test procedure and obtain the default fuel and emissions performance

input.accel.param={'spds'};input.accel.value={[0 30; 50 70]};[a,b]=adv_no_gui('accel_test',input)

accel1(I)=b.accel.times(1);

accel2(I)=b.accel.times(2);

% to run the acceleration test and obtain the 0 to 30 mph and 50 to 70 mph accel times

input.resp.param={'veh_mass';'fc_trq_scale'};[a,b]=adv_no_gui('other_info',input)

mass(I)=b.other.value{1};

scale(I)=b.other.value{2};

% to obtain the resulting vehicle mass

end

figure; plot(scale,accel1,'b-',scale,accel2,'r-') % to plot accel times vs. power

xlabel('Torque Scale Factor')

ylabel('Acceleration Time (s)')

legend('0-30','50-70')

figure; plot(scale,mass) % to plot mass vs power

xlabel('Torque Scale Factor')

ylabel('Vehicle Mass (kg)')

figure; plot(scale,fuel) % to plot fuel economy vs power

xlabel('Torque Scale Factor')

ylabel('Fuel Economy (mpg)')

3. At the command line type my_script and the function should provide you with 3 plots showing the relationships to engine size. All of the raw data will be accessible in the Matlab workspace.

Example 3: Running Autosize

First, run the autosize feature from the GUI. Setup a test case the way you want adv_no_gui to run autosize. Run this case. When finished, switch to the MATLAB command window and type the following:

autosize.grade_test=vinf.grade_test;autosize.accel_test=vinf.accel_test;autosize.autosize=vinf.autosize;save fname autosize;

After this is complete, you will have made and saved a structure ready for use with adv_no_gui. Consult autosize.m and adv_no_gui.m for details on how the sub-fields *.autosize.autosize, *.autosize.grade_test, and *.autosize.accel_test are used. Next, clear the matlab workspace and start working with adv_no_gui:

clear all;input=load('fname'); % creates input.autosize.autosize, *.*.grade_test, & *.*.accel_test[a,b]=adv_no_gui('autosize',input);

The model will be automatically autosized. Results are accessible from the base workspace or via the [a,b]=adv_no_gui(’other_info’,input) command.

2.3.1 Calling ADVISOR from outside of MATLAB

An executable file has been include with ADVISOR to allow users to perform automated analysis external to ADVISOR and MATLAB.  The executable file is named advisor_script.exe and can be found in the C:\ADVISOR\gui directory.  The ADVISOR_script executable (advisor_script.exe) can be used in conjunction with adv_no_gui to automate the process of running analyses from the windows command line.

Format:

advisor_script.exe WorkingDirectory ScriptFilename ADVISORRootDirectory SupportDirectory

This command can be executed from a command window and will perform the following functions:

1) Open the MATLAB Engine
2) Update the MATLAB path to include directories necessary for ADVISOR to execute
3) Add the SupportDirectory to the top of the path
4) Update the current working directory to be WorkingDirectory
5) Run ScriptFilename at the MATLAB command prompt
6) Close the MATLAB engine when calculations are complete

ADVISOR_script does not return any results or output so the ScriptFilename must handle input and output data management with ADVISOR. The scriptfile will typically include a series of adv_no_gui calls that build the ADVISOR workspace, run the cycles or tests, and saves the results for review later. A sample script file has been included (see SampleScriptFile.m) to serve as a template for creating your own routines.

CAUTION: At this time directory names with spaces are not supported!!!

The source code for advisor_script.exe is included in advisor_script.c. 
### 2.4 Helper Classess and Functions

• Cycle Audit Class
• Engine Map Class
  

Last Revised: [04-Aug-2003]: mpo