Setting up the program

Python

1. Install or create a new 3.5.X or higher python environment. Make sure that tkinter and pip are included in your installation.

Recommendation

Create a new environment based on your current Python version by running python -m venv <my_virtual_environment> in the folder you want to create the new environment.

2. Install the required packages for running VEMOD Plotter by running pip install -r requirements.txt. Where requirements.txt is the file located in /NewLauncher/python_plotters.

Warning

If you want to install the packages in your new python environment, you must activate this environment first by running path/to/<my_new_environment>/Scripts/activate.

After that, the next line in the console should be (<my_new_environment>) current/path

Then, you are able to install the packages by running pip install -r requirements.txt

3. Check the console for any possible installation error. To check your installed packages run pip list.

Configuration XML file

Create a configuration XML file needed for running VEMOD Plotter. The contents of this file are explained in the next paragraph.

The configuration file

The configuration file is an XML file required for VEMOD Plotter for processing simulation and experiment data. An example of configuration file is presented below:

<?xml version="1.0" encoding="UTF-8" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="config.xsd">
    <engine pistonDiameter="0.08002" crankRadius="0.0398" fuelPCI="42.92" totalDisplacement="0.0016"
        cylinders="4" injectionPulses="3"/>
    <plotStyles lineStyleExp="-" lineStyleModel=":" lineWidthExp="1.5" lineWidthModel="1.5"
        colorExp="#E24A33" colorModel="#348ABD" labelExp="Reference" labelModel="VEMOD" style="ggplot"
        fontSize="14" fontFamily="sans-serif" font="DejaVu Sans" />
    <plottingOptions>
        <emissions plot="false" location="Pipe/Exhaust/0.010m" />
        <trends plot="true" />
        <timeEvolution plot="true" steadyVariablesFile="Steady_model_vars.dat"
            transientVariablesFile="Transient_model_vars.dat" />
    </plottingOptions>
    <experimentalProcessing>
        <inputFile category="calmecAverages">
            path/of/steady-state/Resglob.dat
        </inputFile>
        <inputFile category="experimentalRaw">
            path/of/steady-state/TodasCombustiones.xlsx
        </inputFile>
        <outputFile>
            ../INPUT_dataset/medidas_SS/ExperimentalData.xlsx
        </outputFile>
    </experimentalProcessing>
    <simulationProcessing>
        <settings roomTempConditions="ambient" modelNamePrefix="R9M_lab12_" xmlCase="Default"
            simulationMode="testbench" simulationPath="../User_VEMOD_Model/simulation/results"
            processingPath="" />
        <transient experimentalPath="../INPUT_dataset/medidas_WLTC" 
            variablesFile="Variables_transient.dat" simTime="1800">
            <divisions>
                <division name="Low" start="0.0" end="589" />
                <division name="Medium" start="589" end="1022" />
                <division name="High" start="1022" end="1477" />
                <division name="Extra High" start="1477" end="1800" />
            </divisions>
            <errorEvaluation>
                <error pointsPercentage="50" />
                <error pointsPercentage="70" />
                <error pointsPercentage="80" />
                <error pointsPercentage="90" />
                <error pointsPercentage="95" />
            </errorEvaluation>
        </transient>
        <steady averagingPercentage="3" variablesAverageFile="Variables_avg.dat"
            experimentalFile="../INPUT_dataset/medidas_SS/ExperimentalData.xlsx" 
            variablesInstantaneousFile="Variables_ins.dat" 
            calmecInstantaneousPath="path/of/steady-state/Instantaneous" >
            <cases>
                <case name="1500_011_h_1">
                    <nomenclature>
                        <labelPart property="speed"/>
                        <labelPart property="load"/>
                        <labelPart property="roomTemperature"/>
                        <labelPart property="repetition"/>
                    </nomenclature>
                </case>
                <case name="1500_025_h_2">
                    <nomenclature>
                        <labelPart property="speed"/>
                        <labelPart property="load"/>
                        <labelPart property="roomTemperature"/>
                        <labelPart property="repetition"/>
                    </nomenclature>
                </case>
                <case name="1500_050_h_3">
                    <nomenclature>
                        <labelPart property="speed"/>
                        <labelPart property="load"/>
                        <labelPart property="roomTemperature"/>
                        <labelPart property="repetition"/>
                    </nomenclature>
                </case>
                <case name="1500_075_h_2">
                    <nomenclature>
                        <labelPart property="speed"/>
                        <labelPart property="load"/>
                        <labelPart property="roomTemperature"/>
                        <labelPart property="repetition"/>
                    </nomenclature>
                </case>
                <case name="1500_100_h_1">
                    <nomenclature>
                        <labelPart property="speed"/>
                        <labelPart property="load"/>
                        <labelPart property="roomTemperature"/>
                        <labelPart property="repetition"/>
                    </nomenclature>
                </case>
            </cases>
        </steady>
    </simulationProcessing>
</config>
            

An XML scheme is provided in /NewLauncher/python_plotters/config.xsd. This scheme is useful to check the structure of the configuration file and look for errors if you are using an advanced editor.

The nodes that make up the configuration file are the following:

Engine

Includes some engine parameters.

Attribute	Type	Units	Use
pistonDiameter	float	m	required
crankRadius	float	m	required
totalDisplacement	float	m3	required
cylinders	unsignedByte	-	required
injectionPulses	unsignedByte	-	required
fuelPCI	float	MJ/kg	required

Plot styles

Includes some graphic parameters and Matplotlib styles.

Attribute	Type	Use
lineStyleExp	string	optional
lineStyleModel	string	optional
lineWidthExp	float	optional
lineWidthModel	float	optional
colorExp	string 1	optional
colorModel	string 1	optional
labelExp	string	optional
labelModel	string	optional
style	string 2	optional
fontSize	unsignedByte	optional
fontFamily	string 3	optional
font	string 3	optional

1. Colors can be specified as their name, hex or decimal code. See how to specify colors in Matplotlib for more information.

2. The Matplotlib styles available are restricted to this styles list.

3. The font has to be available in your computer. Read how to configure the font family for more information.

Plotting options

Here the user decides to include some graphs in the processing or not.

Emissions

If the plot attribute is set to true, pollutant emissions figures (mass flow and accumulated mass if it is a transient simulation) will be plotted. In this case, an engine location, where the pollutant emissions are measured and available in the simulation results, has to be provided in the location attribute.

Attribute	Type	Use
plot	boolean	required
location	string	required

Trends

If the plot attribute is set to true, trends figures (model values vs experimental values) will be plotted.

Attribute	Type	Use
plot	boolean	required

Time evolution

If the plot attribute is set to true, model variables will be plotted along the simulation time. In this case, a table file should be provided ⁴.

Attribute	Type	Use
plot	boolean	required
steadyVariablesFile	string	optional (used just in steady-state)
transientVariablesFile	string	optional (used just in transient)

4. The table file with the model variables must have the following columns:

Column	Description	Type
Print	yes or no if you want to plot the variable or not.	string
Name	The name of the variable as shown in the graphs.	string
Mod_column	The variable column in the simulation results. Different rows with the same variable name can be added with different model columns. This way, several plots will appear in the same graph.	string
Legend	The variable legend for each Mod_column.	string
Units	The variable physical units.	string
Conv_factor	The conversion factor between the model column units and the selected units in the Units column.	float

The recommended separator for values is the tab and the recommended file extension is .dat

Experimental processing (steady-state only)

This node consists of three elements required for running the program in experimental mode .

Element	Description	Type	Use
inputFile	There are two input data files defined by the required attribute category (which only can be calmecAverages or experimentalRaw). calmecAverages contains the CALMEC processed values for each steady-state case, whilst experimentalRaw contains the test bench acquired data for the same steady-state cases.	string	required
outputFile	Is the name of the resulting reference data file when running the program in experimental mode. This file is required later to plot steady-state graphs.	string	required

Simulation processing

This is the most important node of the configuration file. It consists of one general node called settings and two other nodes referring the processing mode (transient or steady-state).

Settings

The attributes of this element help the user to find and specify the simulation files.

Attribute	Description	Type	Use	Restrictions
roomTempConditions	The room temperature conditions of the test bench in order to compare with experimental data.	string	optional	warm, cold or ambient
modelNamePrefix	The beggining of the simulation results file names.	string	required	-
xmlCase	The name of the simulated case. It can be found in the Cases node of the model XML file.	string	required	-
simulationMode	The simulation mode used if the simulation was run using the Matlab VEMOD Launcher.	string	optional	testbench, N-T, N-mf, vehicle
simulationPath	The path where the simulation results are stored.	string	optional	-
processingPath	The path where the processed graphs are saved. If this attribute is missing, the graphs will be stored in the path where VEMOD Plotter is located.	string	optional	-

Transient

The attributes of this element define the processing of the transient simulations.

Attribute	Description	Type	Use
experimentalPath	The path where the transient test bench data files are located.	string	required
variablesFile	The table file where the variables to be plotted are listed with their corresponding column names for model and experiment 5.	string	required
simTime	The simulation time (in seconds) of the transient profile.	unsignedInt	optional
sectionStart	The starting time (in seconds) of the transient cycle section to be plotted.	float	optional
sectionEnd	The ending time (in seconds) of the transient cycle section to be plotted.	float	optional
filterModel	Decides whether to filter or not the model values. Default is true.	boolean	optional

5. The table file with the listed variables must have the following columns:

Column	Description	Type
Print	yes or no if you want to plot the variable or not.	string
Name	The name of the variable as shown in the graphs.	string
Ref_column	The variable column in the experiment results. Some variables require a sequence of columns separated by commas to reduce hard-coding during the processing.	string
Mod_column	The variable column in the simulation results. Some variables require a sequence of columns separated by commas to reduce hard-coding during the processing.	string
Units	The variable physical units.	string
ModToRef_factor	The conversion factor between the model column units and the selected units in the Units column, which should match the units of the experimentally measured variable.	float
Ymin	The lower limit in the Y axis when plotting the variable. Set it to NA if you do not want to apply limits.	float
Ymax	The upper limit in the Y axis when plotting the variable. Set it to NA if you do not want to apply limits.	float
Tau	The delay (in engine cycles) when plotting the model signal of the variable. Acts as a rolling average. This is useful to drastically reduce noise of the model signal, which has a greater resolution compared with the experimental signal, e.g., when comparing temperatures measured by a thermocouple. Set it to 0 to keep the original model signal.	float

The recommended separator for values is the tab and the recommended file extension is .dat

Divisions

It is possible to divide the transient profile in small divisions. These divisions are visible in the graphs and their are names printed under the X axis. Besides, statistical data regarding this divisions are saved in the transient summary file. Divisions have to be created in the divisions child of the transient element.

<divisions>
    <division name="Low" start="0.0" end="589" />
    <division name="Medium" start="589" end="1022" />
    <division name="High" start="1022" end="1477" />
    <division name="Extra High" start="1477" end="1800" />
</divisions>
                

Attribute	Description	Type	Use
name	The name of the division	string	required
start	The instant when the division starts (in seconds)	float	required
end	The instant when the division ends (in seconds)	float	required

Error evaluation

It is possible to evaluate the absolute and relative error of a percentage of the total points along the transient profile. The errors for all the points along the transient are sorted in ascending order. After that, the values corresponding to the percentages of the points are saved in the transient summary file. These percentages have to be defined in the errorEvaluation child of the transient element.

<errorEvaluation>
    <error pointsPercentage="50" />
    <error pointsPercentage="70" />
    <error pointsPercentage="80" />
    <error pointsPercentage="90" />
    <error pointsPercentage="95" />
</errorEvaluation>
                

Attribute	Description	Type	Use
pointsPercentage	The percentage of points with respect to the total to be evaluated.	float	required

Steady

The attributes of this element define the processing of the steady-state simulations.

Attribute	Description	Type	Use
averagingPercentage	The last percentage of values to be considered for each variable. If the simulation time is quite enough to stabilize the mean values, it is faster and more accurate to take the last values for averaging. Default value is 3 %.	unsignedByte	optional
experimentalFile	The Excel file where the reference values are stored. This file is created by running the program in experimental mode.	string	required
variablesAverageFile	The table file where the variables to be plotted are listed with their corresponding column names for model and experiment 6. Only used in steady-avg mode.	string	required
variablesInstantaneousFile	The table file where the variables to be plotted are listed with their corresponding column names for model and experiment 7. Only used in steady-ins mode.	string	required
calmecInstantaneousPath	The path where the CALMEC processed files for each steady-state case and cylinder are stored. Only used in steady-ins mode.	string	required

6. The table file with the listed average variables must have the following columns:

Column	Description	Type
Print	yes or no if you want to plot the variable or not.	string
Name	The name of the variable as shown in the graphs.	string
Ref_column	The variable column in the experiment results.	string
Mod_column	The variable column in the simulation results.	string
Units	The variable physical units.	string
ModToRef_factor	The conversion factor between the model column units and the selected units in the Units column, which should match the units of the experimentally measured variable.	float
Ymin	The lower limit in the Y axis when plotting the variable. Set it to NA if you do not want to apply limits.	float
Ymax	The upper limit in the Y axis when plotting the variable. Set it to NA if you do not want to apply limits.	float

7. The table file with the listed cylinder variables must have the following columns:

Column	Description	Type
Print	yes or no if you want to plot the variable or not.	string
Name	The name of the variable as shown in the graphs.	string
Ref_column	The variable column in the experiment results.	string
Mod_column	The variable column in the simulation results.	string
Units	The variable physical units.	string
K_mod	The conversion factor between the model column units and the selected units in the Units column.	float
K_exp	The conversion factor between the reference column units and the selected units in the Units column.	float
Xmin	The lower limit in the X axis when plotting the variable. Set it to ≈-120 to center the combustion phase.	float
Xmax	The upper limit in the X axis when plotting the variable. Set it to ≈120 to center the combustion phase.	float

The recommended separator for values is the tab and the recommended file extension is .dat for both files.

Cases

The program needs to know which steady-state cases are going to be processed. This cases are identified by an unique name or ID that must match the ones in the experimentalFile, which are the same test names that appear in the processed CALMEC files. This cases have to be defined in the cases child of the steady element.

<cases>
    <case name="1000_021_h_2">
        <nomenclature>
            <labelPart property="speed"/>
            <labelPart property="load"/>
            <labelPart property="roomTemperature"/>
            <labelPart property="repetition"/>
        </nomenclature>
    </case>
    ...
</cases>
                

Test names are typically defined by a sequence of values separated by underscores. In the example above each labelPart defines one of these values:

 1000 _  021 _        h        _     2     

speed _ load _ roomTemperature _ repetition

Attribute	Description	Type	Use	Restrictions
property	The property that represents that part of the test name between underscores.	string	required	speed, load, torque, roomTemperature, repetition, date, BMEP, EGR or undefined.

More property types can be added in the scheme. If you are not sure about which property represents each labelPart, use undefined as a wildcard.

Running the program

VEMOD Plotter can be executed in four modes: experimental, steady-avg, steady-ins and transient, and accept different command line arguments.

Experimental mode

This mode just processes experimental data and is related to the experimentalProcessing node of the configuration file. Once you run VEMOD Plotter in this mode, an Excel file is created joining all the experimental data for the selected steady-state tests.

Execute the program in this mode by running:

python plotter.py <my_configuration_file.xml> experimental [optional arguments]

Steady-avg mode

This mode generates different graphs based on the variables' mean values and is related to the steady node of the configuration file.

Execute the program in this mode by running:

python plotter.py <my_configuration_file.xml> steady-avg [optional arguments]

Steady-ins mode

This mode generates different graphs based on the cylinder variables' instantaneous values and is related to the steady node of the configuration file.

Execute the program in this mode by running:

python plotter.py <my_configuration_file.xml> steady-ins [optional arguments]

Transient mode

This mode generates different graphs based on the mean values of the variables along the transient cycle and is related to the transient node of the configuration file.

Execute the program in this mode by running:

python plotter.py <my_configuration_file.xml> transient [optional arguments]

Optional arguments

Argument	Description
-h, --help	Displays a help message in the console.
-V, --version	Shows VEMOD Plotter current version.
-v, --verbosity	Shows runtime detailed information when running the program. -v shows detailed information, while -vv shows debug level information.
--nomultiprocesing	This option disables the multiprocessing feature when loading simulation data and creating graphs. All the tasks are carried out by a single python process, thus increasing the processing time.

Figures and summaries

Running VEMOD Plotter in any mode except experimental one, a folder is created in the processingPath. This folder is named as <date>_<room_temperature_conditions>_<mode>_<simulation_mode>, e.g., 2020-Jan-08_ambient_transient_testbench. If none of the previous attributes are available in the configuration file, the folder is named according to the processing date.

Each mode creates different sub-folders in the mentioned folder:

Steady-avg

/<processing_folder>

    |- <xmlCase>

        |- /cycles (Stores the simulation average result files)

        |- /img (Stores the generated bar graphs)

        |- /mat (Stores the simulation Matlab files)

        |- /structs_for_Matlab

(Stores the generated Matlab datasets, only if 'simulationMode' is 'testbench')

        |- /time_evolution

(Stores the generated variable vs time graphs, only if 'timeEvolution plot' is true)

        |- /trends

(Stores the generated model vs experiment graphs, only if 'trends plot' is true)

        |- /xml (Stores the model XML files)

        |- IVC_data.xlsx (Intake Valve Closing conditions for each steady-state case)

        |- summary_averages.xlsx (Statistical summary for each steady-state case)

Steady-ins

/<processing_folder>

    |- <xmlCase>

        |- /img_ins (Stores the generated line graphs)

        |- /mat (Stores the simulation Matlab files)

        |- /plots

(Stores the simulation instantaneous result files of each -or last- engine cycle)

        |- /xml (Stores the model XML files)

        |- summary_cyl_ins.xlsx (Statistical summary for each steady-state case)

Transient

/<processing_folder>

    |- <xmlCase>

        |- /cycles (Stores the simulation average result files along the transient cycle)

        |- /img (Stores the generated line graphs)

        |- /mat (Stores the simulation Matlab files)

        |- /plots

(Stores the simulation instantaneous result files of each -or last- engine cycle)

        |- /trends

(Stores the generated model vs experiment graphs, only if 'trends plot' is true)

        |- /xml (Stores the model XML files)

        |- summary_transient.xlsx (Statistical summary)

        |- transient_for_N-mf_mode_<roomTemperature>.xlsx

(Launcher transient input file for N-mf mode, only if 'simulationMode' is 'testbench')

        |- transient_for_N-T_mode_<roomTemperature>.xlsx

(Launcher transient input file for N-T mode, only if 'simulationMode' is 'testbench')

Structure

This section covers how variable data is managed within the program. The data structure strongly depends on the processing mode. The following charts explain the structure for each mode:

Steady-avg

For example, to access model values it would be like this:

                        variable.values['<steady-state_test_name>']['model']
                    

Steady-ins

For example, to access model Y values it would be like this:

                        variable.values['<steady-state_test_name>']['model']['y']
                    

Transient

For example, to access model Y values it would be like this:

                        variable.values['model']['y']
                    

Maintenance

Several actions can be taken to increase the program versatility easily. A few of them are explained below:

Increase available properties for test names

More property types can be added to identify the parts of a test name. To do this, add them to the restrictions in the config.xsd scheme file.

You can also manage how they are going to be displayed in the graphs by modifying the get_case_labels function in the /resources/plotting_functions.py file.

Add or replace the room temperature identifiers

Currently there are three options: warm, cold or ambient. You can add new ones by adding them to the restrictions in the config.xsd scheme file.

Warm and cold conditions are identified in test names by an h and a c, respectively. You can edit this by modifying the room_cond_dict dictionary at the beginning of the plotter.py file.

Add or replace the transient experimental files

You can add new transient experimental files or replace the existing ones. To make sure that the program is reading the proper files, edit the experimental_transient dictionary at the beginning of the plotter.py file.

Note

Every time a transient experimental file is modified in the ../INPUT_dataset/medidas_WLTC folder, next time the program is executed, it is aware of the modification and creates a new binary version of the Excel file for a faster loading in the future.

Add or replace graph colors and markers

You can add or replace the current sequence of markers and colours by modifying the markers and colors tuples at the beginning of the /resources/plotting_functions.py file. Visit Matplotlib markers and Matplotlib colors for more information.

Changelog

2.2.1

• Fixed a bug introduced in last version that prevented plotting transient results.
• Do not stop the program execution if pollutants mass flow location is wrong.
• Added intake/exhaust manifolds pressure difference variable.

2.2.0

• Added the feature of graphing the cylinder pressure throughout the whole engine cycle in instantaneous cylinder variables.

2.1.0

• Added the feature of graphing a section of the entire transient cycle.
• Added the option for not filtering model signals.
• Autodetection of the separation character in calmec files.
• Improved the way in which model variables are read.
• Added new model variables.

2.0.1

• Changes in error columns in transient summary.
• Changes in steady-state trend plots' legend.
• Model columns in turbocharger graphs are read from variables file.

2.0.0

• New project structure: one main script for processing all the simulations. Auxiliary functions and classes separated from main script.
• Simulation data loading and graphs creation processes are done in parallel multiprocessing.
• Resulting graphs now can be stored at any folder. Not necessarily in the local repository.
• Different verbosity levels: info and debug.
• Improved summary files with more information and better structured.
• Full documentation available for functions and files.
• Configuration file moved to XML format with more parameters and greater independence of the engine type. It also includes an XML checker that look for problems in the configuration file.
• Better file sorting method.
• Better identification of steady-state test names.
• Transient tests can be evaluated by sections.
• Homogenization of variable input files.

Contact

Contact ngeaugar@mot.upv.es for any questions not resolved in this guide.