max
/
TrainRun.jl
2
1
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Add docstrings to formulary.jl for documentation

master
Max Kannenberg 2022-09-05 22:40:22 +02:00
parent 71778ac715
commit 5c5fa14f46
1 changed files with 229 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

294
src/formulary.jl
View File

@ -27,27 +27,23 @@
## } ## }
######################### #########################
#approxLevel = 6
v00 = 100/3.6 # velocity factor (in m/s) v00 = 100/3.6 # velocity factor (in m/s)
## calculate forces ## calculate forces:
#TODO: replace the ? ? ?
""" """
tractionUnitResistance(v, train) tractionUnitResistance(v, train)
Calculate the vehicle resistance for the traction unit of the `train` dependend on the velocity `v`. Calculate the vehicle resistance in N for the traction unit of the `train` dependend on the velocity `v`.
...
# Arguments # Arguments
- `v::AbstractFloat`: the current velocity in m/s. - `v::AbstractFloat`: the current velocity in m/s.
- `train::Train`: ? ? ? - `train::Train`: the struct defined in types.jl containing attributes with technical data.
...
# Examples # Examples
```julia-repl ```julia-repl
julia> tractionUnitResistance(30.0, ? ? ?) julia> tractionUnitResistance(15.0, freight_train)
? ? ? 5461.127252
``` ```
""" """
function tractionUnitResistance(v::AbstractFloat, train::Train) function tractionUnitResistance(v::AbstractFloat, train::Train)
@ -58,32 +54,52 @@ function tractionUnitResistance(v::AbstractFloat, train::Train)
m_td = train.m_td # mass on the traction unit's driving axles (in kg) m_td = train.m_td # mass on the traction unit's driving axles (in kg)
m_tc = train.m_tc # mass on the traction unit's carrying axles (in kg) m_tc = train.m_tc # mass on the traction unit's carrying axles (in kg)
F_R_tractionUnit = f_Rtd0/1000 * m_td * g + f_Rtc0/1000 * m_tc * g + f_Rt2/1000 * (m_td+m_tc) * g * ((v + Δv_air) /v00)^2 # vehicle resistance of the traction unit (in N) # /1000 because of the unit ‰ F_R_tractionUnit = f_Rtd0/1000 * m_td * g + f_Rtc0/1000 * m_tc * g + f_Rt2/1000 * (m_td+m_tc) * g * ((v + Δv_air) /v00)^2 # vehicle resistance of the traction unit (in N) # /1000 because of the unit ‰
# TODO: use forceFromCoefficient? F_R_tractionUnit = forceFromCoefficient(f_Rtd0, m_td) + forceFromCoefficient(f_Rtc0, m_tc) + forceFromCoefficient(f_Rt2, m_td+m_tc) * ((v + Δv_air) /v00)^2 # vehicle resistance of the traction unit (in N)
return F_R_tractionUnit return F_R_tractionUnit
#TODO: same variable name like in the rest of TrainRuns? return R_traction
end #function tractionUnitResistance end #function tractionUnitResistance
""" """
TODO freightWagonsResistance(v, train)
calculate and return the freight wagons' vehicle resistance dependend on the velocity
Calculate the vehicle resistance in N for the freight wagons of the `train` dependend on the velocity `v`.
# Arguments
- `v::AbstractFloat`: the current velocity in m/s.
- `train::Train`: the struct defined in types.jl containing attributes with technical data.
# Examples
```julia-repl
julia> freightWagonsResistance(15.0, freight_train)
20900.732702639998
```
""" """
function freightWagonsResistance(v::AbstractFloat, train::Train) function freightWagonsResistance(v::AbstractFloat, train::Train)
# equation is based on a combination of the equations of Strahl and Sauthoff [Wende:2003, page 153] # equation is based on the equation of Strahl [Wende:2003, page 153]
f_Rw0 = train.f_Rw0 # coefficient for basic resistance of the set of wagons (consist) (in ‰) f_Rw0 = train.f_Rw0 # coefficient for basic resistance of the set of wagons (consist) (in ‰)
f_Rw2 = train.f_Rw2 # coefficient fo the consistsr air resistance (in ‰) f_Rw2 = train.f_Rw2 # coefficient fo the consistsr air resistance (in ‰)
m_w = train.m_w # mass of the set of wagons (consist) (in kg) m_w = train.m_w # mass of the set of wagons (consist) (in kg)
F_R_wagons = m_w *g *(f_Rw0/1000 + f_Rw2/1000 * (v /v00)^2) # vehicle resistance of freight wagons (in N) with Strahl # /1000 because of the unit ‰ F_R_wagons = m_w *g *(f_Rw0/1000 + f_Rw2/1000 * (v /v00)^2) # vehicle resistance of freight wagons (in N) with Strahl # /1000 because of the unit ‰
# TODO: use forceFromCoefficient? F_R_wagons = forceFromCoefficient(f_Rw0, m_w) + ...
return F_R_wagons return F_R_wagons
end #function calcWagonsResistance end #function calcWagonsResistance
""" """
TODO passengerWagonsResistance(v, train)
calculate and return the passenger wagons' vehicle resistance dependend on the velocity
Calculate the vehicle resistance in N for the passenger wagons of the `train` dependend on the velocity `v`.
# Arguments
- `v::AbstractFloat`: the current velocity in m/s.
- `train::Train`: the struct defined in types.jl containing attributes with technical data.
# Examples
```julia-repl
julia> passengerWagonsResistance(15.0, longdistance_passenger_train)
14461.2708244928
```
""" """
function passengerWagonsResistance(v::AbstractFloat, train::Train) function passengerWagonsResistance(v::AbstractFloat, train::Train)
# equation is based on the equations of Sauthoff [Wende:2003, page 153] # equation is based on the equations of Sauthoff [Wende:2003, page 153]
@ -94,129 +110,277 @@ function passengerWagonsResistance(v::AbstractFloat, train::Train)
F_R_wagons = m_w *g *(f_Rw0/1000 + f_Rw1/1000 *v /v00 + f_Rw2/1000 * ((v + Δv_air) /v00)^2) # vehicle resistance of passenger wagons (in N) with Sauthoff # /1000 because of the unit ‰ F_R_wagons = m_w *g *(f_Rw0/1000 + f_Rw1/1000 *v /v00 + f_Rw2/1000 * ((v + Δv_air) /v00)^2) # vehicle resistance of passenger wagons (in N) with Sauthoff # /1000 because of the unit ‰
# TODO: use forceFromCoefficient? F_R_wagons = forceFromCoefficient(f_Rw0, m_w) + ...
return F_R_wagons return F_R_wagons
end #function calcWagonsResistance end #function calcWagonsResistance
function forceFromCoefficient(f_R::Real, m::Real) """
forceFromCoefficient(f, m)
Calculate the force in N with the coefficient `f` in ‰ and the vehicle's mass `m` in kg.
# Examples
```julia-repl
julia> forceFromCoefficient(1.5, 68000.0)
1000.2783
```
"""
function forceFromCoefficient(f::Real, m::Real)
# equation is based on [Wende:2003, page 8] # equation is based on [Wende:2003, page 8]
# f_R: specific resistance (in ‰) F = f /1000 *m *g # force (in N) # /1000 because of the unit ‰
# m: vehicle's mass (in kg) return F
F_R = f_R /1000 *m *g # Resisting Force (in N) # /1000 because of the unit ‰
return F_R
end #function forceFromCoefficient end #function forceFromCoefficient
## calculate acceleration:
"""
acceleration(F_T, F_R, m_train, ξ_train)
Calculate the acceleration in m/s^2 with train characteristics and forces.
# Arguments
- `F_T::Real`: the tractive effort in N.
- `F_R::Real`: the resisting forces in N.
- `m_train::Real`: the train's mass in kg.
- `ξ_train::Real`: the train's rotation mass factor (without unit).
# Examples
```julia-repl
julia> acceleration(94400.0, 1700.0, 88000.0, 1.08)
0.9753787878787878
```
"""
function acceleration(F_T::Real, F_R::Real, m_train::Real, ξ_train::Real) function acceleration(F_T::Real, F_R::Real, m_train::Real, ξ_train::Real)
# equation is based on [Bruenger:2014, page 72] with a=dv/dt # equation is based on [Bruenger:2014, page 72] with a=dv/dt
# F_T: tractive effort (in N) a = (F_T - F_R) /m_train /ξ_train # acceleration (in m/s^2)
# F_R: resisting forces (in N)
# m_train: train's mass (in kg)
# ξ_train: train's rotation mass factor (without unit)
a = (F_T - F_R) /m_train /ξ_train # acceleration (in m/s)
return a return a
end #function acceleration end #function acceleration
## calculate step sizes:
"""
Δs_with_Δt(Δt, a_prev, v_prev)
Calculate the distance step in m with the time step in s, acceleration in m/s^2 and velocity in m/s.
See also [`Δs_with_Δv`](@ref), [`Δt_with_Δs`](@ref), [`Δt_with_Δv`](@ref), [`Δt_with_constant_v`](@ref), [`Δv_with_Δs`](@ref), [`Δv_with_Δt`](@ref).
# Examples
```julia-repl
julia> Δs_with_Δt(3.0, 0.5, 25.0)
77.25
```
"""
function Δs_with_Δt(Δt::Real, a_prev::Real, v_prev::Real) function Δs_with_Δt(Δt::Real, a_prev::Real, v_prev::Real)
# equation is based on [Wende:2003, page 37] # equation is based on [Wende:2003, page 37]
# Δt: time step (in s)
# a_prev: acceleration from previous support point
# v_prev: velocitiy from previous support point
Δs = Δt * (2*v_prev + Δt*a_prev) /2 # step size (in m) Δs = Δt * (2*v_prev + Δt*a_prev) /2 # step size (in m)
return Δs return Δs
end #function Δs_with_Δt end #function Δs_with_Δt
"""
Δs_with_Δv(Δv, a_prev, v_prev)
Calculate the distance step in m with the velocity step in m/s, acceleration in m/s^2 and velocity in m/s.
See also [`Δs_with_Δt`](@ref), [`Δt_with_Δs`](@ref), [`Δt_with_Δv`](@ref), [`Δt_with_constant_v`](@ref), [`Δv_with_Δs`](@ref), [`Δv_with_Δt`](@ref).
# Examples
```julia-repl
julia> Δs_with_Δv(1.0, 0.5, 25.0)
51.0
```
"""
function Δs_with_Δv(Δv::Real, a_prev::Real, v_prev::Real) function Δs_with_Δv(Δv::Real, a_prev::Real, v_prev::Real)
# equation is based on [Wende:2003, page 37] # equation is based on [Wende:2003, page 37]
# Δv: velocity step (in m/s) Δs = ((v_prev + Δv)^2 - v_prev^2) /2 /a_prev # step size (in m)
# a_prev: acceleration from previous support point
# v_prev: velocitiy from previous support point
Δs = ((v_prev + Δv)^2 - v_prev^2)/2/a_prev # step size (in m)
return Δs return Δs
end #function Δs_with_Δv end #function Δs_with_Δv
"""
Δt_with_Δs(Δs, a_prev, v_prev)
Calculate the time step in s with the distance step in m, acceleration in m/s^2 and velocity in m/s.
See also [`Δs_with_Δt`](@ref), [`Δs_with_Δv`](@ref), [`Δt_with_Δv`](@ref), [`Δt_with_constant_v`](@ref), [`Δv_with_Δs`](@ref), [`Δv_with_Δt`](@ref).
# Examples
```julia-repl
julia> Δt_with_Δs(10.0, 0.5, 25.0)
0.39841267341660824
```
"""
function Δt_with_Δs(Δs::Real, a_prev::Real, v_prev::Real) function Δt_with_Δs(Δs::Real, a_prev::Real, v_prev::Real)
# equation is based on [Wende:2003, page 37] # equation is based on [Wende:2003, page 37]
# Δs: distance step (in m) Δt = sign(a_prev) *sqrt((v_prev /a_prev)^2 + 2 *Δs /a_prev) - v_prev /a_prev # step size (in s)
# a_prev: acceleration from previous support point
# v_prev: velocitiy from previous support point
Δt = sign(a_prev) *sqrt((v_prev /a_prev)^2 + 2 *Δs /a_prev) - v_prev /a_prev # step size (in m/s)
return Δt return Δt
end #function Δt_with_Δs end #function Δt_with_Δs
"""
Δt_with_Δv(Δv, a_prev)
Calculate the time step in s with the velocity step in m/s and the acceleration in m/s^2.
See also [`Δs_with_Δt`](@ref), [`Δs_with_Δv`](@ref), [`Δt_with_Δs`](@ref), [`Δt_with_constant_v`](@ref), [`Δv_with_Δs`](@ref), [`Δv_with_Δt`](@ref).
# Examples
```julia-repl
julia> Δt_with_Δv(1.0, 0.5)
2.0
```
"""
function Δt_with_Δv(Δv::Real, a_prev::Real) function Δt_with_Δv(Δv::Real, a_prev::Real)
# equation is based on [Wende:2003, page 37] # equation is based on [Wende:2003, page 37]
# Δv: velocity step (in m/s)
# a_prev: acceleration from previous support point
Δt = Δv /a_prev # step size (in s) Δt = Δv /a_prev # step size (in s)
return Δt return Δt
end #function Δt_with_Δv end #function Δt_with_Δv
"""
Δt_with_constant_v(Δs, v)
Calculate the time step in s with the distance step in m and constant velocity in m/s.
See also [`Δs_with_Δt`](@ref), [`Δs_with_Δv`](@ref), [`Δt_with_Δs`](@ref), [`Δt_with_Δv`](@ref), [`Δv_with_Δs`](@ref), [`Δv_with_Δt`](@ref).
# Examples
```julia-repl
julia> Δt_with_constant_v(10.0, 25.0)
0.4
```
"""
function Δt_with_constant_v(Δs::Real, v::Real) function Δt_with_constant_v(Δs::Real, v::Real)
# equation is based on [Wende:2003, page 37] # equation is based on [Wende:2003, page 37]
# Δs: distance step (in m)
# v: constant velocity (in m/s)
Δt = Δs /v # step size (in s) Δt = Δs /v # step size (in s)
return Δt return Δt
end #function Δt_with_constant_v end #function Δt_with_constant_v
"""
Δv_with_Δs(Δs, a_prev, v_prev)
Calculate the velocity step in m/s with the distance step in m, acceleration in m/s^2 and velocity in m/s.
See also [`Δs_with_Δt`](@ref), [`Δs_with_Δv`](@ref), [`Δt_with_Δs`](@ref), [`Δt_with_Δv`](@ref), [`Δt_with_constant_v`](@ref), [`Δv_with_Δt`](@ref).
# Examples
```julia-repl
julia> Δv_with_Δs(10.0, 0.5, 25.0)
0.19920633670830412
```
"""
function Δv_with_Δs(Δs::Real, a_prev::Real, v_prev::Real) function Δv_with_Δs(Δs::Real, a_prev::Real, v_prev::Real)
# equation is based on [Wende:2003, page 37] # equation is based on [Wende:2003, page 37]
# Δs: distance step (in m)
# a_prev: acceleration from previous support point
# v_prev: velocitiy from previous support point
Δv = sqrt(v_prev^2 + 2*Δs*a_prev) - v_prev # step size (in m/s) Δv = sqrt(v_prev^2 + 2*Δs*a_prev) - v_prev # step size (in m/s)
return Δv return Δv
end #function Δv_with_Δs end #function Δv_with_Δs
"""
Δv_with_Δt(Δt, a_prev, v_prev)
Calculate the velocity step in m/s with the time step in s and acceleration in m/s^2.
See also [`Δs_with_Δt`](@ref), [`Δs_with_Δv`](@ref), [`Δt_with_Δs`](@ref), [`Δt_with_Δv`](@ref), [`Δt_with_constant_v`](@ref), [`Δv_with_Δs`](@ref).
# Examples
```julia-repl
julia> Δv_with_Δt(3.0, 0.5)
1.5
```
"""
function Δv_with_Δt(Δt::Real, a_prev::Real) function Δv_with_Δt(Δt::Real, a_prev::Real)
# equation is based on [Wende:2003, page 37] # equation is based on [Wende:2003, page 37]
# Δt: time step (in s)
# a_prev: acceleration from previous support point
Δv = Δt * a_prev # step size (in m/s) Δv = Δt * a_prev # step size (in m/s)
return Δv return Δv
end #function Δv_with_Δt end #function Δv_with_Δt
## calculate values for braking
"""
brakingDistance(v_start, v_end, a_braking, approxLevel)
Calculate the braking distance in m with velocities in m/s and acceleration in m/s^2.
See also [`brakingAcceleration`](@ref), [`brakingStartVelocity`](@ref).
# Arguments
- `v_start::Real`: the velocity at the start of braking in m/s.
- `v_end::Real`: the target velocity at the end of braking in m/s.
- `a_braking::Real`: the constant braking acceleration in m/s^2.
- `approxLevel::Integer`: the last position behind the decimal point that is not rounded
# Examples
```julia-repl
julia> brakingDistance(25.0, 15.0, -0.4253, 3)
470.2563
```
"""
function brakingDistance(v_start::Real, v_end::Real, a_braking::Real, approxLevel::Integer) function brakingDistance(v_start::Real, v_end::Real, a_braking::Real, approxLevel::Integer)
# equation is based on [Wende:2003, page 37] # equation is based on [Wende:2003, page 37]
# v_start: velocity at the start of braking (in m/s)
# v_end: target velocity at the end of braking (in m/s)
# a_braking: constant braking acceleration (in m/s^2)
s_braking = (v_end^2 - v_start^2) /2 /a_braking # braking distance (in m) s_braking = (v_end^2 - v_start^2) /2 /a_braking # braking distance (in m)
# TODO: also possible: Δs_with_Δv(v_end-v_start, a_braking, v_start)
# return max(0.0, ceil(s_braking, digits=approxLevel)) # ceil is used to be sure that the train stops at s_exit in spite of rounding errors
return max(0.0, ceil(s_braking, digits= approxLevel +1)) # ceil is used to be sure that the train stops at s_exit in spite of rounding errors return max(0.0, ceil(s_braking, digits= approxLevel +1)) # ceil is used to be sure that the train stops at s_exit in spite of rounding errors
end #function brakingDistance end #function brakingDistance
"""
brakingStartVelocity(v_end, a_braking, s_braking, approxLevel)
Calculate the maximum velocity in m/s where the train can start to brake to reach `v_end`.
See also [`brakingAcceleration`](@ref), [`brakingDistance`](@ref).
# Arguments
- `v_end::Real`: the target velocity at the end of braking in m/s.
- `a_braking::Real`: the constant braking acceleration in m/s^2.
- `s_braking::Real`: the braking distance in m.
- `approxLevel::Integer`: the last position behind the decimal point that is not rounded
# Examples
```julia-repl
julia> brakingStartVelocity(15.0, -0.4253, 500, 3)
25.4656
```
"""
function brakingStartVelocity(v_end::Real, a_braking::Real, s_braking::Real, approxLevel::Integer) function brakingStartVelocity(v_end::Real, a_braking::Real, s_braking::Real, approxLevel::Integer)
# equation is based on [Wende:2003, page 37] # equation is based on [Wende:2003, page 37]
# v_end: target velocity at the end of braking (in m/s)
# a_braking: constant braking acceleration (in m/s^2)
# s_braking: braking distance (in Ws)
v_start = sqrt(v_end^2 - 2*a_braking *s_braking) # braking start velocity (in m/s) v_start = sqrt(v_end^2 - 2*a_braking *s_braking) # braking start velocity (in m/s)
# return floor(v_start, digits= approxLevel)
return floor(v_start, digits= approxLevel +1) return floor(v_start, digits= approxLevel +1)
end #function brakingStartVelocity end #function brakingStartVelocity
"""
brakingAcceleration(v_start, v_end, s_braking)
Calculate the acceleration in m/s^2 to decelerate from `v_start` to `v_end` in m/s on `s_braking` in m.
See also [`brakingDistance`](@ref), [`brakingStartVelocity`](@ref).
# Examples
```julia-repl
julia> brakingAcceleration(25.0, 15.0, 500)
-0.4
```
"""
function brakingAcceleration(v_start::Real, v_end::Real, s_braking::Real) function brakingAcceleration(v_start::Real, v_end::Real, s_braking::Real)
# equation is based on [Wende:2003, page 37] # equation is based on [Wende:2003, page 37]
# v_start: braking start velocity (in m/s)
# v_end: target velocity at the end of braking (in m/s)
# s_braking: braking distance (in Ws)
a_braking = (v_end^2 - v_start^2) /2 /s_braking # constant braking acceleration (in m/s^2) a_braking = (v_end^2 - v_start^2) /2 /s_braking # constant braking acceleration (in m/s^2)
return a_braking return a_braking
end #function brakingAcceleration end #function brakingAcceleration