Skip to content

8. The DICE.

Jump to bottom
dimitriskomnos edited this page Sep 1, 2018 · 44 revisions

For each WLTP interpolation family following a completed test run of the CO2MPAS, the type approval authority or the designated technical service shall use the relevant commands in the correlation tool to send the signed dice report to a timestamp server and then to a functional mailbox in DG CLIMA. Prior to your first use of Dice, please send an e-mail to JRC-CO2MPAS@ec.europa.eu to appropriately configure your e-mail settings for the use of the sampling feature.

Overview of the DICE Workflow

To get the flowchart of dicing, take a peek at the "CO2MPAS dice workflow" presentation.

For the user, the DICE workflow includes 5 steps.

  1. The first step is, after running the simulation in CO2MPAS software, to append the input file and the generated output file in a DICE project in your local machine. They are stored in the local DICE files Database

  2. The second step is to generate the dice report from the files you inserted. The report includes information about the date-time the simulation occurred, the version of CO2MPAS, if the simulation was set in Type approval mode, the deviation from the declared and the simulated CO2MPAS NEDC result, and the scores that the CO2MPAS sub-models achieved.

  3. The dice report is then sent through:

    • either an e-mail to the timestamp server through the dice request email using the SMTP protocol. The timestamp server is an automatic digital timestamping service which is used to corroborate the date in a signed document with PGP. The timestamp server, sends the signed document back through the dice response email using the IMAP protocol.
    • or the WebStamper, JRC’s user-friendly stamper web-application that uses a simple HTTP-form to timestamp a pasted dice report and return a dice stamp, emailing it also to any specified recipients, always including from CLIMA/JRC.

    NOTE: For the purposes of the vehicle type approving, the users of timestamp server need to add as recipients of the dice response email at least these 3 recipients: CLIMA, JRC-CO2MPAS, their official user's e-mail (the last one for identification purposes).

  4. Once you have received the dice response email, you need to decode it. You can do this either automatically (if properly configured, the DICE can read the emails coming from the timestamp server), or manually (copying the dice response email and pasting it in the CO2MPAS console). This step will provide the SAMPLE/ NOSAMPLE decision, meaning that you have to do a double test (physical NEDC test), or not, respectively.

  5. The last step is to export and archive the project.

Below, there is a diagram of the DICE stages, as explained above:

Getting started with the DICE

  • For running the DICE, you need to create in your CO2MPAS HOME directory a folder named .co2dice. With Windows Explorer a new folder can be created using an additional dot at the end (.co2dice.). Alternatively, this step can be done through the console typing the command: mkdir .co2dice

  • You need 2 extra files in order to be able to run the DICE tool. The first one is the configuration file, that stores all the configurations for your e-mail account, named co2dice_config.py. The second is the co2dice_persist.json, that stores the password for the e-mail account that you are going to use for sending dice report from a vehicle and receiving the dice response email from the Timestamp server.

  • In order to obtain these 2 files:

    1. The co2dice_config.py can be generated, in its full form, with the command: co2dice config write. This command will store an empty co2dice_config.py file with all the possible configurations that you are able to set up in the directory CO2MPAS/.co2dice. You may ask us to provide you a sample of it with the most frequent changes that you may have to do.
    2. The co2dice_persist.json, is provided directly by the JRC. Petitions must be done through the JRC-CO2MPAS@ec.europa.eu functional mailbox.

  • We suggest you to navigate in the co2dice commands and sub-commands in order to see the full capabilities of the DICE. In each step, adding the flag --help will provide a description of what the command does and how you can proceed. Examples are included, too.

confguration hierarchy

Steps to use the Dice

  • Make sure to properly fill in the input file (in particular, the vehicle_family_id since all the sampling procedure will use this ID as identifier.
  • Run CO2MPAS in Type Approval mode.
  • Once the simulation has finished and the output file is generated, open the CO2MPAS console by clicking the launch console button.

  • When you have done the above steps, by typing co2dice project ls it is possible to get information on the state of the workflow. If you have not configured your e-mail client you will be prompted the following message. Please, send an e-mail to the CO2MPAS-Team to start dicing.
> co2dice project ls
2017-07-10 16:05:09:ERROR:co2mpas.sampling.dice.Co2diceCmd:co2dice: encountered invalid configs: No DICE-configurations found in ['D:\\Apps\\co2mpas_AIO-v1.6.1b2\\CO2MPAS\\.co2dice\\co2dice_config.py']!
  Ask JRC for configs, or copy/adapt them from your old AIO.

If the e-mail config file is properly set when typing co2dice project ls, a list of all dice projects (if any) in the repository will appear together with their status. The following capture shows dice repository with some projects already started. The one marked with an asterisk * is the active Dice project. In order to change the active project type co2dice project open name-of-the-project.

  • type co2dice project init vehicle_family_id to start working with the Dice on the file that has just been generated by CO2MPAS (eg co2dice project init IP-10-AAA-2017-1023). This action will generate a "folder" that will contain all the files needed to run the dice. Now, by typing co2dice project ls the project appears in the list and its state is empty.

Now, by typing co2dice project ls the project appears in the list and its state is empty.

  • type:

    > co2dice project append  -i C:/MyInputfile.xlsx  -o C:/MyOutputfile.xlsx

    to add the Input, and the Output files from CO2MPAS into the DICE-project. Now the state of the project is wltp_iof meaning that input and output file have been added to the project. Note that additional files can be added to the project (eg, log files generated by CO2MPAS in case the model failed to produce the output)

TIP: Some more capabilities until this point.

  1. NOTE the -f: It forces to overwrite input and and output files.
> co2dice project append -i co2mpas_input.xlsx -o co2mpas_results.xlsx -f
  1. You can append the input files separately from the output files. In case you want to add more than one input files (This can happen if you have in different files the Vehicle-H and Vehicle-L)
> co2dice project append -i co2mpas_input_1.xlsx -i co2mpas_input_2.xlsx ...
  1. In case you want to add more than one output files (This can happen if you have in different files the Vehicle-H and Vehicle-L)
> co2dice project append -o co2mpas_output_1.xlsx -o co2mpas_output_2.xlsx ...
  1. You can have several projects open in different stages. In order to change your current project to an other one, you have to use the sub-command open, followed by the vehicle_family_id:
> co2dice project open XX-12-YYY-2017-0000
  • type co2dice project report to generate the contents of the Dice email that contains a Hash coding the Input and Output file + the Dice report. You will be prompted with the generated report.

The state of the project is now tagged.

TIP: Some more capabilities until this point.

  1. In order to be more sufficient, there is the capability of summing all the steps until here (init, append, report), with the command line bellow:
> co2dice init -i co2mpas_input.xlsx -o co2mpas_results.xlsx --report

After the step above, there are two different ways to continue.

  1. With the e-mail Stamper
  2. With the WebStamper

E-mail Stamper

  • Before sending the DICE report, you have to see if you have set up the configurations (co2dice_config.py and co2dice_persist.json) correctly for logging in your SMTP and IMAP servers. This step is essential, since DICE needs access to the e-mail server in order to automatically send the report and automatically receive and parse the time-stamp response. Type co2dice tstamp login. If you can successfully log in, the response in the console is True for both SMTP and IMAP.

  • type co2dice project tsend to send the Dice email to the time-stamp server. The Dice email will be sent and the state of the project is mailed

  • After 10-15 minutes you will receive in your provided e-mail address the dice-stamp that has to be decoded by typing in the console. There are 2 ways to parse the time stamp response.

    1. With the command co2dice project tparse. Copy the e-mail received (from -----BEGIN PGP SIGNED MESSAGE----- to the end) and paste it in the console by pressing [Shift+INSERT], and send the end-stream character after a new-line, that is to say: press [Enter], [Ctrl+Z], [Enter], in a row.
      More for this option, in the Manual procedure, below.

    2. With the command: co2dice project trecv vehicle_family_id. There are several criteria in order to filter the response and manage to parse it.

And you will and end up with the message below:

The dice stamp has been decoded showing at the end of the message the random sampling number [0 to 99], and the OK/SAMPLE decision-flag. In the case of the example, it is an OK code, and the state of the project become nosample.

WebStamper

  • Copy the DICE-report: From the state tagged you need to copy the DICE report by just selecting it with the left-mouse button, in order to feed it to the WebStamper:
object 5a2712a23c466ea4d85d720670f44197a8828930
type commit
tag dices/IP-10-AAA-2017-0000/0
tagger Test User <dimitriskomnos11@gMail.com> 1510066363 +0100

- {v: 1.0.2, a: drep 2 files, p: IP-10-AAA-2017-0000, s: tagged}

- file: co2mpas_demo-0.xlsx

[...]

-----END PGP SIGNATURE-----

TIP: Make sure your selection include the start & end lines, in full (without missing any character), as shown above.

  • Open the WebStamper in your browser (JRC will provide you the URL). Populate the the following 3 fields:

    1. Sender: There, you may insert your designated-email and/or your name or id (free form, but only ASCII chars are allowed).
    2. Stamp Recipients: The recipients of the Timestamp. Insert the e-mail addresses that you want the Timestamp response want to reach. You do not need to add CLIMA and JRC, since they are appended automatically.
    3. Dice Report: Paste here the dice-report as copied from the previous step.

  • Stamp! After populating the above Stamper web-app fields, you have to:

    1. Click the 1: Check… button, to validate your field-values, and check that a blue and not a red-ish validation-messages are produced, like that:

    2. Click the 2: Stamp! button, and that's it!
      The recipients listed in the submit-message must have now received your stamp-response, which will be also visible in the "DICE report stamped" text-box:

  • Proceed project to stage mailed (Ignore this step in case of version 1.7.4 or later):

co2dice project tsend --dry-run

TIP: Ignore the output of this command (which is comprised of some config-values for the recipients + the dice-report).

  • Import stamp-response into the project Paste back the stamp-response copied from WebStamper (or from your email inbox) into this console command: co2dice project tparse Running that command will await for your input; assuming your clipboard contains the copied tstamp, you may paste and finalize the command with this key sequence: [Shift+Insert], [Enter], [Ctrl+Z], [Enter], or use the mouse to paste it and [Enter], [Ctrl+Z], [Enter].

Finalizing the DICE project

The finalization procedure includes 2 steps:

  • Construct the HASH-2 for certification paper-forms. Depending on the CO2MPAS version:

    1. for CO2MPAS version earlier than 1.7.x, for example the version 1.5.7.b3, the HASH-2 corresponds to the hexnum that is shown in the console when parsing the DICE e-mail.
    2. for CO2MPAS version 1.7.x, co2dice project trecv/tparse commands generate another type of report, the "decision-report", that is also signed with your secret-key, and which contains HASH-2 at the top. The report command has also been retrofitted to printout this 2nd "decision-report", as seen below:
      Use that highlighted elements to construct the HASH-2 for certification paper-forms and/or emails exchanged with TAAs, like that: dices/IP-10-AAA-2017-1234/1 936845d307388a8a44f02855b075cf69b1817d82 Actually just using the first 7-10 characters of the hash is enough to identify the specific dice procedure in its entirety: 936845d3073

  • Finally, type co2dice project export project_number for example(co2dice project export IP-10-AAA-2017-1023) in order to store (in a compressed .zip file) all the files used in the Dice workflow (ie, the input file to CO2MPAS, the CO2MPAS-TA output file, and the Dice decision). Example:

co2dice project export IP-10-AAA-2017-1023
...
packed: projects/IP-10-AAA-2017-1023
packed: dices/IP-10-AAA-2017-1023/1
packed: projects/IP-10-AAA-2017-1023
Archive: ~co2mpas_AIO\CO2MPAS\CO2MPAS_projects-20180901-021326.zip

This file has to be sent to the Type Approval authority that will keep it as part of the TA of the vehicle.

Importing a DICE project

Importing one or multiple DICE project(s) from one AIO to another can be essential. This can used in order to continue working in a project from another computer or AIO. To import a DICE project, you need to trace the exported project and type the command co2dice project import exported_zip_file. Example:

co2dice project import ~co2mpas_AIO\CO2MPAS\CO2MPAS_projects-20180901-021326.zip
...
unpacked: projects/IP-10-AAA-2017-1023
unpacked: dices/IP-10-AAA-2017-1023/0
unpacked: dices/IP-10-AAA-2017-1023/1
...

Steps to dice manually in case of the e-mail Stamper

In case that you face problems connecting to the e-mail client from the console, you can always send the report to the time-stamp server and parse the dice-stamp manually:

  • After generating the report for the dice with the below command:
> co2dice project report

You have to continue with the following:

  • Proceed with the co2dice project tsend --dry-run.

  • As it is written in the first message logs, you have to open the e-mail account and create a new email. There, you have to set the e-mail as plain-text. Below, there are some examples:
    Gmail:


Outlook:

  • Copy with [Left Click] and selecting from the first line starting from the X-Stamper-To: (In the console just selecting the message it is automatically copied.)

  • Paste the message in the new email, specify as recipient post@stamper.itconsult.co.uk, specify as CC JRC-CO2MPAS@ec.europa.eu, and set the same subject as specified in the in the report that the co2dice project tsend --dry-run produces in the field Subject:
Subject: dice test dices/IP-10-AAA-2017-1024/0

In the above example: dice test dices/IP-10-AAA-2017-1024/0

  • Send the e-mail.

  • After 10-15 minutes you will receive in your provided e-mail address the dice stamp that has to be decoded by typing in the console co2dice project tparse. Copy the e-mail received (from -----BEGIN PGP SIGNED MESSAGE----- to the end) and paste it in the console by pressing [Shift+INSERT], and send the end-stream character after a new-line, that is to say: press [Enter], [Ctrl+Z], [Enter], in a row. The dice stamp will be decoded showing at the end of the message the random sampling number [0 to 99], and the OK/SAMPLE decision-flag. In the case of the example, it is a 'OK' code, and the state of the project become nosample.

Dice scenarios

The dice stamp includes a randomly generated integer number in the range 0 to 99 which is automatically translated into the dice decision. Where the number is in the range of 90 to 99 (SAMPLE) the vehicle shall be selected for one physical NEDC measurement taking into account the precisions specified in section 3.3. of Annexes to the correlation regulation. The test results shall be documented in accordance with Annex VIII to Directive 2007/46/EC. From the obtained random number, four scenarios are possible:

  • Scenario 1: In the case that for both vehicles H and L the CO2MPAS deviation did not exceed 4 percent and for both vehicles (L and H) the manufacturer declared value is accepted, the vehicle configuration selected for physical measurement shall be the vehicle L, if the random number is in the range from 90 to 94, and vehicle H, if the random number is in the range from 95 to 99.

  • Scenario 2: For one vehicle configuration CO2MPAS deviation did exceed 4 percent and that vehicle is physically tested. For another configuration CO2MPAS deviation did not exceed 4 percent and for that vehicle the manufacturer declared value is accepted. If the random number received is in the range from 90 to 99 physical measurement should be performed for the vehicle configuration where declared value is accepted and where CO2MPAS deviation did not exceed 4 percent.

  • Scenario 3: For one vehicle configuration CO2MPAS deviation did exceed 4 percent but the vehicle is not physically tested and CO2MPAS result is accepted. For another configuration CO2MPAS deviation did not exceed 4 percent and for that vehicle the manufacturer declared value is accepted. If the random number received is in the range from 90 to 94 vehicle L shall be tested and if the random number received is in the range from 95 to 99 vehicle H shall be tested.

  • Scenario 4: If the CO2MPAS deviation did exceed 4 percent for both vehicle configurations (vehicle H and L) and both vehicles are physically tested, the reply from the time-stamped server in terms of generated random number should be ignored.

Back to the Index of the user guidelines

Clone this wiki locally