- Release
- Home
- Documentation
- PyPI
- Copyright
2014 European Commission (JRC-IET)
- License
Fuefit is a python package that calculates fitted fuel-maps from measured engine data-points based on coefficients with physical meaning.
The Fuefit calculator performs the following:
- Accepts fuel-consumption engine data points as input (RPM, Power and Fuel-Consumption or equivalent quantities such as CM, PME/Torque and PMF/FC).
- Uses those points to fit the coefficients a, b, c, a2, b2, loss0, loss2 in the following formula:1
pme = (a + b × cm + c × cm2) × pmf + (a2 + b2 × cm) × pmf2 + loss0 + loss2 × cm2
- Spits-out the input engine-points according to the fitting.
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,
pandas.DataFrame
,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):
Engine-speed:
N (1/min) N_norm (1/min) : normalized against N_idle + (N_rated - N_idle) CM (m/sec) : Mean Piston speed
Work-capability:
P (kW) P_norm (kW) : normalized against P_MAX T (Nm) PME (bar)
Fuel-consumption:
FC (g/h) FC_norm (g/h) : normalized against P_MAX PMF (bar)
Assuming you have a working python-environment, open a command-shell, (in Windows use cmd.exe
BUT ensure python.exe
is in its PATH
), you can try the following commands:
- Install
$ pip install fuefit --pre $ fuefit --winmenus ## Windows only
- Cmd-line
$ fuefit --version 0.0.4-alpha.3 $ fuefit --help ... ## Change-directory into the `fuefit/test/` folder in the *sources*. $ fuefit -I FuelFit_real.csv header+=0 \ --irenames n_norm _ fc_norm \ -I engine.csv file_frmt=SERIES model_path=/engine header@=None \ --irenames \ -m /engine/fuel=petrol \ -O - model_path=/engine/fc_map_coeffs \ -m /params/plot_maps@=True
- Excel
$ fuefit --excelrun ## Windows & OS X only
- Python-code
import pandas as pd from fuefit import model, processor input_model = mdl = model.base_model() input_model.update({...}) ## See "Python Usage" below. input_model['engine_points'] = pd.read_csv('measured.csv') ## Can also read Excel, matlab, ... mdl = model.validate_model(mdl, additional_props) output_model = processor.run(input_model) print(model.resolve_jsonpointer(output_model, '/engine/fc_map_coeffs')) print(output_model['fitted_eng_points'])
Tip
The commands beginning with $
, above, imply a Unix like operating system with a POSIX shell (Linux, OS X). Although the commands are simple and easy to translate , it would be worthwile to install Cygwin to get the same environment on Windows. If you choose to do that, include also the following packages in the Cygwin's installation wizard:
* git, git-completion
* make, zip, unzip, bzip2
* openssh, curl, wget
Tip
To install python, you can try the free (as in beer) distribution Anaconda for Windows and OS X, or the totally free WinPython distribution, but only for Windows:
- For Anaconda you may need to install project's dependencies manually (see
setup.py
) usingconda
. The most recent version of WinPython (python-3.4) although it has just changed maintainer, it remains a higly active project, and it can even compile native libraries using an installations of Visual Studio, if available (required for instance when upgrading
numpy/scipy
,pandas
ormatplotlib
withpip
).You must also Register your WinPython installation and add your installation into
PATH
(seefaq
). To register it, go toStart menu --> All Programs --> WinPython --> WinPython ControlPanel
, and thenOptions --> Register Distribution
.
For more elaborate instructions, read the next sections.
Current runs on Python-3.3+ and it is distributed on Wheels.
Before installing it, make sure that there are no older versions left over. So run this command until you cannot find any project installed:
$ pip uninstall fuefit ## Use `pip3` if both python-2 & 3 are in PATH.
You can install the project directly from the PyPi repo_ the "standard" way, by typing the pip
in the console:
$ pip install fuefit
- If you want to install a pre-release version (the version-string is not plain numbers, but ends with
alpha
,beta.2
or something else), use additionally--pre
. - If you want to upgrade an existing instalation along with all its dependencies, add also
--upgrade
(or-U
equivalently), but then the build might take some considerable time to finish. Also there is the possibility the upgraded libraries might break existing programs(!) so use it with caution, or from within a virtualenv (isolated Python environment)_. To install an older version issue the console command:
$ pip install fuefit=1.1.1 ## Use `--pre` if version-string has a build-suffix.
- To install it for different Python environments, repeat the procedure using the appropriate
python.exe
interpreter for each environment. Tip
To debug installation problems, you can export a non-empty
DISTUTILS_DEBUG
and distutils will print detailed information about what it is doing and/or print the whole command line when an external program (like a C compiler) fails.
After installation, it is important that you check which version is visible in your PATH
:
$ fuefit --version
0.0.4-alpha.3
If you download the sources you have more options for installation. There are various methods to get hold of them:
- Download a release-snapshot from github
- Download the 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
Note
This last command installs any missing dependencies inside the project-folder.
Attention
Excel-integration requires Python 3 and Windows or OS X!
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:
fuefit_excel_runner{#}.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,).
fuefit_excel_runner{#}.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 fuefit_excel_runner.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 atfuefit.excel.fuefit_excel_runner.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
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
Example code:
>> from fuefit import model, processor
>> input_model = model.base_model()
>> input_model.update({
"engine": {
"fuel": "diesel",
"p_max": 95,
"n_idle": 850,
"n_rated": 6500,
"stroke": 94.2,
"capacity": 2000,
"bore": null,
"cylinders": null,
}
})
>> model.validate_model(input_model)
>> output_model = processor.run(input_model)
>> print(output_model['engine'])
>> print(output_model['fitted_eng_maps'])
For information on the model-data, check the schema:
>> print(fuefit.model.model_schema())
You can always check the Test-cases and the fuefit.cmdline
for sample code. You explore documentation in Html by serving it with a web-server:
sad [TBD]
- Author:
- Kostis Anagnostopoulos
- Contributing Authors:
- Giorgos Fontaras for the physics, policy and admin support.
Bastiaan Zuurendonk, Maarten Steinbuch(2005): "Advanced Fuel Consumption and Emission Modeling using Willans line scaling techniques for engines", Technische Universiteit Eindhoven, 2005, Department Mechanical Engineering, Dynamics and Control Technology Group, http://alexandria.tue.nl/repository/books/612441.pdf↩