[steamer_ctn]

I have been trying to understand the Units of Measure (UoM) that OR is using internally so that I can understand the code a better. I thought that it might be of assistance to others, and so I will share my interpretation of the _STF.cs file.

I have summarised my findings in the table below.

The Valid UoM column indicates units that can be used in a WAG or ENG file, and as one would expect, they are based on those used in MSTS files.

The OR default column indicates the UoM that is used by OR whenever these type of values are read, so for example, distance measurements are converted to metres, power measurements will be converted to watts, volume to cubic feet, etc.

To ensure that the conversion process occurs correctly the UoM must follow the value without any spaces, for example, ( 23in ) will be correctly converted to the metric equivalent, whereas ( 23 in ) will be read directly with the UoM being ignored, and OR will think that it is 23 metres.

Similarly volume and area parameters appear to need to be surrounded by ", for example ( 2198*(ft^2) ) will be read as 2198 sq metres, whereas ( "2198*(ft^2)" ) will be correctly converted to 204 sq m.

Thus it is important to ensure that UoM used in WAG and ENG files are correctly formatted.

Please feel free to add more, or correct my interpretation as appropriate.

Thanks

Attached thumbnail(s)

• 

[cjakeman]

steamer_ctn, on 13 May 2013 - 03:27 AM, said:

The OR default column indicates the UoM that is used by OR whenever these type of values are read, so for example, distance measurements are converted to metres, power measurements will be converted to watts, volume to cubic feet, etc.

Good point.

I noticed quite recently that the internal units weren't exclusively metric, but we also have cubic feet (and, from your table, pounds/sq in). I would like to all internal units to be consistent.

We also ought to add Amperes as they will be needed soon.

[jtr1962]

For what it's worth, as the chart says if speed has no units then mph should be assumed but it doesn't appear to work this way. When parsing .eng files the dynamic brake parameters dynamicbrakesminusablespeed, dynamicbrakesfadingspeed, dynamicbrakesmaximumeffectivespeed, and dynamicbrakesmaximumspeedforfadeout are always unitless and should be interpreted as being in mph in order to work correctly. OR currently treats them as if they're in m/s.

[James Ross]

I agree that internal OR variables should always be metric - and also SI standard units where it makes sense. Sometimes SI standard units will result in values that are huge or tiny for typical values and in those cases using a scaled metric unit is fine (e.g. using kg/h instead of g/s).

I think the table needs an extra column: split out "OR Default" in to "OR Default" (unit assumed if none in eng/wag file) and "OR Internal" (unit used in code variables). The default value for numbers in eng/wag files isn't (and shouldn't be) tied to the internal unit of the variable (I've no idea if this is actually tied together in the code or just a feature of the way this table was compiled).

Otherwise, great job - this kind of table is exactly the sort of thing we need in the documentation. Thanks!

[disc]

psi, cubic feet, pounds per hour doesn't seem to be SI for me :oldstry:
For pressure it should have be pascals(pa, aka N/m2) scaled by kilo, and cubic metres for volume.

[copperpen]

Do not forget in the Mass UoM there are Imperial tons, US tons and Metric tons, the last of which is used by MSTS. Not too sure about those Volume and Area units either. I have always got rid of those and used standard figures without the math bit on the end.

[Lindsayts]

James Ross, on 13 May 2013 - 10:42 AM, said:

I agree that internal OR variables should always be metric - and also SI standard units where it makes sense. Sometimes SI standard units will result in values that are huge or tiny for typical values and in those cases using a scaled metric unit is fine (e.g. using kg/h instead of g/s).

I think the table needs an extra column: split out "OR Default" in to "OR Default" (unit assumed if none in eng/wag file) and "OR Internal" (unit used in code variables). The default value for numbers in eng/wag files isn't (and shouldn't be) tied to the internal unit of the variable (I've no idea if this is actually tied together in the code or just a feature of the way this table was compiled).

How can the default value __NOT__ be tied to an internal value if the unit is not specfied. What _stf.cs appears to do is scan all values for a units suffix if one is found it converts the variable to a specified unit. I have not checked specficly what happens if no unit is specfied it does not though throw an error, it may be a REAL good idea if it did, at least a warning that no unit is specfied and a certain unit is assumed. That would save a great many headaches. Perhaps this is something that should be looked in to so an unspecfied unit cannot throw a spanner in the works.

Quote

Otherwise, great job - this kind of table is exactly the sort of thing we need in the documentation. Thanks!

Amen brother!!!! I have constructed my own table of default units, unit suffix's and conversions compiled from _stf.cs as otherwise one is totally lost when playing around with the eng files. I never thought of putting it up though as it is quite clear in the source and so few appear to be interested in the "physics". One thing I have not checked is if all internal calculations assume a unit is in OR's default unit. The mixing of unit systems certainly within the steam physics makes the code far more difficult to understand than needs to be the case.

I believe the table would be better presented in the forum as a text file rather than a formated printable table is a text table would be more flexible in use and easier for anyone to add to.

Errrrrrrrrrrr,
Can I assume steamer_ctn is from the Aus route Coals to Newcastle fame, certainly sounds like him.

Lindsay

[steamer_ctn]

jtr1962, on 13 May 2013 - 10:34 AM, said:

For what it's worth, as the chart says if speed has no units then mph should be assumed but it doesn't appear to work this way. When parsing .eng files the dynamic brake parameters dynamicbrakesminusablespeed, dynamicbrakesfadingspeed, dynamicbrakesmaximumeffectivespeed, and dynamicbrakesmaximumspeedforfadeout are always unitless and should be interpreted as being in mph in order to work correctly. OR currently treats them as if they're in m/s.

Thanks for the feedback, I think that you are correct that a parameter without a unit will default to the OR Default value, depending on how the coder has defined the read statement (see below). So in your case no UoM will result in values being in m/s, similarly the majority of brake statements without a UoM would be in psi, etc.


Below are some more of my observations:



Coding Variations

As alluded to above there seems to be some differences in how coders are coding read statements which I believe could lead to errors.

For example, a read statement generally has the following form:

case "engine(cylinderdiameter": CylinderDiameterM = stf.ReadFloatBlock(STFReader.UNITS.Distance, null); break;

- MSTSSteamLocomotive.cs

In this example the Units are clearly defined as Distance ones, and therefore will be treated as has been defined above for "distance" UoM.

However in some locations the following format has been used:

case "wagon(brakepipevolume": BrakePipeVolumeFT3 = stf.ReadFloatBlock(STFReader.UNITS.Any, null); break;

- Brakes.cs file

In this instance unit has been defined as ANY, so I suspect that the value will be read, but no "OR Default" is relevant so it will depend upon the UoM that the coder has assumed in his calculations, it will also mean that other "volume" units will not be correctly recognised.

Ideally wherever a UoM has been defined, it should be used.



Issues Created

Sadly I believe that the use of a mixture of Imperial and SI units in the OR code has complicated the coding, and caused confusion and errors.

My example is the Steam Generation Value in the MSTSSteamLocomotive.cs. It is calculated using the following formula:

EvaporationLBpS = boilerKW / (1.055f * steamHeat);

On the RHS side of the formula it is using metric units, so the final value on the LHS will be in kg/s UoM. It actually needs to be in lb/s. The fix is to multiply the answer by the conversion factor between kg and lbs, ie 2.205, as follows:

EvaporationLBpS = (boilerKW / (1.055f * steamHeat) * 2.205f);

This results in an approx doubling of the Steam Generated figure which is more in line with the actual value.

I have logged a patch file for the above error on Launchpad.

I believe that there are a number of similar errors in this file which is impacting in some way on the performance of the steam locomotive.



Way Forward

I suspect that the effort to align OR and recode it onto a single internal reference unit framework will be significant, and given the development resources, not something likely to happen in the near future. (Happy to hear otherwise).

Therefore I feel that we will need to accept were we are in regard to UoM, and mitigate the issues as best we can. Both the community and the developers can play a part in this approach.

I think that the following things need to happen:

i) UoM framework needs to be agreed and visible to all. Whilst it would be nice to have many different units, it is probably best to limit the number as much as possible.
ii) Developers need to ensure that their coding is clear and using the same units throughout all relevant formulae. It would also be good to comment formulae so that constants and conversion factors can be confirmed easily.
iii) The community needs to adjust WAG and ENG files to clearly define the UoM of measure, rather then relying on guessing unitless values.

Some work will need to be done in aligning the formulae to their relevant values as described above, and sorting out the read statements as well.

Whilst this is a large post, I suspect that it has some importance to the direction of OR, and will need some compromises to achieve the best outcome.

{Note to the developers: I am happy to try and assist within my limited coding experience. Contact me off line if you wish to discuss. Thanks}

Lindsayts, on 13 May 2013 - 01:58 PM, said:

Errrrrrrrrrrr,
Can I assume steamer_ctn is from the Aus route Coals to Newcastle fame, certainly sounds like him.
Lindsay

Yes, I am.

Cheers

[James Ross]

Lindsayts, on 13 May 2013 - 01:58 PM, said:

How can the default value __NOT__ be tied to an internal value if the unit is not specfied. What _stf.cs appears to do is scan all values for a units suffix if one is found it converts the variable to a specified unit.

The internal unit and default unit have no reason to be the same. Let's say that we're dealing with velocity (speed), so the internal unit is 'm/s', and that the default unit is 'mph'.

• 100mph is converted from 100mph to 44.704m/s.
  
• 100kph is converted from 100kph to 27.778m/s.
  
• 100 is converted from 100mph to 44.704m/s.

The internal unit should be the same for each type of data (velocity, mass, force, etc.), while the default unit is likely to vary by source location (e.g. MSTS data files might default to mph everywhere, or only most places, or something, but OR data files might default to kph - though I suspect OR data files should not have variable units :) ).

Lindsayts, on 13 May 2013 - 01:58 PM, said:

I have not checked specficly what happens if no unit is specfied it does not though throw an error, it may be a REAL good idea if it did, at least a warning that no unit is specfied and a certain unit is assumed. That would save a great many headaches. Perhaps this is something that should be looked in to so an unspecfied unit cannot throw a spanner in the works.

As long as it isn't a really common practice to omit units on items, this seems like a good idea; I would print it out as an information message because OR knows what's going on (it has a default unit so the data isn't wrong), but it wants you to know that it is possibly suspect.

[James Ross]

steamer_ctn, on 14 May 2013 - 12:10 AM, said:

I think that the following things need to happen:

i) UoM framework needs to be agreed and visible to all. Whilst it would be nice to have many different units, it is probably best to limit the number as much as possible.
ii) Developers need to ensure that their coding is clear and using the same units throughout all relevant formulae. It would also be good to comment formulae so that constants and conversion factors can be confirmed easily.
iii) The community needs to adjust WAG and ENG files to clearly define the UoM of measure, rather then relying on guessing unitless values.

Some work will need to be done in aligning the formulae to their relevant values as described above, and sorting out the read statements as well.

All good points; we do have a guideline that all variables containing physical data should have the unit as a suffix, which is used in many but probably not all places. I think adding these where they are missing would be a good first step - especially since it is really easy to rename variables in Visual Studio (F2). Then it'll be clearer when formulae are messing up the calculation.

As for conversion factors, we do have some static classes defining these values - and we should always use them when converting values. E.g. to convert something from kph to mph, use MpH.FromKpH(). Define more of these as necessary in RunActivity\Commong\Conversions.cs. We can also define constants containing the conversion values if necessary, but the JIT is good at inlining the tiny conversion methods, so it isn't critical.