Command Line Interface (CLI)
This document describes the functionalities of the Command Line Interface (CLI) which is a new COPERT feature integrated in the program code. The document will cover the additional capabilities of COPERT under the CLI. All previous functionalities are described in the existing COPERT manual (http://COPERT.emisia.com). The CLI does not introduce new methodological elements which are described in detail in EEA’s emission inventory guidebook (https://www.eea.europa.eu/publications/emep-eea-guidebook-2019/part-b-sectoral-guidance-chapters/1-energy/1-a-combustion/1-a-3-b-i/view). The CLI feature will, from now on, follow the development of the software (currently COPERT version 5.4), which means that it will be available to all COPERT users. Therefore, it is advised that users familiarize themselves with the COPERT software before using the CLI interface.
Introduction - main features
The purpose of this feature is to allow multiple automatic executions of COPERT, by externally providing input data and subsequently receiving results in an external file. Moreover, third party applications (like Matlab or custom software) will be able to execute COPERT via the Command Line Interface to perform automated tasks.
Calculation methodology will follow the COPERT functionalities allowing for emission factor and emission calculation as well as energy consumption calculation. Advanced features of the model can only be run by using the windows version of the tool. The following table lists the features available via the CLI and those available under Windows.
No separate installation is required; the feature is integrated in the COPERT installation.
Minimum software requirements
COPERT is a 64-bit application and requires a 64-bit Microsoft Windows operating system, Microsoft® Windows 7 or newer Windows version.
Minimum hardware requirements
- 2 GHz, 64-bit processor
- 8 GB RAM
- 30 MB for installation, 100 MB for full run
- Screen Resolution: 1024x768 pixels
Note that a higher frequency processor based computer and/or more on RAM memory are recommended if frequent use of the program is expected.
The CLI is available on any PC where the COPERT tool is installed. It is called by the Windows command line window. To open the command line window (Figure 1) click Start. In the Search or Run line, type cmd (short for command), and press Enter.
A specific syntax must be followed to start the procedure.
CLI execution syntax
The command line syntax is the following:
<COPERT.exe path1>/COPERT.exe” -i <input folder path>/<input filename with extension xlsx or json> -oEF <output folder path>/<output filename with extension xlsx or json><one space><Switch 12><one space><Switch n2>
1 Typical installation path is “C:\Program Files\COPERT 5”
1 optional, see description below
E.g.: "C:\Program Files\COPERT 5\COPERT.exe" -i "D:\COPERT_CLI\JRC COPERT CLI example.xlsx" -oEF “D:\COPERT_CLI\JRC_results.xlsx"
Input and output files can be in the same folder; however, the output files must not already exist in the specified folder, otherwise you will get an error message “Output file already exists” (Figure 3).
The program opens a separate CMD window returning control to the user in the launch window.
CLI file types
Valid input and output file types are Excel and Json files. All 4 filetype combinations for input and output files are possible.
COPERT CLI automatically converts to and from any of the two filetypes during calculation.
E.g.: "C:\Program Files\COPERT 5\COPERT.exe" -i "D:\COPERT_CLI\JRC COPERT CLI example.xlsx" -oEF "D:\COPERT_CLI\JRC_results.json"
There are two switches used by the CLI, “-keep” and “-noevap”. Both of the switches are optional, and the switch order does not influence the results. The switches should be provided at the end of the basic command (see the following examples).
Eg: "C:\Program Files\COPERT 5\COPERT.exe" -i "D:\COPERT_CLI\JRC COPERT CLI example.xlsx" -oEF "D:\COPERT_CLI\JRC_results.xlsx" -keep
When you execute COPERT via the CLI all information is temporarily stored in a COPERT file which is deleted after the completion of the calculations. If the user wishes to keep the file for further processing the “keep” switch at the end of the basic command prevents COPERT from deleting the file. The *.cop file is saved to the same folder as the output file (xlsx or json). If there is a *.cop file with the same name an error occurs, and the process is interrupted (Figure 4).
Eg: "C:\Program Files\COPERT 5\COPERT.exe" -i "D:\COPERT_CLI\JRC COPERT CLI example.xlsx" -oEF "D:\COPERT_CLI\JRC_results.xlsx" -noevap
If the user wants to perform multiple runs of the model and wishes to save up time, there is an option to omit evaporation calculations and reduce calculation time by up to 30%. However, this will have an effect on CO2 and energy consumption results, so it is best used only for the evaluation of other pollutants, like NOx, PM, CO.
Alternative country name
Eg: "C:\Program Files\COPERT 5\COPERT.exe" -i "D:\COPERT_CLI\JRC COPERT CLI example.xlsx" -oEF "D:\COPERT_CLI\JRC_results.xlsx" UK
By default, COPERT prepares a country named Greece. By providing a country abbreviation as a switch COPERT can change the country name and use the alternative. The list of country names and abbreviations are based on the Alpha-2 code of the ISO 3166 country code. The list of country codes and abbreviations can be found in the ANNEX.
The user can employ COPERT CLI to convert a file from xlsx to json and vice versa by using the following command line syntax: <COPERT.exe path>/COPERT.exe” -i <folder path>/<input filename with extension xlsx” -oC < folder path>/<output filename with extension json> -convert
Eg: "C:\Program Files\COPERT 5\COPERT.exe" -i "D:\COPERT_CLI\JRC COPERT CLI example.xlsx" -oC "D:\COPERT_CLI\ JRC COPERT CLI example.json" -convert
As previously mentioned, COPERT CLI can work with json and xlsx files. To produce an xlsx template the windows version of the software can be used. Following the creation of a COPERT run and setting the software for data input:
- Country selection (File>Create)
- Year addition (Year>Add new Year)
- Vehicle selection (Vehicles>Stock Configuration)
the user can then navigate to Exchange>Export Input Structure and create an Excel file to be used by the CLI (Figure 5).
COPERT will create an Excel file where input data are provided in separate tabs.
COPERT vehicle categories
For the COPERT vehicle categories the input data that needs to be provided (in order to obtain reasonable and complete results) are the following:
- Min Temperature
- Max Temperature
- Reid Vapor Pressure (in case of evaporation calculations)
- Mean Activity
- Lifetime Cumulative Activity (in case of evaporation calculations)
- Urban Peak Speed
- Urban Off-Peak Speed
- Rural Speed
- Highway Speed
- Urban Peak Share
- Urban Off-Peak Share
- Rural Share
- Highway Share
- Fuel Year
Non-COPERT vehicle categories
Additional vehicle types can be provided by the user to be calculated along with the standard ones. This can be done by adding at the end of the COPERT list (in the input xlsx file created by COPERT as explained above), the name of the custom vehicle category in the columns “Category”, “Fuel”, “Segment” and “Euro Standard”. Not all of these columns need to be filled but at least one of them. Also, the user has to provide the input information as usual. Required information is standard COPERT information (see Table 3),
and COPERT CLI information, which is the emission factor in unit of mass per unit of activity for the four driving modes (Urban Peak, Urban Off-Peak, Rural and Highway). The column names of the emission factors should have the following structure “YYYY_DM”, meaning the year and the driving mode.
The emission factors have to be provided by driving mode and then by year. For example, if the user wants to calculate 3 years (2010, 2011, 2012), they must provide the emission factors respecting a specific column order, firstly the emission factors for urban off peak driving mode, for all years chronologically (2010_OP, 2011_OP, 2012_OP), then for urban peak driving mode, for all years (2010_PK, 2011_ PK, 2012_ PK), etc. (see Figure 7)
It must be noted that the results will have the same units as the emission factor. If the emission factor is provided in g/km the results will also be in grams. For this reason, it is strongly advised to provide emission factors for new vehicles in a way that all vehicle categories (COPERT and non-COPERT) will have the same units. For example, the results of CO2 emissions for COPERT vehicle categories are displayed in tonnes (t). Thus CO2 emission factors for non-COPERT vehicle categories should be given in t/km for consistency.
The calculation will follow the basic function for the emission calculation:
Emissions [total] = Emissions [urban peak] + Emissions [urban off-peak] + Emissions [rural] + Emissions [highway]
Emissions [urban peak] = vehicle stock [n] x vehicle mean activity [km] x urban peak share [%] x urban peak emission factor [g/vkm]
Emissions [urban off-peak] = vehicle stock [n] x vehicle mean activity [km] x urban off-peak share [%] x urban off-peak emission factor [g/vkm]
Emissions [rural] = vehicle stock [n] x vehicle mean activity [km] x rural share [%] x rural emission factor [g/vkm]
Emissions [highway] = vehicle stock [n] x vehicle mean activity [km] x highway share [%] x highway emission factor [g/vkm]
Emission factors for each pollutant must be provided in separate sheets named according to COPERT standard sheet naming. As an example, in order to provide the CO2 emission factor the user must prepare a sheet named “NEW_CO2_EF”* with the following structure:
COPERT CLI will only calculate results for those pollutants where a valid emission factor has been provided. Only total emissions per driving share can be calculated for custom vehicle types (no distinction between hot, cold etc.). Full export is provided for all COPERT vehicle types. Please also explain how fuel consumption can be calculated for additional vehicle types.
* Additional emission sheets can be named as follows:
The COPERT CLI will export all available results that can be found in the Windows version of the model (Figure 8). For all COPERT vehicle categories all emissions will be exported for all driving modes separately.
For the non COPERT vehicle categories emissions will be exported for all driving modes separately, but results will only be calculated for those pollutants where an emission factor has been provided by the user. For the other pollutants , the non-COPERT vehicles will be displayed in the results with blank emissions. In this way all the “..total” sheets in the results file (not the “..hot”, “..cold” etc. sheets) will have the same number of rows.
Examples of software use
Example 1: Provide a function for the user defined vehicle’s speed
One of the CLI’s major advantages is the ability to integrate in the same file COPERT and non-COPERT vehicle types and their respective emissions. To facilitate emission calculation the user defines an implied emission factors per drive profile (Urban Peak, Urban off peak, Rural and Highway mode) for non COPERT vehicles. Alternatively, the user can define a function for the emission factor which is speed dependent, provide custom vehicle speed in the respective sheet, and link the cells (Figure 9). In this way different scenarios can be performed by using different speeds, even for the non-COPERT vehicle types.
Example 2: How to introduce multiple powertrains (or fuels) for the same vehicle
New vehicles may use more than one motor to operate. Moreover, these motors may consume different fuels provided by external sources. Moreover, it is possible that the fuel consumed may be a blend (e.g. fossil and biofuels), requiring two emission or consumption factors to simulate engine behavior. To model these vehicles the user can “split up” the vehicle according to operation and consumption modes, provide separate emission or consumption factors and calculate results for each part (Figure 10). The model will treat each individual part as a separate vehicle, allowing the user to sum the results into one vehicle type. A good example is the plug-in hybrid vehicle. The user can provide 3 vehicles to the model as in the example in Figure 10.
To simulate the percentage, use for the different operating conditions a split to the activity will be provided. If a 30/70 split exists between electric and internal combustion engine operation and a fuel blend E10 is used, this can be approximated by splitting mean vehicle activity, e.g. 15.000 km per year, into:
30% x 15.000 km = 4.500 km of pure electric propulsion,
and the remaining 10.500 km will be further subsplit 90/10 into petrol and biofuel (Figure 11).
Separate emission or energy consumption factors must be provided by the user for each fuel type. Energy consumption factors are treated in COPERT the same way as emission factors. COPERT will calculate emissions and consumption for all vehicles. The user can at a later stage sum up results in a single row.
Example 3: Provide own emission factors for COPERT vehicle types
It is not possible to provide own emission factor for COPERT vehicle types using the CLI functionality. However, there is a workaround if the user wishes to do so. The user can define a custom vehicle along with the respective input data (stock, activity, custom emission factors etc) with a description matching almost exactly the description of the COPERT vehicle (Figure 12). This way the input information will not be used in the COPERT algorithm but will be treated as a non-COPERT vehicle, allowing for the custom emission factors to be used.
List of abbreviations
|COPERT||Computer programme to calculate emissions from road transport|
|CLI||Command Line Interface|
|xlsx||Microsoft Excel filetype|
|Antigua and Barbuda||AG|
|Bonaire, Sint Eustatius and Saba||BQ|
|Bosnia and Herzegovina||BA|
|British Indian Ocean Territory||IO|
|Central African Republic||CF|
|Cocos (Keeling) Islands||CC|
|Congo, Democratic Republic of||CD|
|Falkland Islands (Malvinas)||FK|
|French Southern Territories||TF|
|Heard Island and McDonald Islands||HM|
|Isle of Man||IM|
|Northern Mariana Islands||MP|
|Palestine, State of||PS|
|Papua New Guinea||PG|
|Saint Helena, Ascension and Tristan da Cunha||SH|
|Saint Kitts and Nevis||KN|
|Saint Martin (French part)||MF|
|Saint Pierre and Miquelon||PM|
|Saint Vincent and the Grenadines||VC|
|Sao Tome and Principe||ST|
|Sint Maarten (Dutch part)||SX|
|South Georgia and the South Sandwich Islands||GS|
|Svalbard and Jan Mayen||SJ|
|Taiwan, Province of China||TW|
|Trinidad and Tobago||TT|
|Turks and Caicos Islands||TC|
|United Arab Emirates||AE|
|United States Minor Outlying Islands||UM|
|Virgin Islands, British||VG|
|Virgin Islands, U.S.||VI|
|Wallis and Futuna||WF|