3. Code reference

The core of the simulator is composed from the following modules:

experiment The core that accepts a vehicle-model and wltc-classes, runs the simulation and updates the model with results (downscaled velocity & gears-profile).
model The hierarchical data and their schema for the WLTC calculator (defaults, WLTC-data) used by the Model and Experiments classes.

Among the various tests, those involved with data and divergence from existing tool are:

experiment_WholeVehicleTests Tests check top-level functionality.
wltp_db_tests Compares the results of a batch of wltp_db vehicles against Heinz’s tool.
experiment_SampleVehicleTests Compares the results of synthetic vehicles from JRC against Heinz’s tool.

The following scripts in the sources maybe used to preprocess various wltc data:

  • util/preprocheinz.py
  • util/printwltcclass.py
  • util/csvcolumns8to2.py

3.1. Module: wltp.experiment

The core that accepts a vehicle-model and wltc-classes, runs the simulation and updates the model with results (downscaled velocity & gears-profile).

Attention

The documentation of this core module has several issues and needs work.

ALL_CAPITALS variable denote vectors, usually over the velocity-profile (the cycle), for instance, GEARS is like that:

 t:||: 0  1  2  3
---+-------------
g1:|[[ 1, 1, 1, 1, ... 1, 1
g2:|   2, 2, 2, 2, ... 2, 2
g3:|   3, 3, 3, 3, ... 3, 3
g4 |   4, 4, 4, 4, ... 4, 4 ]]

3.1.1. Vectors

V: floats (#cycle_steps)
The wltp-class velocity profile.
GEARS: integers (#gears X #cycle_steps)
One row for each gear (starting with 1 to #gears).
GEARS_YES: boolean (#gears X #cycle_steps)
One row per gear having True wherever gear is possible for each step.
N_GEARS: floats (#gears X #cycle_steps)
One row per gear with the Engine-revolutions required to follow the V-profile (unfeasable revs included), produced by multiplying V * gear-rations.

See also

model for in/out schemas

since:1 Jan 2014
class wltp.experiment.Experiment(*models, skip_model_validation=False, validate_wltc=False)[source]

Runs the vehicle and cycle data describing a WLTC experiment.

See wltp.experiment for documentation.

__init__(*models, skip_model_validation=False, validate_wltc=False)[source]

model is a tree (formed by dicts & lists) holding the experiment data.

skip_model_validation when true, does not validate the model.

run(overridde_cycle=False)[source]

Invokes the main-calculations and extracts/update Model values!

@see: Annex 2, p 70

wltp.experiment.applyDriveabilityRules(V, A, GEARS, CLUTCH, ngears, driveability_issues)[source]

@note: Modifies GEARS. @see: Annex 2-4, p 72

wltp.experiment.calcDownscaleFactor(P_REQ, p_max_values, downsc_coeffs, dsc_v_split, p_rated, v_max, f_downscale_threshold)[source]

Check if downscaling required, and apply it.

Returns:(float) the factor

@see: Annex 1-7, p 68

wltp.experiment.calcEngineRevs_required(V, gear_ratios, n_idle, v_stopped_threshold)[source]

Calculates the required engine-revolutions to achieve target-velocity for all gears.

Returns:array: N_GEARS: a (#gears X #velocity) float-array, eg. [3, 150] –> gear(3), time(150)
Return type:array: GEARS: a (#gears X #velocity) int-array, eg. [3, 150] –> gear(3), time(150)

@see: Annex 2-3.2, p 71

wltp.experiment.calcPower_available(N_GEARS, n_idle, n_rated, p_rated, load_curve, p_safety_margin)[source]

@see: Annex 2-3.2, p 72

wltp.experiment.calcPower_required(V, A, test_mass, f0, f1, f2, f_inertial)[source]

@see: Annex 2-3.1, p 71

wltp.experiment.decideClass(class_limits, class3_velocity_split, mass, p_rated, v_max)[source]

@see: Annex 1, p 19

wltp.experiment.downscaleCycle(V, f_downscale, phases)[source]

Downscale just by scaling the 2 phases demarked by the 3 time-points with different factors, no recursion as implied by the specs.

@see: Annex 1-7, p 64-68

wltp.experiment.gearsregex(gearspattern)[source]
Parameters:gearspattern

regular-expression or substitution that escapes decimal-bytes written as: \g\d+ with adding +128, eg:

\g124|\g7 --> unicode(128+124=252)|unicode(128+7=135)
wltp.experiment.possibleGears_byEngineRevs(V, A, N_GEARS, ngears, n_idle, n_min_drive, n_clutch_gear2, n_min_gear2, n_max, v_stopped_threshold, driveability_issues)[source]

Calculates the engine-revolutions limits for all gears and returns for which they are accepted.

My interpratation for Gear2 n_min limit:

                      _____________                ______________
                  ///INVALID///|   CLUTCHED   |  GEAR-2-OK
EngineRevs(N): 0-----------------------+---------------------------->
for Gear-2                     |       |      +--> n_clutch_gear2   := n_idle + MAX(
                               |       |                                      0.15% * n_idle,
                               |       |                                      3%    * n_range)
                               |       +---------> n_idle
                               +-----------------> n_min_gear2      := 90% * n_idle
Returns:GEARS_YES: possibibilty for all the gears on each cycle-step (eg: [0, 10] == True –> gear(1) is possible for t=10)
Return type:list(booleans, nGears x CycleSteps)

@see: Annex 2-3.2, p 71

wltp.experiment.possibleGears_byPower(N_GEARS, P_REQ, n_idle, n_rated, p_rated, load_curve, p_safety_margin, driveability_issues)[source]

@see: Annex 2-3.1 & 3.3, p 71 & 72

wltp.experiment.rule_a(bV, GEARS, CLUTCH, driveability_issues, re_zeros)[source]

Rule (a): Clutch & set to 1st-gear before accelerating from standstill.

Implemented with a regex, outside rules-loop: Also ensures gear-0 always followed by gear-1.

NOTE: Rule(A) not inside x2 loop, and last to run.

wltp.experiment.rule_c2(bV, A, GEARS, CLUTCH, driveability_issues, re_zeros)[source]

Rule (c2): Skip 1st-gear while decelerating to standstill.

Implemented with a regex, outside rules-loop: Search for zeros in _reversed_ V & GEAR profiles, for as long Accel is negative. NOTE: Rule(c2) is the last rule to run.

wltp.experiment.runCycle(V, A, P_REQ, gear_ratios, n_idle, n_min_drive, n_rated, p_rated, load_curve, params)[source]

Calculates gears, clutch and actual-velocity for the cycle (V). Initial calculations happen on engine_revs for all gears, for all time-steps of the cycle (N_GEARS array). Driveability-rules are applied afterwards on the selected gear-sequence, for all steps.

Parameters:
  • V – the cycle, the velocity profile
  • A – acceleration of the cycle (diff over V) in m/sec^2
Returns:

CLUTCH: a (1 X #velocity) bool-array, eg. [3, 150] –> gear(3), time(150)

Return type:

array

wltp.experiment.step_rule_b1(t, pg, g, V, A, GEARS, driveability_issues)[source]

Rule (b1): Do not skip gears while accelerating.

wltp.experiment.step_rule_b2(t, pg, g, V, A, GEARS, driveability_issues)[source]

Rule (b2): Hold gears for at least 3sec when accelerating.

wltp.experiment.step_rule_c1(t, pg, g, V, A, GEARS, driveability_issues)[source]

Rule (c1): Skip gears <3sec when decelerating.

wltp.experiment.step_rule_d(t, pg, g, V, A, GEARS, driveability_issues)[source]

Rule (d): Cancel shifts after peak velocity.

wltp.experiment.step_rule_e(t, pg, g, V, A, GEARS, driveability_issues)[source]

Rule (e): Cancel shifts lasting 5secs or less.

wltp.experiment.step_rule_f(t, pg, g, V, A, GEARS, driveability_issues)[source]

Rule(f): Cancel 1sec downshifts (under certain circumstances).

wltp.experiment.step_rule_g(t, pg, g, V, A, GEARS, driveability_issues)[source]

Rule(g): Cancel upshift during acceleration if later downshifted for at least 2sec.

3.2. Module: wltp.model

The hierarchical data and their schema for the WLTC calculator (defaults, WLTC-data) used by the Model and Experiments classes.

Attention

The documentation of this core module has several issues and needs work.

wltp.model.merge(a, b, path=[])[source]

‘merges b into a

wltp.model.model_base()[source]

The base model for running a WLTC experiment.

It contains some default values for the experiment (ie the default ‘full-load-curve’ for the vehicles). But note that it this model is not valid - you need to iverride its attributes.

:return :json_tree: with the default values for the experiment.

wltp.model.model_schema()[source]
Returns:The json-schema(dict) for input/output of the WLTC experiment.
wltp.model.wltc_data()[source]

The WLTC-data required to run an experiment (the class-cycles and their attributes)..

:return :json_tree:

wltp.model.wltc_schema()[source]

The json-schema for the WLTC-data required to run a WLTC experiment.

:return :dict: