fuefit 0.0.6-alpha.1

Overview

The Fuefit calculator performs the following:

1. Accepts fuel-consumption engine data points as input (RPM, Power and Fuel-Consumption or equivalent quantities such as CM, PME/Torque and PMF/FC).

2. Uses those points to fit the following coefficients:

   \begin{equation*} a, b, c, a2, b2, loss0, loss2 \end{equation*}

   using the following formula:[1]

   \begin{equation*} \mathbf{pme} = (a + b\times{\mathbf{cm}} + c\times{\mathbf{cm^2}})\times{\mathbf{pmf}} + (a2 + b2\times{\mathbf{cm}})\times{\mathbf{pmf^2}} + loss0 + loss2\times{\mathbf{cm^2}} \end{equation*}

3. Spits-out the input engine-points according to the fitting, and optionally plots a mesh (grid) with the engine-map.

An “execution” or a “run” of a calculation along with the most important pieces of data are depicted in the following diagram:

              .----------------------------.                    .-----------------------------.
             /        Input-Model         /                    /        Output-Model         /
            /----------------------------/                    /-----------------------------/
           / +--engine                  /                    / +--engine                   /
          /  |  +--...                 /                    /  |  +--fc_map_coeffs        /
         /   +--params                /  ____________      /   +--measured_eng_points    /
        /    |  +--...               /  |            |    /    |    n   p  fc  pme  ... /
       /     +--measured_eng_points /==>| Calculator |==>/     |  ... ... ...  ...     /
      /          n    p    fc      /    |____________|  /      +--fitted_eng_points   /
     /          --  ----  ---     /                    /       |    n    p   fc      /
    /            0   0.0    0    /                    /        |  ...  ...  ...     /
   /           600  42.5   25   /                    /         +--mesh_eng_points  /
  /           ...    ...  ...  /                    /               n    p   fc   /
 /                            /                    /              ...  ...  ...  /
'----------------------------'                    '-----------------------------'

The Input & Output Model are trees of strings and numbers, assembled with:

• sequences,

• dictionaries,

• class(pandas.DataFrame),

• class(pandas.Series), and

• URI-references to other model-trees (TODO).

Apart from various engine-characteristics under /engine the table-columns such as capacity and p_rated, the table under /measured_eng_points must contain at least one column from each of the following categories (column-headers are case-insensitive):

1. Engine-speed:

   N        (1/min)
   N_norm   (1/min)    : normalized against N_idle + (N_rated - N_idle)
   CM       (m/sec)    : Mean Piston speed

2. Work-capability:

   P        (kW)
   P_norm   (kW)       : normalized against P_MAX
   T        (Nm)
   PME      (bar)

3. Fuel-consumption:

   FC       (g/h)
   FC_norm  (g/h)      : normalized against P_MAX
   PMF      (bar)

Quick-start

The program runs on Python-3.3+ with numpy/scipy, pandas and win32 native-libraries installed.

On Windows/OS X, it is recommended to use one of the following “scientific” python-distributions, as they already include the native libraries and can install without administrative priviledges:

• WinPython (Windows only),

• Anaconda,

• Canopy,

Assuming you have a working python-environment, open a command-shell, (in Windows use program(cmd.exe) BUT ensure program(python.exe) is in its envvar(PATH)), you can try the following commands:

Install:

$ pip install fuefit
$ fuefit --winmenus                         ## Adds StartMenu-items, Windows only.

See: doc(install)

Cmd-line:

$ fuefit --version
0.0.6-alpha.1

$ fuefit --help
...

## Change-directory into the `fuefit/test/` folder in the  *sources*.
$ fuefit -I FuelFit_real.csv header+=0 \
    -I ./FuelFit.xlsx sheetname+=0 header@=None names:='["p","n","fc"]' \
    -I ./engine.csv file_frmt=SERIES model_path=/engine header@=None \
    -m /engine/fuel=petrol \
    -m /params/plot_maps@=True \
    -O full_results_model.json \
    -O fit_coeffs.csv model_path=/engine/fc_map_coeffs   index?=false \
    -O t1.csv model_path=/measured_eng_points   index?=false \
    -O t2.csv model_path=/mesh_eng_points       index?=false \

See: cmd-line-usage

Excel:

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

See: excel-usage

Python-code:

code-block:

>>> import pandas as pd
>>> from fuefit import datamodel, processor, test

>>> inp_model = datamodel.base_model()
>>> inp_model.update({...})                                     ## See "Python Usage" below.        # doctest: +SKIP
>>> inp_model['engine_points'] = pd.read_csv('measured.csv')    ## Pandas can read Excel, matlab, ... # doctest: +SKIP
>>> datamodel.set_jsonpointer(inp_model, '/params/plot_maps', True)

>>> datamodel.validade_model(inp_model, additional_properties=False)            # doctest: +SKIP

>>> out_model = processor.run(inp_model)                                        # doctest: +SKIP

>>> print(datamodel.resolve_jsonpointer(out_model, '/engine/fc_map_coeffs'))    # doctest: +SKIP
a            164.110667
b           7051.867419
c          63015.519469
a2             0.121139
b2          -493.301306
loss0      -1637.894603
loss2   -1047463.140758
dtype: float64

See: python-usage

Installing from sources

If you download the sources you have more options for installation. There are various methods to get hold of them:

• Download and extract a release-snapshot from github.

• Download and extract a sdist source distribution from PyPi repo.

• Clone the git-repository at github. Assuming you have a working installation of git you can fetch and install the latest version of the project with the following series of commands:

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

When working with sources, you need to have installed all libraries that the project depends on. Particularly for the latest WinPython environments (Windows / OS X) you can install the necessary dependencies with:

$ pip install -r WinPython_requirements.txt -U .

The previous command installs a “snapshot” of the project as it is found in the sources. If you wish to link the project’s sources with your python environment, install the project in development mode:

$ python setup.py develop

Anaconda install

The installation to Anaconda (ie OS X) works without any differences from the pip procedure described so far.

To install it on miniconda environment, you need to install first the project’s native dependencies (numpy/scipy), so you need to download the sources (see above). Then open a bash-shell inside them and type the following commands:

$ coda install `cat miniconda_requirements.txt`
$ pip install lmfit             ## Workaround lmfit-py#149
$ python setup.py install
$ fuefit --version
0.0.6-alpha.1

Excel usage

In Windows and OS X you may utilize the excellent xlwings library to use Excel files for providing input and output to the processor.

To create the necessary template-files in your current-directory you should enter:

$ fuefit --excel

You could type instead fuefit --excel {file_path} to specify a different destination path.

In windows/OS X you can type fuefit --excelrun and the files will be created in your home-directory and the excel will open them in one-shot.

All the above commands creates two files:

file(FuefitExcelRunner{#}.xlsm)

The python-enabled excel-file where input and output data are written, as seen in the screenshot below:

After opening it the first tie, enable the macros on the workbook, select the python-code at the left and click the Run Selection as Pyhon button; one sheet per vehicle should be created.

The excel-file contains additionally appropriate VBA modules allowing you to invoke Python code present in selected cells with a click of a button, and python-functions declared in the python-script, below, using the mypy namespace.

To add more input-columns, you need to set as column Headers the json-pointers path of the desired model item (see python-usage below,).

file(FuefitExcelRunner{#}.py)

Python functions used by the above xls-file for running a batch of experiments.

The particular functions included reads multiple vehicles from the input table with various vehicle characteristics and/or experiment coefficients, and then it adds a new worksheet containing the cycle-run of each vehicle . Of course you can edit it to further fit your needs.

Some general notes regarding the python-code from excel-cells:

• An elaborate syntax to reference excel cells, rows, columns or tables from python code, and to read them as class(pandas.DataFrame) is utilized by the Excel . Read its syntax at func(~fuefit.excel.FuefitExcelRunner.resolve_excel_ref).

• On each invocation, the predefined VBA module pandalon executes a dynamically generated python-script file in the same folder where the excel-file resides, which, among others, imports the “sister” python-script file. You can read & modify the sister python-script to import libraries such as ‘numpy’ and ‘pandas’, or pre-define utility python functions.

• The name of the sister python-script is automatically calculated from the name of the Excel-file, and it must be valid as a python module-name. Therefore: * Do not use non-alphanumeric characters such as spaces(` ), dashes(-) and dots(.`) on the Excel-file. * If you rename the excel-file, rename also the python-file, or add this python import <old_py_file> as mypy`

• On errors, a log-file is written in the same folder where the excel-file resides, for as long as the message-box is visible, and it is deleted automatically after you click ‘ok’!

• Read http://docs.xlwings.org/quickstart.html

Cmd-line usage

Example command:

fuefit -v\
  -I fuefit/test/FuelFit.xlsx sheetname+=0 header@=None names:='["p","rpm","fc"]' \
  -I fuefit/test/engine.csv file_frmt=SERIES model_path=/engine header@=None \
  -m /engine/fuel=petrol \
  -O ~t2.csv model_path=/fitted_eng_points    index?=false \
  -O ~t2.csv model_path=/mesh_eng_points      index?=false \
  -O ~t.csv model_path= -m /params/plot_maps@=True

Python usage

The most powerful way to interact with the project is through a python REPL (Read-Eval-Print Loop). So fire-up a command(python) or command(ipython) shell and first try to import the project just to check its version:

code-block:

>>> import fuefit

>>> fuefit.__version__                ## Check version once more.
'0.0.6-alpha.1'

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

If the version was as expected, take the base-model and extend it with your engine-data (strings and numbers):

>>> from fuefit import datamodel, processor

>>> inp_model = datamodel.base_model()
>>> inp_model.update({
...     "engine": {
...         "fuel":     "diesel",
...         "p_max":    95,
...         "n_idle":   850,
...         "n_rated":  6500,
...         "stroke":   94.2,
...         "capacity": 2000,
...         "bore":     None,       ##You do not have to include these,
...         "cylinders": None,      ##  they are just for displaying some more engine properties.
...     }
... })

>>> import pandas as pd
>>> df = pd.read_excel('fuefit/test/FuelFit.xlsx', 0, header=None, names=["n","p","fc"])
>>> inp_model['measured_eng_points'] = df

For information on the accepted model-data, check both its JSON-schema at func(~fuefit.datamodel.model_schema), and the func(~fuefit.datamodel.base_model):

Next you have to validate it against its JSON-schema:

>>> datamodel.validate_model(inp_model, additional_properties=False)

If validation is successful, you may then feed this model-tree to the mod(fuefit.processor), to get back the results:

>>> out_model = processor.run(inp_model)

>>> print(datamodel.resolve_jsonpointer(out_model, '/engine/fc_map_coeffs'))
a            164.110667
b           7051.867419
c          63015.519469
a2             0.121139
b2          -493.301306
loss0      -1637.894603
loss2   -1047463.140758
dtype: float64

>>> print(out_model['fitted_eng_points'].shape)
(262, 11)

Sources & Dependencies

To get involved with development, you need a POSIX environment to fully build it (Linux, OSX, or Cygwin on Windows).

Development team

• Author:

  • Kostis Anagnostopoulos

• Contributing Authors:

  • Giorgos Fontaras for the testing, physics, policy and admin support.