Units in catalogue files

[ajtribick]

The attached file contains a diff against the src directory in SVN revision 4915 adds the ability to specify units for the Period and SemiMajorAxis properties in the EllipticalOrbit part of Celestia's input files. It also contains a test .ssc file to demonstrate this functionality.

The syntax is to place the unit in angle brackets after the property name, e.g.

Code: Select all

"TestUnits1" "Alf Men"
{
    Radius 70000
    Texture "exo-class3.*"
   
    EllipticalOrbit {
        Period<d> 365.25
        SemiMajorAxis<km> 149597870.7
        MeanAnomaly 30
    }
}

Which will place a planet in a 1 year orbit at a distance of 1 AU from Alpha Mensae. The units list in angle brackets is treated as a space-separated list, since some of the properties that can be specified in .ssc files allow more than one type of unit (e.g. LongLat which combines angular and length units) - none of these properties have these units specified yet but this is planned for the future. Only one unit per type can be specified, e.g. if you specify SemiMajorAxis<km AU> then km will be used. Units are case-sensitive.

Units currently supported are:
Length units: m, km, AU, ly
Time units: s, h, d, y

In terms of the internals of how it works, the <units> construction gets parsed to properties such as SemiMajorAxis%Length, Period%Time depending on the unit (a limitation of this approach is that it is not possible to have two units of different types with the same name). These properties cannot be specified directly in the catalogue file because of the % sign.

I plan to add more units in due course, my current plan is for the following:

Length units: m, km, rE (=Earth radius), rJ (=Jupiter radius), rS (=Solar radius), AU, ly, pc, kpc, Mpc
Time units: s, min, h, d, y
Angle units: mas (=milliarcsecond), arcsec (=arcsecond), deg, hRA (=hour of right ascension), rad
Mass units: kg, mE (=Earth mass), mJ (=Jupiter mass), mS (=Solar mass)

(No guarantees that this won't explode your computer or something... I have a lot more experience with C# than I do with C++, which is a far less forgiving language and I may have managed to do something spectacularly idiotic here. On the other hand, it seems to work for me running the qt4 version on Linux)

Edit: removed old version of patch

[duds26]

Mentioned this a while ago myself.
What you're doing is fantastic, now everybody can use the units they want.
well, sort of.
But, and this is big, future scripts that uses your units are going to be more self-documenting and Celestia will be more robust.

One thing: in Physics in school and stuff, it's written like this: 1.5135465 Unit.
Any chance of being able to do it this way?
1.35435Unit or 1.538487 Unit.
it would be more in line with other fields and be more robust because of the place it's located, with the value.

Example:

Code: Select all

"TestUnits1" "Alf Men"
{
    Radius 70000
    Texture "exo-class3.*"
   
    EllipticalOrbit {
        Period 365.25d
        SemiMajorAxis 149597870.7km
        MeanAnomaly 30
    }
}


A slightly different example:

Code: Select all

"TestUnits1" "Alf Men"
{
    Radius 70000
    Texture "exo-class3.*"
   
    EllipticalOrbit {
        Period 365.25 d
        SemiMajorAxis 149597870.7 km
        MeanAnomaly 30
    }
}


Will it be possible to say in the beginning of a file, on a per file basis, what type of units there will be used.
Then they would be used and only overwritten if ther is a unit at the value itself. Time saver.

Love your great work, keep going!!
Don't let C++ way of things get you scared.
The more you can do anything, the more the language is like a powerful engine with a greater degree of control!!

[t00fri]

Physicists suffer when units are not manifest. I suffered for 7.5 years

Thanks Andrew, for addressing that long overdue issue...

Fridger

[duds26]

Well your suffering is going to come to a halt.
Now that Celestia will have units.
And this is not the only thing.
Blender, mostly used for 3D has a proposal for adding units.
http://wiki.blender.org/index.php/BlenderDev/Blender2.5/DimensionRNA

Now physicists will suffer less and less from those issues!!

[ajtribick]

I don't think dropping the delimiters around the units section is a good idea: it provides a way to tell the parser to expect units at a given point. Also helps to insulate against potential for future "nasty surprises" if more properties get added. Whether it goes prefix or postfix isn't too much of an issue code-wise. My choice of using prefix is because the notation is more similar to functions, generics and templates (take your pick depending on what your favourite language's syntax is), and that once you start getting into various array properties and mixed type arrays, the syntax would diverge from "normal" usage anyway, e.g.

Code: Select all

LongLat [ 20 -10 500 ] <deg m>

Which would be read as meaning the angle quantities are degrees and the length quantity is metres, not that all three quantities are some product of degrees and metres, or

Code: Select all

LongLat [ 30 -5 125 ] <m>

Which would be read as meaning that the length quantity is in metres but the angle quantities should use the default unit, not that the entire array is in metres.

Putting the units up front seems to me a way of avoiding getting caught by such "gotchas" which going down the "natural language" route might tend to encourage. Would welcome more thoughts on this issue.

[Chuft-Captain]

I don't think dropping the delimiters around the units section is a good idea: it provides a way to tell the parser to expect units at a given point. Also helps to insulate against potential for future "nasty surprises" if more properties get added.

I agree Andrew. Keep it as you've done it -- with the space delimiter (let's not make life any more difficult for the parser than it has to be ).

One question :
Are you referencing pre-defined Celestia conversion factors for units such as AU, Ly, and y ?

CC

[ajtribick]

Are you referencing pre-defined Celestia conversion factors for units such as AU, Ly, and y ?

So far as they are available, yes. I'm planning to move some of the constants into astro.h (which seems to be the appropriate place for this kind of thing) - it seems that the year conversion factor is hardcoded at several points in the code for example.

There's also the issue of what to take as the values for planetary radii: for example the customorbit code has constants defining Jupiter and Saturn radii as 71398 and 60330 km respectively, however in solarsys.ssc the radii of these planets are given as 71492 and 60268 km. I'm inclined towards using these latter values for the units code (not going to mess with the customorbits code though - presumably the sources for the orbits use these values)

[Chuft-Captain]

Are you referencing pre-defined Celestia conversion factors for units such as AU, Ly, and y ?

So far as they are available, yes. I'm planning to move some of the constants into astro.h (which seems to be the appropriate place for this kind of thing) - it seems that the year conversion factor is hardcoded at several points in the code for example.

Good. I was just checking that you weren't adding even more duplicated constants.
Good idea also to do a tidy up of existing duplicates if not too much work or too risky.

There's also the issue of what to take as the values for planetary radii: for example the customorbit code has constants defining Jupiter and Saturn radii as 71398 and 60330 km respectively, however in solarsys.ssc the radii of these planets are given as 71492 and 60268 km. I'm inclined towards using these latter values for the units code (not going to mess with the customorbits code though - presumably the sources for the orbits use these values)

In the case of Saturn, 60330 is apparently the radius of Saturn at the 100 millibar altitude, and 60268 is the 1 bar level (which is the value that Horizons uses). See: the short exchange of comments in this thread.

Is it really necessary however to have units expressed in planetary radii? -- having too many units could become confusing and / or unwieldy.
I would have thought that m, km, AU, Ly, pc, Kpc, Mpc, and maybe also Gpc would be plenty.
I think we should give some thought to limiting available units to accepted SI-units, and a limited number of accepted astronomical units such as Ly and Parsec (and 1000 multiples of such, as above).

(Some would argue that the Ly should be excluded in deference to the parsec. )

CC

[ajtribick]

I noticed a bug in the code I posted at the top of this thread - some of the time units have incorrect definitions, I have already fixed this in my local copy of the code, so will be fixed when I post the next update.

Regarding using planetary radii as units, this would make things more convenient for the extrasolar planet files, as the literature typically uses values scaled to Jupiter radii for transiting planets (or Earth radii now that some lower-mass transiting planets have been found). Similar thing goes for star radii - often these are given in solar radii, not in km. I don't think there's much to be gained by incorporating any other body radii in the units section beyond these though.

[Cham]

Andrew,

the units would be better located after the numbers :

Radius 56437 <km>

instead of Radius<km> 56437

Is it possible ?

[ajtribick]

It's a matter of putting the code to read units after the part which reads the value instead of before. So yes, easily done. What would NOT be easily done would be to add support for, e.g.

LongLat [ 24 <deg>, 0.1 <rad>, 100 <m> ]

So don't expect that to happen for a while

Currently progressing through various sections of the code to add units support... so far no showstoppers. There's some rather weird code in stardb.cpp where some parameters get their positions reduced to single-precision which apparently was put there to be consistent with the star database - I'm guessing that since Celestia now stores rectangular coordinates in stars.dat we don't need to do this (and leaving it in may lead to weird effects if someone tries to modify a star located a long way from home), but I'll defer to the other developers on this one, not going to change that for the moment.

[Guckytos]

Couldn't also a few other things be cleaned up that seem strange or inconsistant (at least to me)?

- Julian dates (Use instead "normal" dates as standard?)
- The difference in angles for different catalogues (decimal degrees, hours+minutes+seconds, degree+minute+seconds)

Regards,

Guckytos

[ajtribick]

- Julian dates (Use instead "normal" dates as standard?)

It is already possible to specify dates using strings: according to the Wiki, a string value of "2007 10 09 12:13:14" will work. Note this is in TDB.

- The difference in angles for different catalogues (decimal degrees, hours+minutes+seconds, degree+minute+seconds)

While I would really really like to do this, I am not going to. Changing the default units would totally break many existing add-ons... IMHO the only time such a break would make sense is with a major version number upgrade. One of the motivations for adding units to Celestia is to get around these kind of inconsistencies without breaking existing content.

[ajtribick]

Keeping on adding units support... turns out I am going to be supporting arcmin as an angle unit because of its use in globular cluster definitions. I am probably going to omit support for units on old-style rotation definitions as these are only retained for backwards compatibility (plus the degrees per year value of PrecessionRate is a weird one to deal with). There's also the issue of ScriptedOrbit/ScriptedRotation parameters - I don't do much in the way of scripting, so I'm not sure what the best way to handle this issue is. Would it be better to multiply the values before passing to the script, or provide some alternative way of getting the scaling factors?

Also, is anyone using Mass for anything - apparently it is available for scripts but not currently used in Celestia. From extrasolar.ssc it looks like for planets it should be defaulted to Earth masses, stars don't currently support this property (but I have some vague plans which might require it at some future point).

[selden]

There's also the issue of ScriptedOrbit/ScriptedRotation parameters - I don't do much in the way of scripting, so I'm not sure what the best way to handle this issue is. Would it be better to multiply the values before passing to the script, or provide some alternative way of getting the scaling factors?

ScriptedOrbit and ScriptedRotation parameters must be passed unchanged.
They're arbitrary names for arguments to functions written by the author of the addon.
Any relationship to any particular set of measurement units is defined only by the code in the function.
There is no way for the SSC code to know how they are going to be used.

[chris]

Andrew,

This is a great addition. I checked out your code, and it looks good, with clean and minimal changes to the parser.

Keeping on adding units support... turns out I am going to be supporting arcmin as an angle unit because of its use in globular cluster definitions. I am probably going to omit support for units on old-style rotation definitions as these are only retained for backwards compatibility (plus the degrees per year value of PrecessionRate is a weird one to deal with). There's also the issue of ScriptedOrbit/ScriptedRotation parameters - I don't do much in the way of scripting, so I'm not sure what the best way to handle this issue is. Would it be better to multiply the values before passing to the script, or provide some alternative way of getting the scaling factors?

Before units could be useful for a scripted orbit, there would need to be some means for the script to declare the type of quantity for its parameters: distance, time, angle, Julian date, etc. For the time being, parameters should be passed unmodified to a ScriptedOrbit or ScriptedRotation.

Also, is anyone using Mass for anything - apparently it is available for scripts but not currently used in Celestia. From extrasolar.ssc it looks like for planets it should be defaulted to Earth masses, stars don't currently support this property (but I have some vague plans which might require it at some future point).

You are correct that mass is not used by Celestia right now, and also that the default units are Earth masses. (The only use I envision for planet masses is that Celestia might show them as part of the selection info. But, this goes against the unofficial policy that Celestia only display data relevant for visual simulation. Also, typically only the quantity mass * sin(inclination) is known--we wouldn't want code that naively labeled this as simply mass in the selection info.)

--Chris

[duds26]

I don't think dropping the delimiters around the units section is a good idea: it provides a way to tell the parser to expect units at a given point. Also helps to insulate against potential for future "nasty surprises" if more properties get added. Whether it goes prefix or postfix isn't too much of an issue code-wise. My choice of using prefix is because the notation is more similar to functions, generics and templates (take your pick depending on what your favourite language's syntax is), and that once you start getting into various array properties and mixed type arrays, the syntax would diverge from "normal" usage anyway, e.g.

Code: Select all

LongLat [ 20 -10 500 ] <deg m>

Which would be read as meaning the angle quantities are degrees and the length quantity is metres, not that all three quantities are some product of degrees and metres, or

Code: Select all

LongLat [ 30 -5 125 ] <m>

Which would be read as meaning that the length quantity is in metres but the angle quantities should use the default unit, not that the entire array is in metres.

Putting the units up front seems to me a way of avoiding getting caught by such "gotchas" which going down the "natural language" route might tend to encourage. Would welcome more thoughts on this issue.

Postfix please.

Those gotchas can be solved robustly, at least for this unit thing.

Well with the delimiters, you can tell the parser to search after the end first and then read the number in.
(It's just a little more work to do.
With good code that isn't too much duplicated it shouldn't be much work.)

In the case of the array, I would like to see something like this:

Code: Select all

LongLat [ 20 -10 500 ] <deg> <m> <m>


This leaves the most flexible way to deal with it, one unit for each.
(Know it won't happen soon or something, but this is what I would want to do with units:)

Code: Select all

LongLat [ 20deg -10m 500m ]


I use the spaces for the delimiter and paste the unit to the numbers.
I can do this robust without any surprise.
The parser can search for the first non-number character and divide it up.
It's a little bit more work, but it isn't very much.
Just more planning involved.

Anyway, like the idea of having units in Celestia.
Keep on coding!

[ajtribick]

Ok postfix it is. However I still do not think independent qualification of units of the same dimension in vectors is worthwhile. Is there a use case for, say,

Code: Select all

LongLat [ 1 -25 350 ] <rad deg m>

And is it sufficiently compelling to justify coming up with a sensible interpretation of, say,

Code: Select all

SemiAxes [ 5 1 3 ] <rE rJ>

I'm holding off on the script units. The one change I am making to the script parameters parser is to avoid passing any parameter with a % sign in it to the script (I don't know what effect that would have in lua, but I suspect it would lead to weirdness). Coming up with a new all-singing, all-dancing interface to orbit/rotation scripts is outside the scope of this change

As for use of mass parameters, I am thinking these would be useful in some future project (not promising anything at the moment!) for generating tidally-distorted Roche models, though I'm not particularly sure how relevant this would be for real planets - IIRC the hot Jupiters all lie well within their Roche lobes.


Also I meant to discuss the following upthread, but forgot, sorry...

Will it be possible to say in the beginning of a file, on a per file basis, what type of units there will be used.
Then they would be used and only overwritten if ther is a unit at the value itself. Time saver.

I have no plans to do this. The issue is that when the file is read you are dealing with a tokenizer and parser that have no knowledge of what the tokens mean. These turn the file into a set of associative arrays, which have no knowledge of which file they came from. Adding this kind of feature would involve a significant change in the way that Celestia reads the files, and the same system is used for several different file formats: as well as .ssc, .stc, .dsc, you have things like asterisms.dat going through that system.

[chris]

Ok postfix it is.

I actually preferred prefix, but I'll yield to the majority on this one.

However I still do not think independent qualification of units of the same dimension in vectors is worthwhile. Is there a use case for, say,

Code: Select all

LongLat [ 1 -25 350 ] <rad deg m>

And is it sufficiently compelling to justify coming up with a sensible interpretation of, say,

Code: Select all

SemiAxes [ 5 1 3 ] <rE rJ>

Those are rather perverse usages. I think it's reasonable to specify that for number lists, only one unit per quantity type is permitted. Mixing different length (or time or angle) units should not be allowed within a number list.

I'm holding off on the script units. The one change I am making to the script parameters parser is to avoid passing any parameter with a % sign in it to the script (I don't know what effect that would have in lua, but I suspect it would lead to weirdness). Coming up with a new all-singing, all-dancing interface to orbit/rotation scripts is outside the scope of this change

Good idea. I don't think that the effort required to add units for ScriptedOrbit and ScriptedRotation is justified at this point. If certain ScriptedOrbit modules came into widespread use, then it might be worthwhile. But right now, ScriptedOrbits tend to be one-offs, used in just a single add-on.

And now something I meant to discuss upthread:

Will it be possible to say in the beginning of a file, on a per file basis, what type of units there will be used.
Then they would be used and only overwritten if ther is a unit at the value itself. Time saver.

I have no plans to do this. The issue is that when the file is read you are dealing with a tokenizer and parser that have no knowledge of what the tokens mean. These turn the file into a set of associative arrays, which have no knowledge of which file they came from. Adding this kind of feature would involve a significant change in the way that Celestia reads the files, and the same system is used for several different file formats: as well as .ssc, .stc, .dsc, you have things like asterisms.dat going through that system. So I'm not going to do that.

There are also advantages to using standard default units for all ssc, stc, and dsc files. It makes it possible to cut a definition from one file and paste it into another file without worrying about what default units were set at the beginning of the file.

--Chris

[Chuft-Captain]

Ok postfix it is.

I actually preferred prefix, but I'll yield to the majority on this one.

I also prefer to see the units specified immediately after the property name, and before the value (as you originally specified Andrew). I just think it will be more readable and easier to understand (especially when mixed with numbers with many significant digits).
ie. It makes better sense (cognitively) when reading, to know the units before reading the value.

CC