3. Usage¶

3.1. Excel usage¶

Attention

Excel-integration requires Python 3 and Windows or OS X!

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

To create the necessary template-files in your current-directory, type this console-command:

$ fuefit --excel

Type fuefit --excel file_path if you want 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 immediately open them.

What the above commands do is to create 2 files:

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

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.

Note

You may reverse the procedure described above and run the python-script instead:

$ python FuefitExcelRunner.py

The script will open the excel-file, run the experiments and add the new sheets, but in case any errors occur, this time you can debug them, if you had executed the script through LiClipse, or IPython!

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 pandas.DataFrame is utilized by the Excel . Read its syntax at 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

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

3.3. Python usage¶

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

>>> import fuefit

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

>>> fuefit.__file__                   ## To check where it was installed.         
/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 model_schema(), and the 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 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)

Hint

You can always check the sample code at the Test-cases and in the cmdline tool fuefit.__main__.

3.3.1. Fitting Parameterization¶

The ‘lmfit’ fitting library can be parameterized by setting/modifying various input-model properties under /params/fitting/.

In particular under /params/fitting/coeffs/ you can set a dictionary of coefficient-name –> lmfit.parameters.Parameter such as min/max/value, as defined by the lmfit library (check the default props under fuefit.datamodel.base_model() and the example columns in the ExcelRunner).