updating user manual, adding missing files

Documentation/User Manual/1-user-interface/F_VEH-Editor.md

@@ -166,9 +166,10 @@ However, it is possible that more than one electric machine is used at a certain
 
 The *Loss map EM ADC* can be used to consider the losses of a transmission step between drivetrain and electric machine or to consider losses of a summation gear. The loss map has the same format as for all other transmission components (see [Transmission Loss Map (.vtlm)](#transmission-loss-map-.vtlm)). For simplicity or if no such transmission step is used it is possible to enter the efficiency directly (i.e., "1" if no transmission step is used).
 
-In case of a P2.5 configuration (the electric motor is connected to an internal shaft of the tranmission) the transmission ratio for every single gear of the transmission has to be specified in the list to the right of the electric motor parameters.
+In case of a P2.5 configuration (the electric motor is connected to an internal shaft of the tranmission) the transmission ratio for every single gear of the transmission has to be specified in the list to the right of the electric motor parameters. The ratio is defeined as $n_\textrm{GBX,in} / n_\textrm{EM}$ in case of EM without additional ADC or $n_\textrm{GBX,in} / n_\textrm{ADC,out}$ in case of EM with additional ADC.
 
-For the electric energy storage multiple battery packs can be configured either in series or in parallel and the initial state of charge of the whole battery system can be defined.  For every entry of a battery pack the number of packs (count) in series and a stream identifier need to be specified. Battery packs on the same stream are connected in series (e.g., two different battery packs on stream number 1 are in series) while all streams are then connected in parallel (see [Battery Model](#foo) for details). This is only supported for batteries and **not** for SuperCaps.
+
+For the electric energy storage multiple battery packs can be configured either in series or in parallel and the initial state of charge of the whole battery system can be defined.  For every entry of a battery pack the number of packs (count) in series and a stream identifier need to be specified. Battery packs on the same stream are connected in series (e.g., two different battery packs on stream number 1 are in series) while all streams are then connected in parallel (see [Battery Model](#ress) for details). This is only supported for batteries and **not** for SuperCaps.
 
 **Double-click** an entry to edit.
 
@@ -185,14 +186,14 @@ In the REESS Dialog the battery file itself and how it is connected to the elect
 
 ![](pics/VehicleForm_TorqueLimits.png)
 
-On this tab different torque limits can be applied at the vehicle level. 
+On this tab different torque limits can be applied at the vehicle level. For details which limits are applicable and who the limits are applied in the simulation [see here](#torque-and-speed-limitations).
 
 First, the maximum torque of the ICE may be limited for certain gears (see [Engine Torque Limitations](#torque-and-speed-limitations)).
 In case that the gearbox' maximum torque is lower than the engine's maximum torque or to model certain features like Top-Torque (where in the highest gear more torque is available) it is possible to limit the engine's maximum torque depending on the engaged gear. 
 
 Next, the maximum available torque for the electric machine can be reduced at the vehicle level, both for propulsion and recuperation. The input file is the same as the maximum drive and maximum recuperation curve (see [Electric Motor Max Torque File](#electric-motor-max-torque-file-.vemp))
 
-Last, the overall propulsion of the vehicle (i.e., electric motor plus combustion engine) can be limited. The "Propulsion Torque Limit" curve limits the maximum effective torque at the gearbox input shaft over the input speed. This curve is added to the combustion engine's maximum torque curve (only positive values are allowed!). For details on the file format see [Vehicle Boosting Limits](#vehcle-boosing-limits-.vemp). The propulsion torque limit has to be provided from 0 rpm to the maximum speed of the combustion engine. In case of P3 or P4 configuration, the torque at the gearbox input shaft is calculated assuming that the electric motor does not contribute to propelling the vehicle, considering the increased losses in the transmission components inbetween. For P2.5 powertrain configurations no special calculations are necessary as this architecture is internally anyhow modelled as P2 architecture.
+Last, the overall propulsion of the vehicle (i.e., HEV Px, electric motor plus combustion engine) can be limited. The "Propulsion Torque Limit" curve limits the maximum effective torque at the gearbox input shaft over the input speed. This curve is added to the combustion engine's maximum torque curve (only positive values are allowed!). For details on the file format see [Vehicle Boosting Limits](#vehcle-boosing-limits-.vemp). The propulsion torque limit has to be provided from 0 rpm to the maximum speed of the combustion engine. In case of P3 or P4 configuration, the torque at the gearbox input shaft is calculated assuming that the electric motor does not contribute to propelling the vehicle, considering the increased losses in the transmission components inbetween. For P2.5 powertrain configurations no special calculations are necessary as this architecture is internally anyhow modelled as P2 architecture.
 
 ##Vehicle Editor -- ADAS Tab
 
@@ -200,6 +201,21 @@ Last, the overall propulsion of the vehicle (i.e., electric motor plus combustio
 
 On the ADAS tab, the advanced driver assistant systems present in the vehicle can be selected.  See [ADAS - Engine Stop/Start](#advanced-driver-assistant-systems-engine-stopstart), [ADAS - EcoRoll](#advanced-driver-assistant-systems-eco-roll), and [ADAS - Predictive Cruise Control](#advanced-driver-assistant-systems-predictive-cruise-control)
 
+The following table describes which ADAS technology can be used and is supported for different powertrain architectures (X: supported, O: optional, -: not supported):
+
+| ADAS Technology \ Powertrain Architecture  | Conventional   | HEV   | PEV   |
+| ------------------------------------------ | -------------- | ----- | ----- |
+| Engine Stop/Start                          | X              | X     | -     |
+| EcoRoll Without Engine Stop                | X              | -     | -     |
+| EcoRoll with Engine Stop                   | X              | -     | -     |
+| Predictive Cruise Control                  | X              | X     | X     |
+| APT Gearbox EcoRoll Release Lockup Clutch  | O              | -     | -     |
+
+* Engine Stop/Start not allowed for PEV
+* EcoRoll for HEV always with ICE off
+* For PEV no clutch for disconnecting the EM present, thus no EcoRoll foreseen (very low drag of EM in any case)
+* Inputs for EcoRoll possible in GUI, but no effect in simulation
+
 
 ##Vehicle Editor -- PTO Tab
 

Documentation/User Manual/1-user-interface/H1_HybridStrategyParams-Editor.md

+##Hybrid Strategy Parameters Editor
+
+
+![](pics/HybridStrategyParams.png)
+
+###Description
+
+
+The [Hybrid Strategy Parameters File (.vhctl)](#hybrid-strategy-parameters-file-.vhctl) defines all parameters used by the [Hybrid Control Strategy](#hybrid-control-strategy) to evaluate the best option for splitting the demanded torque between electric motor and combustion engine.
+
+###Strategy Parameters
+
+The hybrid control strategy evaluates different allocations of torque to the electric motor and different gears and calculates the following cost function:
+
+$C = \sum_{i \in  \textrm{Fuels}}{FC_{i} \cdot NCV_{i} \cdot dt} + f_{\textrm{equiv}} \cdot (P_\textrm{Bat} \cdot dt + C_{\textrm{Pen1}}) \cdot f_{SoC} + C_{\textrm{Pen2}}$
+
+$f_\textrm{SoC} = 1 - \left(\frac{\textrm{SoC} - \textrm{TargetSoC}}{0.5 \cdot (\textrm{SoC}_\textrm{max} - \textrm{SoC}_{min}}  \right)^e + C_\textrm{SoC}$
+
+The parameters for the cost function can be defined in the hybrid strategy file.
+
+Evquivalence Factor Discharge
+:   $f_{\textrm{equiv}}$ in case the battery is discharged
+
+Evquivalence Factor Charge
+:   $f_{\textrm{equiv}}$ in case the battery is charged
+
+Min SoC
+:   $\textrm{SoC}_\textrm{min}$
+
+Max SoC
+:   $\textrm{SoC}_\textrm{max}$
+
+Target SoC
+:   $\textrm{TargetSoC}$
+
+Min ICE On Time
+:   In case the ICE was turned on, it cannot be turned of for this period of time
+
+Aux Buffer Time 
+:   In case electric auxiliaries are connected to the high-voltage system, reserve a certain amount of energy in the battery to supply the auxiliaries for this period of time.
+
+Aux Buffer Charge Time
+:   In case electric auxiliaries are connected to the high-voltage system and the reserved energy for the auxiliaries is used, re-charge the "auxiliaries buffer" in within this period of time.
+
+ICE Start penalty factor
+:   Penalty added to the cost function in case the ICE needs to be turned on
+
+Cost Factor SoC Exponent
+:   Exponent $e$ in the cost function
+

Documentation/User Manual/3-simulation-models/ADAS_EcoRoll.md

@@ -184,8 +184,9 @@ If the vehicle enters a potential PCC section, the following calculations are pe
 1. Current vehicle position: $x$
 2. Position in the cycle where the PCC event shall be finished: $x_{end} = min(x + d_{preview}, x_{end, max})$
 3. Estimation of coasting resistance force:  
-$F_{coast}(x) = \frac{P_{roll}(x) + P_{aero}(x, v_{target}) + P_{ice, drag}}{v_{target}}$  
-$P_{ice, drag}$ is set to 0 in case the vehicle is equipped with eco-roll
+$F_{coast}(x) = \frac{P_{roll}(x) + P_{aero}(x, v_{target}) + P_{ice, drag} + P_{em, drag}}{v_{target}}$  
+$P_{ice, drag}$ is set to 0 in case the vehicle is equipped with eco-roll and pure electric vehicles.
+$P_{em,drag}$ is set to 0 for conventional vehicles.
 4. Energy demand/gain for coasting from the vehicle's current position to the point with the minimum velocity $x_{v_{low}}$:  
 $E_{coast, v_{low}} = F_{coast} \cdot (x_{v_{low}} - x)$
 5. Energy demand/gain for coasting from the vehicle's current position to the end of the PCC event $x_{end}$:  
@@ -197,9 +198,13 @@ $E(x_{end}) = m \cdot g \cdot h(x_{end}) + \frac{m \cdot v_{target}(x_{end})^2}{
 
 **PCC State Diagram**
 
-The following state diagram depicts when a PCC event is activated during the simulation.
+The following state diagram depicts when a PCC event is activated during the simulation for conventional vehicles.
 
-![](pics/PredictiveCruiseControlActivation.svg)
+![](pics/PredictiveCruiseControl_Conventional.png)
+
+The following state diagram depicts the activation of a PCC event during the simulation for xEV vehicles.
+
+![](pics/PredictiveCruiseControl_xEV.png)
 
 The fuel consumption of vehicles equipped with PCC option 1 & 2 and eco-roll with engine stop/start will be corrected for engine stop/start as described in [engine stop/start correction](#engine-fuel-consumption-correction).
 

Documentation/User Manual/3-simulation-models/Electric_Motor.md

@@ -8,7 +8,7 @@ The electric motor is modeled by basically 4 map files:
  - Drag curve (i.e., the motor is not energized) over motor speed
  - Continuous torque ($T_\textrm{cont}$)
  - Engine speed for continuous torqe ($n_\textrm{T,cont}$)
- - Overload torque ($T_\textrm{ovl})
+ - Overload torque ($T_\textrm{ovl}$)
  - Engine speed for overload torque  ($n_\textrm{T,ovl}$)
  - Maximum overload time ($t_\textrm{ovl}$)
 
@@ -63,7 +63,7 @@ $P_\textrm{el}(n_\textrm{em}, T_\textrm{em}) = \textrm{Delaunay}_\textrm{EM-Map}
 
 The electric machine can be overloaded for a certain period. In addition to the maximum drive and generation torque (which already is in overload condition) the mechanical power the electric machine can generate is required.
 
-The basic principal of the thermal de-rating is as follows: based on the continuous power and the angular velocity for the continuous power as well as the maximum overload time a thermal energy buffer is calculated. During the simulation the difference between the current losses in the electric machine and the losses at the continuous power operating point are integrated over time. If this value reaches the capacity of the thermal energy buffer the electric machine can only deliver the specified continuous power until the thermal energy buffer goes below a certain.
+The basic principal of the thermal de-rating is as follows: based on the continuous power and the angular velocity for the continuous power as well as the maximum overload time a thermal energy buffer is calculated. During the simulation the difference between the current losses in the electric machine and the losses at the continuous power operating point are integrated over time. If this value reaches the capacity of the thermal energy buffer the electric machine can only deliver the specified continuous power until the thermal energy buffer goes below a certain threshold.
 
 
 $E_\textrm{th,buf} = (P_\textrm{loss,ovl} - P_\textrm{loss,cont}) \cdot t_\textrm{ovl}$
@@ -79,5 +79,5 @@ $E_{\textrm{ovl,} i + 1} = E_{\textrm{ovl,} i} + (P_\textrm{loss, i} - P_\textrm
 $P_\textrm{loss, i} = T_\textrm{em, mech} \cdot n_\textrm{em} - P_\textrm{map, el}(T_\textrm{em, mech}, n_\textrm{em})$
 
 
-If $E_\textrm{ovl, i}$ reaches the overload capacity $E_\textrm{th,buf}$ the power of the electric machine is limited to the continuous power until $E_\textrm{ovl,i}$ goes below the overload capacity multiplied by a certain factor. Then the maximum torque is available again.
+If $E_\textrm{ovl, i}$ reaches the overload capacity $E_\textrm{th,buf}$ the power of the electric machine is limited to the continuous power until $E_\textrm{ovl,i}$ goes below the overload capacity multiplied by the thermal overload recovery factor. Then the maximum torque is available again.
 

Documentation/User Manual/3-simulation-models/Electric_Storage.md

@@ -23,7 +23,7 @@ $I_\textrm{disch,max} = \frac{U(\textrm{SoC})}{4 * R_i(\textrm{SoC})}$
 
 ####Time-dependent Internal Resistance
 
-If the internal resistance shall is provided for different pulse durations, the actual internal resistance is interpolated between the provided resistance values with the current pulse duration. No extrapolation is applied. For pulses below Ri_2, Ri_2 is applied, for pulse durations longer then Ri_20 (or Ri_120 if provided) this value is used. The pulse duration is reset every time the current changes its sign.
+If the internal resistance is provided for different pulse durations, the actual internal resistance is interpolated between the provided resistance values with the current pulse duration. No extrapolation is applied. For pulses below Ri_2, Ri_2 is applied, for pulse durations longer then Ri_20 (or Ri_120 if provided) this value is used. The pulse duration is reset every time the current changes its sign.
 
 ###Modular Battery System
 

Documentation/User Manual/3-simulation-models/Engine_Speed_Torque_limitations.md

@@ -51,7 +51,9 @@ The electric motor's maximum drive and maximum recuperation curve can be overrid
 
 For hybrid electric vehicles the electric machine may provide additional torque to the powertrain and thus cause higher accelerations than a conventional vehicle. To limit such boosting by the electric motor. 
 
-The input is the additional torque the electric motor is allowed to boost in addition to the ICE over ICE speed. Note: this boosting torque has to be provided from 0 rpm up to the max. ICE speed. The angular speed refers to the gearbox input shaft.
+The input is the additional torque the electric motor is allowed to boost in addition to the ICE over ICE speed.
+
+*Note:* this boosting torque has to be provided from 0 rpm up to the max. ICE speed. The angular speed refers to the gearbox input shaft.
 
 
 ####Example 1: No boosting
@@ -64,13 +66,11 @@ If the electric motor shall not be allowed to provide additional torque beyond t
 
 ~~~
 n [rpm] , T_drive [Nm]
-0       , 300
-599     , 300
-600     , 0
+0       , 0
 2500    , 0
 ~~~
 
-For speeds below idle speed the propulsion torque limit is set to the electric motor's maximum torque so that the vehicle can drive off without the combustion engine. 
+For speeds below idle speed the full-load torque available from the ICE equals the ICE full-load torque at engine idling speed due to the modeling of the clutch behavior during vehicle starts.
 
 ####Example 2: 
 
@@ -80,9 +80,7 @@ In this example the electric motor is allowed to provide torque in addition to t
 
 ~~~
 n [rpm] , T_drive [Nm]
-0       , 300
-599     , 300
-600     , 100
+0       , 100
 2500    , 100
 ~~~
 

Documentation/User Manual/3-simulation-models/simulation-models.md

@@ -2,6 +2,7 @@
 
 In this chapter the used component models for the simulation are described.
 
+* [Supported Powertrain Architectures](#supported-powertrain-architectures)
 * [Powertrain and Components Structure](#powertrain-and-components-structure)
 * [Driver: Acceleration Limiting](#driver-acceleration-limiting)
 * [Driver: Look-Ahead Coasting](#driver-look-ahead-coasting)

Documentation/User Manual/3-simulation-models/supported_powertrain_architectures.md

+##Supported Powertrain Architectures
+
+The following xEV architectures are currently supported in VECTO. All architectures can be used together with the bus auxiliaries model in engineering mode.
+
+###Parallel Hybrid Electric Vehicle Architectures
+
+* P1 + AMT
+* P1 + APT-S/P
+* P2 + AMT
+* P2.5 + AMT
+* P2.5 + APT-S/P
+* P3 + AMT
+* P3 + APT-S/P
+* P4 + AMT
+* P4 + APT-S/P
+
+###Pure Electric Vehicle Architectures
+
+* E2 + AMT
+* E2 + APT-N
+* E3
+* E4

Documentation/User Manual/5-input-and-output-files/VBATx.md

@@ -46,7 +46,7 @@ SoC , Ri
 ~~~
 SoC , Ri-2 , Ri-10 , Ri-20
 0   , 0.04 , 0.06  , 0.08
-0   , 0.04 , 0.06  , 0.08
+100 , 0.04 , 0.06  , 0.08
 ~~~
 
 ##Battery Max Current Map (.vimax)

Documentation/User Manual/5-input-and-output-files/VHCTL.md

+##Hybrid Strategy Parameters File (.vhctl)
+
+File for the definition of the hybrid control strategy parameters in VECTO. Can be created with the [Hybrid Strategy Parameters Editor](#hybrid-strategy-parameters-editor).
+
+- File format is [JSON](#json).
+- Filetype ending is ".vhctl"
+
+**Example:**
+
+~~~
+{
+  "Header": {
+    "CreatedBy": "",
+    "Date": "2020-09-07T15:28:08.3781385Z",
+    "AppVersion": "3",
+    "FileVersion": 1
+  },
+  "Body": {
+    "EquivalenceFactor": 2.0,
+    "MinSoC": 20.0,
+    "MaxSoC": 80.0,
+    "TargetSoC": 50.0,
+    "AuxBufferTime": 5.0,
+    "AuxBufferChgTime": 5.0,
+    "MinICEOnTime": 10.0
+  }
+}
+~~~

Documentation/User Manual/files.txt

@@ -19,6 +19,7 @@
 2-calculation-modes/verification-test.md
 2-calculation-modes/engine-only.md
 3-simulation-models/simulation-models.md
+3-simulation-models/supported_powertrain_architectures.md
 3-simulation-models/powertrain.md
 3-simulation-models/Driver_AccLimit.md
 3-simulation-models/Driver_LAC.md