4. Getting Involved¶
This project is hosted in github. To provide feedback about bugs and errors or questions and requests for enhancements, use github’s Issue-tracker.
4.1. Sources & Dependencies¶
To get involved with development, you need a POSIX environment to fully build it (Linux, OSX or Cygwin on Windows).
First you need to download the latest sources:
$ git clone https://github.com/ankostis/wltp.git wltp.git $ cd wltp.git
You may choose to work in a virtualenv (isolated Python environment), to install dependency libraries isolated from system’s ones, and/or without admin-rights (this is recommended for Linux/Mac OS).
If you decide to reuse stystem-installed packages using --system-site-packages with virtualenv <= 1.11.6 (to avoid, for instance, having to reinstall numpy and pandas that require native-libraries) you may be bitten by bug #461 which prevents you from upgrading any of the pre-installed packages with pip.
Within the sources there are two sample files for the comprehensive LiClipse IDE:
Remove the eclipse prefix, (but leave the dot()) and import it as “existing project” from Eclipse’s File menu.
Another issue is caused due to the fact that LiClipse contains its own implementation of Git, EGit, which badly interacts with unix symbolic-links, such as the docs/docs, and it detects working-directory changes even after a fresh checkout. To workaround this, Right-click on the above file Properties ‣ Team ‣ Advanced ‣ Assume Unchanged
Then you can install all project’s dependencies in `development mode using the setup.py script:
$ 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.
You should now run the test-cases (see ref:metrics, below) to check that the sources are in good shape:
$ python setup.py test
The above commands installed the dependencies inside the project folder and for the virtual-environment. That is why all build and testing actions have to go through python setup.py some_cmd.
If you are dealing with installation problems and/or you want to permantly install dependant packages, you have to deactivate the virtual-environment and start installing them into your base python environment:
$ deactivate $ python setup.py develop
or even try the more permanent installation-mode:
$ python setup.py install # May require admin-rights
4.2. Development procedure¶
For submitting code, use UTF-8 everywhere, unix-eol(LF) and set git --config core.autocrlf = input.
The typical development procedure is like this:
Modify the sources in small, isolated and well-defined changes, i.e. adding a single feature, or fixing a specific bug.
Add test-cases “proving” your code.
Rerun all test-cases to ensure that you didn’t break anything, and check their coverage remain above 80%:
$ python setup.py nosetests --with-coverage --cover-package wltp.model,wltp.experiment --cover-min-percentage=80
You can enter just: python setup.py test_all instead of the above cmd-line since it has been aliased in the setup.cfg file. Check this file for more example commands to use during development.
If you made a rather important modification, update also the Changes file and/or other documents (i.e. README.rst). To see the rendered results of the documents, issue the following commands and read the result html at build/sphinx/html/index.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.
If there are no problems, commit your changes with a descriptive message.
Repeat this cycle for other bugs/enhancements.
When you are finished, push the changes upstream to github and make a merge_request. You can check whether your merge-request indeed passed the tests by checking its build-status on the integration-server’s site (TravisCI).
Skim through the small IPython developer’s documentantion on the matter: The perfect pull request
4.3. Specs & Algorithm¶
This program was implemented from scratch based on this GTR specification (included in the docs/ folder). The latest version of this GTR, along with other related documents can be found at UNECE’s site:
- Probably a more comprehensible but older spec is this one: https://www2.unece.org/wiki/display/trans/DHC+draft+technical+report
The WLTC-profiles for the various classes in the devtools/data/cycles/ folder were generated from the tables of the specs above using the devtools/csvcolumns8to2.py script, but it still requires an intermediate manual step involving a spreadsheet to copy the table into ands save them as CSV.
Then use the devtools/buildwltcclass.py to construct the respective python-vars into the wltp/model.py sources.
Data-files generated from Steven Heinz’s ms-access vehicle info db-table can be processed with the devtools/preprocheinz.py script.
4.4. Tests, Metrics & Reports¶
In order to maintain the algorithm stable, a lot of effort has been put to setup a series of test-case and metrics to check the sanity of the results and to compare them with the Heinz-db tool or other datasets included in the project. These tests can be found in the wltp/test/ folders.
Additionally, below are auto-generated representative diagrams with the purpose to track the behavior and the evolution of this project.
You can reuse the plotting code here for building nice ipython-notebooks reports, and (optionally) link them in the wiki of the project (see section above). The actual code for generating diagrams for these metrics is in wltp.plots and it is invoked by scripts in the docs/pyplot/ folder.
4.4.1. Mean Engine-speed vs PMR¶
First the mean engine-speed of vehicles are compared with access-db tool, grouped by PMRs:
Both tools generate the same rough engine speeds. There is though a trend for this project to produce lower rpm’s as the PMR of the vehicle increases. But it is difficult to tell what each vehicle does isolated.
The same information is presented again but now each vehicle difference is drawn with an arrow:
It can be seen now that this project’s calculates lower engine-speeds for classes 1 & 3 but the trend is reversed for class 2.
4.5. Development team¶
- Kostis Anagnostopoulos
- Contributing Authors:
- Heinz Steven (test-data, validation and review)
- Georgios Fontaras (simulation, physics & engineering support)
- Alessandro Marotta (policy support)