Package jmri.jmrit.logix

Class SpeedUtil

java.lang.Object

jmri.jmrit.logix.SpeedUtil

public class SpeedUtil
extends java.lang.Object

All speed related method transferred from Engineer and Warrant classes. Until June 2017, the problem of determining the actual track speed of a model train in millimeters per millisecond (same as meters/sec) from the throttle setting was usually done with an ad hoc "throttle factor". When created, the RosterSpeedProfile provides this needed conversion but generally is not done by users for each of their locos. Methods to dynamically determine a RosterSpeedProfile for each loco are implemented in this class.

Field Summary

Fields

Modifier and Type	Field	Description
static float	MAX_TGV_SPEED
static float	SCALE_FACTOR

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	SpeedUtil()

Method Summary

Modifier and Type	Method	Description
protected java.lang.String	getAddress()
protected BlockSpeedInfo	getBlockSpeedInfo(int idxBlockOrder)
protected void	getBlockSpeedTimes(java.util.List<ThrottleSetting> commands, java.util.List<BlockOrder> orders)	build map of BlockSpeedInfo's for the route.
DccLocoAddress	getDccAddress()
protected float	getDistanceOfSpeedChange(float fromSpeed, float toSpeed, long speedTime)	Return the distance traveled at current speed after a speed change was made.
protected float	getDistanceTraveled(float speedSetting, java.lang.String speedtype, float time)	Get distance traveled at a constant speed.
protected boolean	getIsForward()
protected RosterSpeedProfile	getMergeProfile()
protected float	getMomentumTime(float fromSpeed, float toSpeed)	ms momentum time to change speed for a throttle amount
protected RampData	getRampForSpeedChange(float fromSpeed, float toSpeed)	Get the ramp for a speed change from Throttle settings
protected float	getRampLengthForEntry(float fromSpeed, float toSpeed)	Get the ramp length for a speed change from Throttle settings
protected float	getRampThrottleIncrement()
protected int	getRampTimeIncrement()
RosterEntry	getRosterEntry()
java.lang.String	getRosterId()	Set the key identifier for the Speed Profile If a RosterEntry exists, _rosterId is the RosterEntry id or possibly is the RosterEntrytitle.
protected DccThrottle	getThrottle()
protected float	getThrottleSettingForSpeed(float trackSpeed)	Get the throttle setting needed to achieve a given track speed track speed is mm/ms.
protected float	getThrottleSpeedStepIncrement()	throttle's minimum speed change amount
protected int	getTimeForDistance(float throttleSetting, float distance)	Get time needed to travel a distance at a constant speed.
protected float	getTrackSpeed(float throttleSetting)	Get the track speed in millimeters per millisecond (= meters/sec) If SpeedProfile has no speed information an estimate is given using the WarrantPreferences throttleFactor.
protected void	leavingBlock(int blkIdx)	Just entered a new block at 'toTime'.
protected RosterEntry	makeRosterEntry(java.lang.String id)
protected float	modifySpeed(float tSpeed, java.lang.String sType)	Modify a throttle setting to match a speed name type Modification is done according to the interpretation of the speed name
protected static long	modifyTime(float speed, long time, float modifiedSpeed)	A a train's speed at a given throttle setting and time would travel a distance.
protected boolean	profileHasSpeedInfo()
protected boolean	secondGreaterThanFirst(java.lang.String speed1, java.lang.String speed2)
boolean	setAddress(java.lang.String id)	Sets dccAddress and key for a speedProfile.
boolean	setDccAddress(int number, java.lang.String type)
protected void	setDccAddress(DccLocoAddress dccAddr)	Called by: Warrant.setRunMode() about to run a warrant WarrantFrame.setup() for an existing warrant WarrantTableModel.cloneWarrant() when cloning an existing warrant
protected void	setIsForward(boolean direction)
protected void	setRampThrottleIncrement(float incr)
protected void	setRampTimeIncrement(int incr)
boolean	setRosterId(java.lang.String id)	Set a key to a loco's roster and speed info.
protected void	setThrottle(DccThrottle throttle)
protected void	speedChange(float throttleSetting)	The engineer makes this notification before setting a new speed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SCALE_FACTOR

public static final float SCALE_FACTOR

See Also:

Constant Field Values

MAX_TGV_SPEED

public static final float MAX_TGV_SPEED

See Also:

Constant Field Values

Constructor Detail

SpeedUtil

protected SpeedUtil()

Method Detail

getRosterEntry

@CheckForNull
public RosterEntry getRosterEntry()

Returns:

RosterEntry

getRosterId

public java.lang.String getRosterId()

Set the key identifier for the Speed Profile If a RosterEntry exists, _rosterId is the RosterEntry id or possibly is the RosterEntrytitle. Otherwise it may be just the decoder address

Returns:

key to speedProfile

setRosterId

public boolean setRosterId(java.lang.String id)

Set a key to a loco's roster and speed info. If there is no RosterEntry, the id still locates a session SpeedProfile for the loco. Called from: SpeedUtil.setDccAdress(String) - main parser WarrantFrame.setup() - edit existing warrant WarrantManagerXml - load warrant

Parameters:

id - key to speedProfile

Returns:

true if RosterEntry exists for id

getDccAddress

public DccLocoAddress getDccAddress()

getAddress

@CheckForNull
protected java.lang.String getAddress()

setDccAddress

protected void setDccAddress(DccLocoAddress dccAddr)

Called by: Warrant.setRunMode() about to run a warrant WarrantFrame.setup() for an existing warrant WarrantTableModel.cloneWarrant() when cloning an existing warrant

Parameters:

dccAddr - DccLocoAddress

setDccAddress

public boolean setDccAddress(int number,
                             java.lang.String type)

makeRosterEntry

protected RosterEntry makeRosterEntry(java.lang.String id)

setAddress

public boolean setAddress(java.lang.String id)

Sets dccAddress and key for a speedProfile. Will fetch RosterEntry if one exists. If _rosterEntry exists, _rosterId set to RosterEntry Id (which may or not be "id") else _rosterId set to "id" or decoder address. Called from: DefaultConditional.takeActionIfNeeded() - execute a setDccAddress action SpeedUtil.makeSpeedTree() - need to use track speeds WarrantFrame.checkTrainId() - about to run, assures address is set Warrantroute.getRoster() - selection form _rosterBox WarrantRoute.setAddress() - whatever is in _dccNumBox.getText() WarrantRoute.setTrainPanel() - whatever in _dccNumBox.getText() WarrantTableModel.setValue() - whatever address is put into the ADDRESS_COLUMN

Parameters:

id - address as a String, either RosterEntryTitle or decoder address

Returns:

true if address found for id

getRampThrottleIncrement

protected float getRampThrottleIncrement()

setRampThrottleIncrement

protected void setRampThrottleIncrement(float incr)

getRampTimeIncrement

protected int getRampTimeIncrement()

setRampTimeIncrement

protected void setRampTimeIncrement(int incr)

getMomentumTime

protected float getMomentumTime(float fromSpeed,
                                float toSpeed)

ms momentum time to change speed for a throttle amount

Parameters:

fromSpeed - throttle change

toSpeed - throttle change

Returns:

momentum time

getThrottleSpeedStepIncrement

protected float getThrottleSpeedStepIncrement()

throttle's minimum speed change amount

Returns:

speed step amount

getMergeProfile

protected RosterSpeedProfile getMergeProfile()

profileHasSpeedInfo

protected boolean profileHasSpeedInfo()

setIsForward

protected void setIsForward(boolean direction)

getIsForward

protected boolean getIsForward()

setThrottle

protected void setThrottle(DccThrottle throttle)

Parameters:

throttle - set DccThrottle

getThrottle

protected DccThrottle getThrottle()

secondGreaterThanFirst

protected boolean secondGreaterThanFirst(java.lang.String speed1,
                                         java.lang.String speed2)

modifySpeed

protected float modifySpeed(float tSpeed,
                            java.lang.String sType)

Modify a throttle setting to match a speed name type Modification is done according to the interpretation of the speed name

Parameters:

tSpeed - throttle setting (current)

sType - speed type name

Returns:

modified throttle setting

modifyTime

protected static long modifyTime(float speed,
                                 long time,
                                 float modifiedSpeed)

A a train's speed at a given throttle setting and time would travel a distance. return the time it would take for the train at another throttle setting to travel the same distance.

Parameters:

speed - a given throttle setting

time - a given time

modifiedSpeed - a different speed setting

Returns:

the time to travel the same distance at the different setting

getTrackSpeed

protected float getTrackSpeed(float throttleSetting)

Get the track speed in millimeters per millisecond (= meters/sec) If SpeedProfile has no speed information an estimate is given using the WarrantPreferences throttleFactor. NOTE: Call profileHasSpeedInfo() first to determine if a reliable speed is known. for a given throttle setting and direction. SpeedProfile returns 0 if it has no speed information

Parameters:

throttleSetting - throttle setting

Returns:

track speed in millimeters/millisecond (not mm/sec)

getThrottleSettingForSpeed

protected float getThrottleSettingForSpeed(float trackSpeed)

Get the throttle setting needed to achieve a given track speed track speed is mm/ms. SpeedProfile wants mm/s SpeedProfile returns 0 if it has no speed information

Parameters:

trackSpeed - in millimeters per millisecond (m/s)

Returns:

throttle setting or 0

getDistanceTraveled

protected float getDistanceTraveled(float speedSetting,
                                    java.lang.String speedtype,
                                    float time)

Get distance traveled at a constant speed. If this is called at a speed change the throttleSetting should be modified to reflect the average speed over the time interval.

Parameters:

speedSetting - Recorded (Normal) throttle setting

speedtype - speed name to modify throttle setting to get modified speed

time - milliseconds

Returns:

distance in millimeters

getTimeForDistance

protected int getTimeForDistance(float throttleSetting,
                                 float distance)

Get time needed to travel a distance at a constant speed.

Parameters:

throttleSetting - Throttle setting

distance - in millimeters

Returns:

time in milliseconds

getBlockSpeedTimes

protected void getBlockSpeedTimes(java.util.List<ThrottleSetting> commands,
                                  java.util.List<BlockOrder> orders)

build map of BlockSpeedInfo's for the route. Map corresponds to list of BlockOrders of a Warrant

Parameters:

commands - list of script commands

orders - list of BlockOrders

getBlockSpeedInfo

protected BlockSpeedInfo getBlockSpeedInfo(int idxBlockOrder)

getRampForSpeedChange

protected RampData getRampForSpeedChange(float fromSpeed,
                                         float toSpeed)

Get the ramp for a speed change from Throttle settings

Parameters:

fromSpeed - - starting speed setting

toSpeed - - ending speed setting

Returns:

ramp data

getRampLengthForEntry

protected float getRampLengthForEntry(float fromSpeed,
                                      float toSpeed)

Get the ramp length for a speed change from Throttle settings

Parameters:

fromSpeed - - starting speed setting

toSpeed - - ending speed setting

Returns:

ramp length

getDistanceOfSpeedChange

protected float getDistanceOfSpeedChange(float fromSpeed,
                                         float toSpeed,
                                         long speedTime)

Return the distance traveled at current speed after a speed change was made. Takes into account the momentum configured for the decoder to change from the previous speed to the current speed. Assumes the velocity change is linear. Does not return a distance greater than that needed by momentum time.

Parameters:

fromSpeed - throttle setting when speed changed to toSpeed

toSpeed - throttle setting being set

speedTime - elapsed time from when the speed change was made to now

Returns:

distance traveled

leavingBlock

protected void leavingBlock(int blkIdx)

Just entered a new block at 'toTime'. Do the calculation of speed of the previous block from when the previous block block was entered. Throttle changes within the block will cause different speeds. We attempt to accumulate these time and distances to calculate a weighted speed average. See method speedChange() below.

Parameters:

blkIdx - BlockOrder index of the block the engine just left. (not train) The lead engine just entered the next block after blkIdx.

speedChange

protected void speedChange(float throttleSetting)

The engineer makes this notification before setting a new speed. Calculate the distance traveled since the last speed change.

Parameters:

throttleSetting - the new Speed of the Throttle.