wltp 0.1.2a0

概述

计算器接受车辆的技术数据作为输入，以及修改WLTC循环执行参数的参数，然后输出车辆的档位、达到的速度曲线以及任何警告。它不计算任何CO₂排放。

以下图表显示了实验的“执行”或“运行”

           .---------------------.                         .----------------------------.
          ;   Input-DataModel   ;                         ;      Output-DataModel       ;
         ;---------------------;                         ;----------------------------;
        ; +--vehicle          ;     ____________        ; +---...                    ;
       ;  +--params          ;     |            |      ;  +--cycle_run:             ;
      ;       +--wltc_data  ;  ==> |   Cycle    | ==> ;      t  v_class gear ...   ;
     ;                     ;       | Generator  |    ;      --------------------  ;
    ;                     ;        |____________|   ;       00      0.0    1     ;
   ;                     ;                         ;        01      1.3    1    ;
  ;                     ;                         ;         02      5.5    1   ;
 ;                     ;                         ;          ...               ;
'---------------------'                         '----------------------------.

输入和输出数据模型是pandas-model的实例，由字符串和数字组成的树，通过以下方式组装：

• 序列，

• 字典，

• 类（pandas.DataFrame），

• 类（pandas.Series），以及

• 指向其他模型树的URI引用。

快速入门

假设您有一个有效的Python环境，打开一个命令提示符，（在Windows中使用程序（cmd.exe）但确保程序（python.exe）在其env[$PATH]中），您可以尝试以下命令

安装:

$ pip install wltp                      ## Use `--pre` if version-string has a build-suffix.
$ wltp --winmenus                       ## Adds StartMenu-items, Windows only.

或者如果您需要最新版本的master分支

$ pip install git+git://github.com/ankostis/wltp.git@master --pre

参阅：doc(安装)

命令行:

$ wltp --version
0.1.2a0

$ wltp --help
...

参阅：ref: cmd-line-usage

Excel:

$ wltp --excelrun                       ## Windows & OS X only

参阅：ref: excel-usage

Python代码:

from wltp.experiment import Experiment

input_model = { ... }           ## See also "Python Usage" for model contents.
exp = Experiment(input_model)
output_model = exp.run()
print('Results: \n%s' % output_model['cycle_run'])

参阅：ref: python-usage

Python安装

如上所述，此项目依赖于需要使用C和Fortran编译器从源代码构建的具有本地后端的包。为了避免这种麻烦，您应选择以下建议的友好型分发之一。

以下是两个建议的自封装Python分发程序的矩阵，用于运行此程序（我们在此排除了linux中包含的默认python）。这两个分发

• 都是免费的（就自由而言），

• 在Windows中安装不需要管理员权限，并且

• 已经测试过可以成功运行此程序（也在默认的linux发行版上测试过）。

包安装

在安装之前，请确保您的Python安装上没有遗留旧版本。要干净地卸载它，请运行此命令，直到您找不到任何项目安装

$ pip uninstall wltp                        ## Use `pip3` if both python-2 & 3 are in PATH.

您可以通过在控制台中键入命令(pip)直接从PyPi仓库以“标准”方式安装项目

$ pip install wltp

• 如果您想安装一个预发布版本（版本字符串不是纯数字，而是以alpha、beta.2或类似结尾），请使用附加选项(–pre)。

$ pip install wltp

• 您还可以直接从源代码安装最新版本

  $ pip install git+git://github.com/ankostis/wltp.git  --pre

• 如果您想升级现有安装及其所有依赖项，请添加选项（–upgrade）（或等价的选项（-U）），但构建完成可能需要一些时间。此外，升级后的库可能会破坏现有程序（！）因此请谨慎使用，或在virtualenv（独立的Python环境）内使用。

• 为了在不同的Python环境中安装，请为每个环境重复使用适当的程序（python.exe）解释器。

安装后，检查您的env[$PATH]中可见的版本是很重要的。

$ wltp --version
0.1.2a0

为了安装不同的Python版本，为每个所需的版本重复此过程。

旧版本

项目版本控制方案的另一个目的是跟踪项目实现了GTR的哪个特定版本。给定版本号MAJOR.MINOR.PATCH，MAJOR部分跟踪实现的GTR阶段。有关MAJOR数字到GTR版本映射的详细信息，请参阅doc（CHANGES）中的“GTR版本矩阵”部分。

要安装旧版本，请输入控制台命令

$ pip install wltp=1.1.1                    ## Use `--pre` if version-string has a build-suffix.

或者直接从源代码中安装

$ pip install git+git://github.com/ankostis/wltp.git@v0.0.9-alpha.3.1  --pre

当然，您可以用“commits”、“branches”或“releases”中的任何slug替换v0.0.9-alpha.3.1，这些slug您可以在项目的github-repo中找到。

从源安装

如果您下载了源代码，您将有更多的安装选项。有多种方法可以获取它们

• 从PyPi仓库下载source发行版。

• 从github下载发布快照

• 从github克隆git-repository

  假设您已安装了git的工作安装，您可以使用以下一系列命令获取并安装项目的最新版本

  $ git clone "https://github.com/JRCSTU/wltp.git" wltp.git
  $ cd wltp.git
  $ python setup.py install                                 ## Use `python3` if both python-2 & 3 installed.

当使用源代码工作时，您需要安装项目所依赖的所有库

$ pip install -r requirements/execution.txt .

前面的命令安装了项目在源代码中找到的“快照”。如果您希望将项目的源代码与Python环境链接，请在开发模式中安装项目

$ python setup.py develop

项目文件和文件夹

以下是项目的文件和文件夹列表

+--wltp/            ## (package) The python-code of the calculator
|   +--cycles/      ## (package) The python-code for the WLTC data
|   +--test/        ## (package) Test-cases and the wltp_db
|   +--model        ## (module) Describes the data and their schema for the calculation
|   +--experiment   ## (module) The calculator
|   +--plots        ## (module) Diagram-plotting code and utilities
+--docs/            ## Documentation folder
|   +--pyplots/     ## (scripts) Plot the metric diagrams embeded in the README
+--devtools/        ## (scripts) Preprocessing of WLTC data on GTR and the wltp_db
|   +--run_tests.sh ## (script) Executes all TestCases
+--setup.py         ## (script) The entry point for `setuptools`, installing, testing, etc
+--requirements/    ## (txt-files) Various pip-dependencies for tools.
+--README.rst
+--CHANGES.rst
+--LICENSE.txt

命令行用法

以下命令行用法需要安装Python环境，并允许您直接从OS的shell（即Windows中的程序（cmd）或POSIX中的程序（bash））执行实验，并使用单个命令。为了精确控制输入和输出（即“批量”实验和/或实验设计），您必须使用API python运行实验，如下文所述。

入口脚本名为program(wltp)，必须在安装过程中放置到您的env[$PATH]中。此脚本可以通过读取多个文件中的输入数据或覆盖特定单值项来构建一个模型。相反，它还可以将结果模型的多个部分输出到文件中。

要获取此脚本的帮助，请使用以下命令

$ wltp --help                               ## to get generic help for cmd-line syntax
$ wltcmdp.py -M vehicle/full_load_curve     ## to get help for specific model-paths

然后，假设vehicle.csv是一个CSV文件，其中包含您想要覆盖的n_idle的车辆参数，请运行以下命令

$ wltp -v \
    -I vehicle.csv file_frmt=SERIES model_path=params header@=None \
    -m vehicle/n_idle:=850 \
    -O cycle.csv model_path=cycle_run

Excel用法

在Windows和OS X中，您可以利用优秀的xlwings库，使用Excel文件为实验提供输入和输出。

要在当前目录中创建必要的模板文件，请输入

$ wltp --excel

或者，您可以输入samp(wltp –excel {file_path})来指定不同的目标路径。

在windows/OS X中，您可以输入samp(wltp –excelrun)，文件将在您的家目录中创建，并且Excel将一次性打开它们。

上述所有命令创建两个文件

文件(wltp_excel_runner.xlsm)

这是一个Python启用的Excel文件，其中写入输入和输出数据，如下面的截图所示

第一次打开时，请启用工作簿中的宏，选择左侧的Python代码，然后单击菜单选择(运行选择为Python)按钮；应该为每辆车创建一个工作表。

Excel文件还包含适当的VBA模块，允许您通过单击按钮调用选定的单元格中的Python代码，以及在此下面的Python脚本中声明的Python函数，使用mypy命名空间。

要添加更多输入列，您需要将所需的模型项的json-pointer路径设置为列标题（参见下文python-usage中的参考）。

文件(wltp_excel_runner.py)

上述xls文件使用的实用Python函数用于运行一系列实验。

包含的特定函数从输入表中读取多个具有不同车辆特征和/或实验参数的车辆，然后添加包含每个车辆循环运行的新工作表。当然，您可以编辑它以满足您的需求。

有关从Excel单元格中的Python代码的一些一般说明

• 在每次调用时，预定义的VBA模块pandalon在Excel文件所在的同一文件夹中执行动态生成的Python脚本文件，其中还导入“姐妹”Python脚本文件。您可以读取并修改姐妹Python脚本以导入库（如“numpy”和“pandas”），或预定义实用Python函数。

• 姐妹Python脚本的名字是自动从Excel文件的名字计算出来的，并且它必须是一个有效的Python模块名字。因此，不要在Excel文件中使用非字母数字字符，如空格(`` )、连字符(-)和点(.``)。

• 出现错误时，将在Excel文件所在的同一文件夹中写入一个日志文件，直到消息框可见，并且点击“确定”后会自动删除！

• 阅读http://docs.xlwings.org/quickstart.html

Python用法

以下是一些示例 Python REPL（读取-评估-打印循环）命令，用于设置和运行一个实验。

首先运行命令（python）或命令（ipython），尝试导入项目以检查其版本

代码块

>>> import wltp

>>> wltp.__version__            ## Check version once more.
'0.1.2a0'

>>> wltp.__file__               ## To check where it was installed.         # doctest: +SKIP
/usr/local/lib/site-package/wltp-...

如果一切正常，创建一个用于保存实验输入数据（字符串和数字）的 pandas-model。您可以使用以下方式构建模型树

• 序列，

• 字典，

• 类（pandas.DataFrame），

• 类（pandas.Series），以及

• 指向其他模型树的URI引用。

例如

代码块

>>> from wltp import model
>>> from wltp.experiment import Experiment
>>> from collections import OrderedDict as odic         ## It is handy to preserve keys-order.

>>> mdl = odic(
...   vehicle = odic(
...     unladen_mass = 1430,
...     test_mass    = 1500,
...     v_max        = 195,
...     p_rated      = 100,
...     n_rated      = 5450,
...     n_idle       = 950,
...     n_min        = None,                            ## Manufacturers my overridde it
...     gear_ratios         = [120.5, 75, 50, 43, 37, 32],
...     resistance_coeffs   = [100, 0.5, 0.04],
...   )
... )

有关接受模型数据的详细信息，请检查其 JSON-schema

代码块

>>> model.json_dumps(model.model_schema(), indent=2)                                # doctest: +SKIP
{
  "properties": {
    "params": {
      "properties": {
        "f_n_min_gear2": {
          "description": "Gear-2 is invalid when N :< f_n_min_gear2 * n_idle.",
          "type": [
            "number",
            "null"
          ],
          "default": 0.9
        },
        "v_stopped_threshold": {
          "description": "Velocity (Km/h) under which (<=) to idle gear-shift (Annex 2-3.3, p71).",
          "type": [
...

然后，您需要将此模型树传递给类（~wltp.experiment.Experiment）构造函数。内部类（~wltp.pandel.Pandel）解析 URI、填充默认值并根据项目预先定义的 JSON-schema 验证数据

代码块

>>> processor = Experiment(mdl)         ## Fills-in defaults and Validates model.

假设验证通过且没有错误，您现在可以运行实验之前检查默认模型

代码块

>>> mdl = processor.model               ## Returns the validated model with filled-in defaults.
>>> sorted(mdl)                         ## The "defaulted" model now includes the `params` branch.
['params', 'vehicle']
>>> 'full_load_curve' in mdl['vehicle'] ## A default wot was also provided in the `vehicle`.
True

现在您可以运行实验

代码块

>>> mdl = processor.run()               ## Runs experiment and augments the model with results.
>>> sorted(mdl)                         ## Print the top-branches of the "augmented" model.
['cycle_run', 'params', 'vehicle']

要访问基于时间的循环结果，最好使用类（pandas.DataFrame）

代码块

>>> import pandas as pd
>>> df = pd.DataFrame(mdl['cycle_run']); df.index.name = 't'
>>> df.shape                            ## ROWS(time-steps) X COLUMNS.
(1801, 11)
>>> df.columns
Index(['v_class', 'v_target', 'clutch', 'gears_orig', 'gears', 'v_real', 'p_available', 'p_required', 'rpm', 'rpm_norm', 'driveability'], dtype='object')
>>> 'Mean engine_speed: %s' % df.rpm.mean()
'Mean engine_speed: 1940.72109939'
>>> df.describe()
           v_class     v_target     clutch   gears_orig        gears  \
count  1801.000000  1801.000000       1801  1801.000000  1801.000000
mean     46.506718    46.506718  0.0660744     3.794003     3.683509
std      36.119280    36.119280  0.2484811     2.278959     2.278108
...
<BLANKLINE>
            v_real  p_available   p_required          rpm     rpm_norm
count  1801.000000  1801.000000  1801.000000  1801.000000  1801.000000
mean     50.356222    28.846639     4.991915  1940.721099     0.214898
std      32.336908    15.833262    12.139823   840.959339     0.195142
...

>>> processor.driveability_report()                                             # doctest: +SKIP
...
  12: (a: X-->0)
  13: g1: Revolutions too low!
  14: g1: Revolutions too low!
...
  30: (b2(2): 5-->4)
...
  38: (c1: 4-->3)
  39: (c1: 4-->3)
  40: Rule e or g missed downshift(40: 4-->3) in acceleration?
...
  42: Rule e or g missed downshift(42: 3-->2) in acceleration?
...

您可以使用以下 pandas 命令将循环运行结果导出到 CSV 文件

>>> df.to_csv('cycle_run.csv')                                                      # doctest: +SKIP

有关更多示例，请下载源代码并检查文件（/wltp/test/）文件夹中找到的测试用例。

IPython笔记本用法

wltp 的 IPython notebooks 列表维护在项目的 wiki 上。

源和依赖项

要参与开发，您需要一个 POSIX 环境，才能完全构建它（Linux、OSX 或 Windows 上的 Cygwin）。

首先您需要下载最新的源代码

$ git clone https://github.com/JRCSTU/wltp.git wltp.git
$ cd wltp.git

然后您可以使用文件（setup.py）脚本在 `开发模式` 下安装所有项目的依赖项

$ python setup.py --help                           ## Get help for this script.
Common commands: (see '--help-commands' for more)

  setup.py build      will build the package underneath 'build/'
  setup.py install    will install the package

Global options:
  --verbose (-v)      run verbosely (default)
  --quiet (-q)        run quietly (turns verbosity off)
  --dry-run (-n)      don't actually do anything
...

$ python setup.py develop                           ## Also installs dependencies into project's folder.
$ python setup.py build                             ## Check that the project indeed builds ok.

现在您应该运行测试用例（见 doc（metrics））以检查源代码是否处于良好状态

$ python setup.py test

开发流程

提交代码时，请确保使用UTF-8编码，UNIX行结束符(LF)，并设置git --config core.autocrlf = input。

典型的发展过程如下

1. 修改源代码，进行小、隔离和定义良好的更改，即添加单个功能或修复特定错误。

2. 添加测试用例“证明”您的代码。

3. 重新运行所有测试用例，以确保您没有破坏任何东西，并检查它们的覆盖率保持在80%以上。

   $ python setup.py nosetests --with-coverage --cover-package wltp.model,wltp.experiment --cover-min-percentage=80

4. 如果您进行了相当重要的修改，请更新doc（CHANGES）文件和其他文档（例如README.rst）。要查看文档的渲染结果，请发出以下命令，并在文件（build/sphinx/html/index.html）中阅读结果HTML。

   $ python setup.py build_sphinx                  # Builds html docs
   $ python setup.py build_sphinx -b doctest       # Checks if python-code embeded in comments runs ok.

5. 如果没有问题，请使用描述性消息提交更改。

6. 重复此循环以修复其他错误/增强功能。

7. 完成后，将更改推送到github并创建一个merge_request。您可以通过检查集成服务器（TravisCI）上的构建状态（）来检查您的merge-request是否确实通过了测试。

规范和算法

此程序基于以下下载（GTR规范 <23.10.2013 ECE-TRANS-WP29-GRPE-2013-13 0930.docx>）从头开始实现（包含在docs/文件夹中）。此GTR的最新版本以及其他相关文档可以在UNECE网站上找到

• http://www.unece.org/trans/main/wp29/wp29wgs/wp29grpe/grpedoc_2013.html

• https://www2.unece.org/wiki/pages/viewpage.action?pageId=2523179

• 可能还有这样一个更易于理解但较旧的规范：https://www2.unece.org/wiki/display/trans/DHC+draft+technical+report

文件（devtools/data/cycles/）文件夹中各种类别的WLTC配置文件是从上述规范的表格中生成的，使用文件（devtools/csvcolumns8to2.py）脚本，但仍需要涉及电子表格的中间手动步骤，将表格复制到其中并保存为CSV。

然后使用文件（devtools/buildwltcclass.py）将相应的python-vars构建到mod（wltp/model.py）源中。

使用来自Steven Heinz的ms-access 车辆信息 db表的数据文件可以通过文件（devtools/preprocheinz.py）脚本进行处理。

开发团队

• 作者

  • Kostis Anagnostopoulos

• 贡献作者

  • Heinz Steven（测试数据、验证和审查）

  • Georgios Fontaras（模拟、物理和工程支持）

  • Alessandro Marotta（政策支持）