9. Schemas

The JSON-schema instances or inputs & outputs of this project, rendered below, are contained in the wltp/data-schema.yaml YAML document.

9.1. Inputs& outputs of the WLTP gear-shit generator.

The vehicle attributes required for generating the WLTC velocity-profile downscaling and gear-shifts.

/data

type

object

properties

  • id

Any identifier for the object

type

integer / string

  • unladen_mass

vehicle unladen mass

The mass (kg) of the vehicle without the driver, used to decide its class, as defined in Annex-4

type

number

exclusiveMinimum

0

units

kg

tags

input

  • test_mass

The test mass of the vehicle used in all calculations, as defined in Annex 4.2.1.3.1, pg 94.

units

kg

tags

input

positiveNumber

  • v_max

maximum vehicle velocity

(OUT) The calculated maximum velocity, as defined in Annex 2-2.i.

type

number

exclusiveMinimum

0

units

km/h

  • n_vmax

engine speed for maximum vehicle velocity

(OUT) The engine speed for v_max.

type

number

exclusiveMinimum

0

units

min⁻¹

tags

input, output

  • g_vmax

gear for maximum vehicle velocity

(OUT) The gear for achieving v_max.

type

number

exclusiveMinimum

0

  • p_rated

maximum rated power

The maximum rated engine power as declared by the manufacturer.

units

kW

tags

input

positiveNumber

  • n_rated

rated engine revolutions

The rated engine revolutions at which an engine develops its maximum power. If the maximum power is developed over an engine revolutions range, it is determined by the mean of this range.

units

min⁻¹

tags

input

positiveNumber

  • n_idle

idling revolutions

The idling engine revolutions (Annex 1).

units

min⁻¹

tags

input

positiveNumber

  • n_min

Minimum engine revolutions: either a number with the minimum engine revolutions for gears > 2 when the vehicle is in motion, or an array with the exact n_min for each gear (array must have length equal to gears).

If unspecified, the minimum n for gears > 2 is determined by the following equation:

n_min = n_idle + f_n_min(=0.125) * (n_rated - n_idle)

Higher values may be used if requested by the manufacturer, by setting this one.

type

array / number

units

min⁻¹

tags

input, output

  • n_lim

(optional) maximum engine speed limit

units

min⁻¹

tags

input

positiveNumber

  • n95_low

Just an artifact of the calculation of n_max1`(`n95_high) of Annex 2-2.g, not used by the GTR (min⁻¹).

units

min⁻¹

tags

output

positiveNumber

  • n95_high

The n_max1 of Annex 2-2.g calculated from wot’s high n (min⁻¹) where 95% of power is produced.

units

min⁻¹

tags

input, output

positiveNumber

  • n_max_cycle

The n_max2 of Annex 2-2.g based on max(V) of “base cycle” (Annex 1-9.1).

units

min⁻¹

tags

input, output

positiveNumber

  • n_max_vehicle

The n_max3 of Annex 2-2.g from v_max (Annex 2-2.i).

units

min⁻¹

tags

input, output

positiveNumber

  • n2v_ratios

N-to-V ratios

An array with the gear-ratios obtained by dividing engine-revolutions

units

min⁻¹/(km/h)

tags

input

positiveNumbers

  • f0

driving resistance coefficient f0

The driving resistance coefficient f0 (Annex 4).

type

number

units

N

tags

input

  • f1

driving resistance coefficient f1

The driving resistance coefficient f1 (Annex 4).

type

number

units

N/(km/h)

tags

input

  • f2

driving resistance coefficient f2

The driving resistance coefficient f2 (Annex 4).

type

number

units

N/(km/h)²

tags

input

  • n_min_drive1

[1/min], see Annex 2-2.k, n_min for gear 1

type

number

exclusiveMinimum

0

units

min⁻¹

tags

input

  • n_min_drive2_up

[1/min], Annex 2-2.k

type

number

exclusiveMinimum

0

units

min⁻¹

tags

input

  • n_min_drive2_stopdecel

[1/min], Annex 2-2.k

type

number

exclusiveMinimum

0

units

min⁻¹

tags

input

  • n_min_drive2

[1/min], Annex 2-2.k

type

number

exclusiveMinimum

0

units

min⁻¹

tags

input

  • n_min_drive_set

[1/min], Annex 2-2.k, calculated minimum engine speed for gears > 2:

n_min_drive = n_idle + 0.125 (n_rated - n_idle)

Do not override this, its value will be ignored. Set higher values only into parameters n_min_drive_up/down.

Matlab call this CalculatedMinDriveEngineSpeedGreater2nd.

type

number

exclusiveMinimum

0

units

min⁻¹

tags

input

  • n_min_drive_up

[1/min], Annex 2-2.k

type

number

exclusiveMinimum

0

units

min⁻¹

tags

input

  • n_min_drive_up_start

[1/min], Annex 2-2.k

type

number

exclusiveMinimum

0

units

min⁻¹

tags

input

  • n_min_drive_down

[1/min], Annex 2-2.k

type

number

exclusiveMinimum

0

units

min⁻¹

tags

input

  • n_min_drive_down_start

[1/min], Annex 2-2.k

type

number

exclusiveMinimum

0

units

min⁻¹

tags

input

  • t_cold_end

see Annex 2-2.k about n_mins

type

number

minimum

0

default

0

units

s

tags

input

  • wot

Wide open throttle curves: an array/dict/dataframe holding the full load power curves for (at least) 2 columns (‘n’, ‘p’) or the normalized values (‘n_norm’, ‘p_norm’).

  • The 1st column or n is the engine revolutions in min⁻¹.

  • The 2nd column or p is the full-power load in kW.

  • The 1st column or n_norm is the normalized engine revolutions, within [0.0, 1.20]:

    n_norm = (n - n_idle) / (n_rated  - n_idle)
    
  • The 2nd column or p_norm is the normalized values of the full-power load against the p_rated, within [0, 1]:

    p_norm = p / p_rated
    

Example:

np.array([
    [ 600, 1000, ... 7000 ],
    [ 4, 10, ... 30 ]
]).T

Normalized N/P Example:

np.array([
    [ 0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120 ],
    [ 6.11, 21.97, 37.43, 51.05, 62.61, 72.49, 81.13, 88.7, 94.92, 98.99, 100., 96.28, 87.66 ]
]).T

type

object / array

  • grid_wots

A dataframe with 2-level columns for p-available (item, gear) and p-required:

  • p_avail_stable: reduced by safety-margin, but not by ASM

  • p_avail: reduced by both SM & ASM

  • p_resist: road loads power

  • p_inert: cycle power required due to accelerations

  • p_req: road loads & cycle power

  • pmr

Power/unladen-Mass ratio.

type

number

units

W/kg

  • wltc_class

The name (or index0) of the WLTC-class (found within WLTC-data/classes) as selected by the experiment.

type

integer / string

enum

class1, class2, class3a, class3b, 0, 1, 2, 3

  • resistance_coeffs_regression_curves

Regression curve factors for calculating vehicle’s resistance_coeffs when missing.

type

array

items

type

array

items

type

number

maxItems

2

minItems

2

maxItems

3

minItems

3

  • f_dsc_threshold

Downscale-factor threshold

The limit for the calculated f_dsc below which no downscaling happens.

type

number

default

0.01

tags

input, constant

  • f_dsc_decimals

Downscale-factor rounding decimals

type

number

default

3

tags

input, constant

  • driver_mass

Driver’s mass (kg)

The mass (kg) of the vehicle’s driver (Annex 1-3.2.6, p9), where:

Unladen_mass = Test_mass - driver_mass

type

number

default

75

units

kg

tags

input, constant

  • v_stopped_threshold

Velocity under which (<=) to idle gear-shift (Annex 2-3.3, p71).

type

number

default

1

units

km/h

tags

input, constant

  • f_inertial

This is the kr inertial-factor used in the 2nd part of the formula for calculating required-power (Annex 2-3.1).

type

number

default

1.03

tags

input, constant

  • f_safety_margin

Safety-margin(SM) factor for load-curve (Annex 2-3.4).

type

number

default

0.1

tags

input, constant

  • f_n_min

For each gear > 2, N :> n_min = n_idle + f_n_min * n_range (unless n_min overridden by manufacturer)

type

number

default

0.125

units

min⁻¹

tags

input

  • f_n_min_gear2

Gear-2 is invalid when N :< f_n_min_gear2 * n_idle.

type

number

default

0.9

units

min⁻¹

tags

input, constant

  • f_n_clutch_gear2

A 2-value number-array(f1, f2) controlling when to clutch gear-2:

N < n_clutch_gear2 := max(f1 * n_idle, f2 * n_range + n_idle),

unless “clutched”…

type

array

default

1.15

0.03

units

min⁻¹

tags

input, constant

  • f_dsc

The downscaling-factor as calculated by the experiment (Annex 1-8.3).

Set it to 0 to disable downscaling, (or to any other value to force it).

type

number

tags

input, output

  • f_running_threshold

Τhe velocity threshold above which the vehicle is considered as “running”, from drivability rules of Annex 2-4.

type

number

default

1

units

km/h

tags

input, constant

  • f_up_threshold

The acceleration/constant<–>deceleration threshold for n_mins_up/down (Annex 2-2.k) for the determination of the initial gear & n_mins, according to Annex 2-3.5.

type

number

default

-0.1389

units

m/s²

tags

input, constant

  • b_no_g0_downshift

A flag to suppress shifting to gear-0(idle) during downshifts.

type

boolean

tags

input

  • v_cap

A maximum velocity limit that when given and > 0, all v_dsc samples below this are clipped (Annex 1-8.4).

type

integer / null

minimum

0

default

None

units

km/h

tags

input

  • dsc_distances

Downscaled cycle distance

units

km

tags

output

positiveNumber

  • capped_distances

Capped cycle distance

units

km

tags

input, output

positiveNumber

  • compensated_distances

the cumulative distance of the compensated cycle

units

km

tags

input, output

positiveNumber

  • cycle

An inp/out dataframe matrix with 2-level columns(item, gear), and items, in addition to those of grid_wots.

properties

  • V_dsc_raw

Downscaled velocity raw

like V_dsc but not yet rounded.

units

km/h

tags

input, output

  • V_dsc

Downscaled velocity

Downscaled velocity profile by f_dsc (not capped or compensated yet).

If not given, the scale_trace pipeline produces it from downscale.calc_V_dsc_raw().

units

km/h

tags

input, output

positiveNumbers

  • V_capped

The V_dsc limited to v_cap maximum.

tags

input, output

positiveNumbers

  • V_compensated

The V_capped extended to retain the same distance (Annex 1-9).

units

km/h

tags

input, output

positiveNumbers

  • A

The Acceleration, Annex 2-3.1

type

number

units

m/s²

tags

input, output

  • initaccel

Driveability rule phase for the initial accelerating phase of a short trip.

tags

input, output

booleans

  • stopdecel

Driveability rule phase for the final decelerating phase of a short trip.

tags

input, output

booleans

  • run

Driveability rule phase for where V is above(>=) f_running_threshold, for Annex 2-4.

tags

input, output

booleans

  • stop

Driveability rule phase for where V is strictly below(<) f_running_threshold, for Annex 2-4.

tags

input, output

booleans

  • up

Driveability rule for acceleration/constant phase in Annex 2-2.k for the determination of the initial gear, according to Annex 2-3.5. for Annex 2-4.

tags

input, output

booleans

additionalProperties

True

  • wltc_data

wltc

additionalProperties

True

9.1.1. positiveInteger

type

integer

exclusiveMinimum

0

9.1.2. positiveNumber

type

number

exclusiveMinimum

0

9.1.3. positiveIntegers

type

array

items

positiveInteger

9.1.4. positiveNumbers

type

array

items

positiveNumber

9.1.5. booleans

type

array

items

type

boolean

9.2. WLTC constants & configuration data

/wltc

type

object

properties

  • classes

type

object

properties

  • class1

Class definitions

  • class2

Class definitions

  • class3a

Class definitions

  • class3b

Class definitions

additionalProperties

False

additionalProperties

False

9.2.1. WLTC class data

type

object

properties

  • pmr_limits

PMR (low, high]

Power_To_unladen-Mass ratio-limits ((low, high], W/kg) used to select classes (Annex 1, p19).

type

array

items

type

number

maxItems

2

minItems

2

  • velocity_limits

Velocity-limits ([low, high), km/h) within which (<) version-a/b from class3 is selected (Annex 1, p19).

type

array

items

type

number

maxItems

2

minItems

2

  • lengths

class part lengths

class part duration, in [sec]

type

array

items

type

integer

  • downscale

type

object

properties

  • phases

triplet (start, tip, end); start & end remain unchanged

type

array

items

positiveInteger

additionalItems

False

maxItems

3

minItems

3

  • decel_phase

type

array

items

type

integer

additionalItems

False

maxItems

2

minItems

2

  • p_max_values

type

object

properties

  • time

type

number

  • v

type

number

  • a

type

number

additionalProperties

False

  • factor_coeffs

type

array

additionalProperties

False

  • checksum

type

number

  • part_checksums

type

array

items

type

number

  • V_cycle

type

array

items

type

number

minItems

906

additionalProperties

False