Command Line Interface (CLI)

From COPERT Documentation
Jump to navigation Jump to search

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.

Table 1 - List of COPERT functionalities vs COPERT CLI functionalities

Installation

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

  1. 2 GHz, 64-bit processor
  2. 8 GB RAM
  3. 30 MB for installation, 100 MB for full run
  4. 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.

Execution

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.

Figure 1 - Command line window

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"

Figure 2 - Example of the CLI execution syntax

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.

Figure 3 - Error message: Output file already exist in the specified folder.

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.

Table 2 - Filetype conversion combinations

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"

Switches

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).

-keep

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).

Figure 4 - Error message: Output COPERT file already exist in the specified folder.

-noevap

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.

Filetype conversion

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

Input data

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:

  1. Country selection (File>Create)
  2. Year addition (Year>Add new Year)
  3. 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).

Figure 5 - Create an xlsx template for COPERT CLI

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)
  • Stock
  • 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
Figure 6 - Export input structure form

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),

Table 3 - Standard COPERT required information

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)

Figure 7 - Example of filling emission factors for different driving modes and years

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:

Table 4 - Custom emission factor input sheet 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:

Table 4 - Naming of custom emission factors sheets

Results

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.

Figure 8 - Available results

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.

Figure 9 - Speed dependent emission factors

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.

Figure 10 - “Split-up” of Plug-in hybrid vehicles

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).

Figure 11 - Activity split of Plug-in hybrid vehicles (Mean Activity Sheet)

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.

Figure 12 - Provide own emission factor for COPERT vehicle types

Glossary

List of abbreviations

List of abbreviations
COPERT Computer programme to calculate emissions from road transport
CLI Command Line Interface
xlsx Microsoft Excel filetype
json JavaScript Object Notation filetype

Annex

Country name abbreviation
Afghanistan AF
Åland Islands AX
Albania AL
Algeria DZ
American Samoa AS
Andorra AD
Angola AO
Anguilla AI
Antarctica AQ
Antigua and Barbuda AG
Argentina AR
Armenia AM
Aruba AW
Australia AU
Austria AT
Azerbaijan AZ
Bahrain BH
Bahamas BS
Bangladesh BD
Barbados BB
Belarus BY
Belgium BE
Belize BZ
Benin BJ
Bermuda BM
Bhutan BT
Bolivia BO
Bonaire, Sint Eustatius and Saba BQ
Bosnia and Herzegovina BA
Botswana BW
Bouvet Island BV
Brazil BR
British Indian Ocean Territory IO
Brunei Darussalam BN
Bulgaria BG
Burkina Faso BF
Burundi BI
Cambodia KH
Cameroon CM
Canada CA
Cape Verde CV
Cayman Islands KY
Central African Republic CF
Chad TD
Chile CL
China CN
Christmas Island CX
Cocos (Keeling) Islands CC
Colombia CO
Comoros KM
Congo CG
Congo, Democratic Republic of CD
Cook Islands CK
Costa Rica CR
Côte d'Ivoire CI
Croatia HR
Cuba CU
Curaçao CW
Cyprus CY
Czech Republic CZ
Denmark DK
Djibouti DJ
Dominica DM
Dominican Republic DO
Ecuador EC
Egypt EG
El Salvador SV
Equatorial Guinea GQ
Eritrea ER
Estonia EE
Ethiopia ET
Falkland Islands (Malvinas) FK
Faroe Islands FO
Fiji FJ
Finland FI
France FR
French Guiana GF
French Polynesia PF
French Southern Territories TF
Gabon GA
Gambia GM
Georgia GE
Germany DE
Ghana GH
Gibraltar GI
Greece GR
Greenland GL
Grenada GD
Guadeloupe GP
Guam GU
Guatemala GT
Guernsey GG
Guinea GN
Guinea-Bissau GW
Guyana GY
Haiti HT
Heard Island and McDonald Islands HM
Vatican City VA
Honduras HN
Hong Kong HK
Hungary HU
Iceland IS
India IN
Indonesia ID
Iran IR
Iraq IQ
Ireland IE
Isle of Man IM
Israel IL
Italy IT
Jamaica JM
Japan JP
Jersey JE
Jordan JO
Kazakhstan KZ
Kenya KE
Kiribati KI
Korea, North KP
Korea, South KR
Kuwait KW
Kyrgyzstan KG
Laos LA
Latvia LV
Lebanon LB
Lesotho LS
Liberia LR
Libya LY
Liechtenstein LI
Lithuania LT
Luxembourg LU
Macao MO
North Macedonia MK
Madagascar MG
Malawi MW
Malaysia MY
Maldives MV
Mali ML
Malta MT
Marshall Islands MH
Martinique MQ
Mauritania MR
Mauritius MU
Mayotte YT
Mexico MX
Micronesia FM
Moldova MD
Monaco MC
Mongolia MN
Montenegro ME
Montserrat MS
Morocco MA
Mozambique MZ
Myanmar MM
Namibia NA
Nauru NR
Nepal NP
Netherlands NL
New Caledonia NC
New Zealand NZ
Nicaragua NI
Niger NE
Nigeria NG
Niue NU
Norfolk Island NF
Northern Mariana Islands MP
Norway NO
Oman OM
Pakistan PK
Palau PW
Palestine, State of PS
Panama PA
Papua New Guinea PG
Paraguay PY
Peru PE
Philippines PH
Pitcairn PN
Poland PL
Portugal PT
Puerto Rico PR
Qatar QA
Réunion RE
Romania RO
Russian Federation RU
Rwanda RW
Saint Barthélemy BL
Saint Helena, Ascension and Tristan da Cunha SH
Saint Kitts and Nevis KN
Saint Lucia LC
Saint Martin (French part) MF
Saint Pierre and Miquelon PM
Saint Vincent and the Grenadines VC
Samoa WS
San Marino SM
Sao Tome and Principe ST
Saudi Arabia SA
Senegal SN
Serbia RS
Seychelles SC
Sierra Leone SL
Singapore SG
Sint Maarten (Dutch part) SX
Slovakia SK
Slovenia SI
Solomon Islands SB
Somalia SO
South Africa ZA
South Georgia and the South Sandwich Islands GS
South Sudan SS
Spain ES
Sri Lanka LK
Sudan SD
Suriname SR
Svalbard and Jan Mayen SJ
Swaziland SZ
Sweden SE
Switzerland CH
Syria SY
Taiwan, Province of China TW
Tajikistan TJ
Tanzania TZ
Thailand TH
Timor-Leste TL
Togo TG
Tokelau TK
Tonga TO
Trinidad and Tobago TT
Tunisia TN
Turkey TR
Turkmenistan TM
Turks and Caicos Islands TC
Tuvalu TV
Uganda UG
Ukraine UA
United Arab Emirates AE
United Kingdom GB
United States US
United States Minor Outlying Islands UM
Uruguay UY
Uzbekistan UZ
Vanuatu VU
Venezuela VE
Vietnam VN
Virgin Islands, British VG
Virgin Islands, U.S. VI
Wallis and Futuna WF
Western Sahara EH
Yemen YE
Zambia ZM
Zimbabwe ZW
Burma (Myanmar) AA
EU28 EU28