stevieb has asked for the wisdom of the Perl Monks concerning the following question:

Fellow Monk no_slogan wrote a piece of software that calculates the magnetic declination and inclination for a set of worldly coordinates.

In the mentioned thread, it was requested that a suitable naming convention be created for the resulting distribution that I very happily created, taking up the offer of readying it for the CPAN. I gave it the name Magnetic::Declination temporarily so I could build the original template with Module::Starter.

Although it's a recent post, it's in Cool Uses For Perl, so it may not be readily visible to all comers.

I will be ready by end of day today to upload it, but am waiting for consensus and am hoping to fast-track it a bit. I hope to have the name by early next week sometime. no_slogan has final say, so let's get some recommendations going if possible.

Here's the current SYNOPSIS and DESCRIPTION:

SYNOPSIS use Magnetic::Declination qw(mag_dec mag_inc); my $lat = 53.1234567; my $lon = -114.1234567; my $alt = 1098; my $declination = mag_dec($lat, $lon, $alt); my $inclination = mag_inc($lat, $lon, $alt); DESCRIPTION This module calculates and returns the magnetic declination and inclination (dip) calculations based on WMM earth magnetism model for a specified latitude and longitude pair. See L<NOAA|> for details.


Replies are listed 'Best First'.
Re: CPAN distribution naming recommendations
by BrowserUk (Pope) on Jun 03, 2017 at 02:29 UTC

    My suggestion is Geo::MagneticVariation or Geo::MagneticAngle. Geo, because that top level exists and contains many related modules; the rest because those are what the Ordnance Survey -- reputedly the best map makers in the world -- call it.

    With the rise and rise of 'Social' network sites: 'Computers are making people easier to use everyday'
    Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
    "Science is about questioning the status quo. Questioning authority". The enemy of (IT) success is complexity.
    In the absence of evidence, opinion is indistinguishable from prejudice. Suck that fhit

      Thank you. I especially appreciate the research put in, and the references supplied.

Re: CPAN distribution naming recommendations
by Laurent_R (Canon) on Jun 03, 2017 at 16:09 UTC
    As a sailing instructor and an amateur skipper and navigator, I would definitely like something like Navigation::MagneticDeclination.

    Now, since Geo is an existing top level domain, I think Geo::MagneticDeclination would also be very good.

    I think magnetic declination is better than magnetic variation (although they mean the same), because it's more clearly a technical term not subject to misunderstandings (variation may be construed as something that varies, or so). (See also

Re: CPAN distribution naming recommendations
by marinersk (Priest) on Jun 03, 2017 at 01:12 UTC

    While Magnetic::Declinationnicely names the module on its own merits, does it fit into a family of otherly-named modules related to positioning or mapping?

      Thanks! (real kudos most definitely goes to no_slogan without saying though).

      At first, before I got to really play with the code (and I fully admit that the math is so far beyond my comprehension that I can't even describe), I threw the name Magnetic::Declination quickly into the mix with the time I had so I could create a home to build from.

      Honestly, it doesn't really fit imho, as it defeats the top level naming structure of the CPAN for not joining into existing which morgon said, along with his statement that "Declination" doesn't fit either because the distribution will provide two functions (inclination as well as declination).

      I have not really specifically looked through the CPAN for where it could go. That's why I threw this question here. I'll re-visit this tomorrow, and before I review any further responses, I'll parse the CPAN namespace for top-level names, and we'll all go from there.

Re: CPAN distribution naming recommendations
by 1nickt (Abbot) on Jun 03, 2017 at 17:06 UTC

    Hi Stevieb

    1) Your code is only relevant for users of a magnetic compass. There is already Geo::Compass::Bearing and Geo::Compass::Points.

    2) While it's true that the terms "Magnetic Declination" and "Magnetic Variation" are interchangeable, *and* that both Wikipedia and NOAA use the former, I can tell you as a 15-yr licensed sea captain that the term "Magnetic Variation" is far more widely used in my experience.

    Furthermore, as you may know, there is a second element that must be considered when plotting a course using a magnetic compass, which is "Magnetic Deviation." Since "Deviation" and "Declination" are such similar words, I'd say that speaks to "Variation" as a better choice. This is particularly true when you consider the ancient formula for calculating magnetic compass course by hand from the true course, which is (I swear) taught with the mnemonic "True Virgins Make Dull Companions":

    T + V = M + D = C True + Variation = Magnetic + Deviation = Compass
    As you can see using "Declination" rather than "Variation" would break the mnemonic that's been used ever since the glory days of the British Navy.

    I therefore suggest that the best name for the module would be: Geo::Compass::Variation.

    (In a perfect world the namespace would be 'Geo::Compass::Magnetic::*' but now that there are already modules for Bearing and Points I think that the "magnetic" is implied.)

    Note: I realize that hikers rarely have to deal with compass deviation, as do pilots and mariners, but this module should be useful for all navigators.

    Bonus: A second mnemonic for working with compass vs. true course is "West is Best, East is Least" -- which should remind you that you add the variation in the west and subtract it in the east).

    Hope this helps!

    The way forward always starts with a minimal test.

      Thanks for the feedback Nick!

      I have to admit that although I've been very proficient at land orienteering most of my life, many of the equations and subtleties I did not understand. As far as variations, I've always been able to calculate that into things using my (to this day) WWII field compass and my topo maps, but doing the math to apply the variations in a digital playground have been very interesting, and I have learned a boatload of new ways to comprehend things.

      The project this is all for is coming along nicely. I have put on the CPAN some GPS-related code already, I'll be uploading this once a name is decided (in fact, I added a series of checks/bounds and tests today, so I'm ready to go) by the original author of the code. If they don't respond by Monday morning, I'll have to choose one. Once I'm done with the Arduino stuff and get this little project packaged, I'm going to port it ALL back to Perl to mix in with my Raspberry Pi work. Although the Pi isn't as field-friendly as an Arduino Trinket, there may still be some use for all of it bundled in a specific grouping of modules, but even if not, everything I've learned started as Perl, and the people in the Perl community, so it's the right thing to do.

      I like your suggestion of Geo::Compass::Variation. It totally fits the bill for the two simple functions the software provides without leaning directly at one of them, and I personally prefer to have only one capital letter in each section of a namespace if possible... it keeps it clean and unambiguous.

      update 2004 hrs EST: Being a land person most of my life and being able to use that knowledge to get from one place in water to the next land area is something I can do in a small scale, I presume that if all the code I'm writing that I'll port back works accurately (Google Compass has been as handy as my physical layout of maps/compass on my living room floor to assume accuracy), I would imagine on a boat/ship with electrical, a Pi, running Perl code could be useful in such situations. It doesn't need to be field light and portable if it's being used in a case that you're not considering weight and size because you're not on foot...

        Geo::Compass::Variation works for me, though I suspect that term is more common in the nautical world.

        One technical comment on your code is that it makes more sense for _calculate to return the X,Y,Z magnetic field components and leave the atan2 fiddling to mag_dec and mag_inc. (Maybe mag_dec should have an alias, mag_var.) Since someone might find an interesting use for that information, you might rename _calculate to mag_field and document it as a part of the interface.

        BTW, the technical report has some test data you could use in your module tests.

Re: CPAN distribution naming recommendations
by morgon (Priest) on Jun 03, 2017 at 01:18 UTC
    For my taste "Magnetic" is bad top-level name as it is not generic enough.

    And you say that it also calculates inclication, so "Declination" seems to be too specific.

    So I'd go with something like "Navigation::Compass" or the like (unless already taken).

      I really like your thoughts here, but I personally think that Navigation::Compass is too broad...

      This module deals exclusively and deliberately with the magnetic *offsets* that don't align with the true north grid, and realistically doesn't have anything to do with a compass, less a fractional angle that deviates from what perhaps a different module may provide.

      What this module does, is spits out a directional difference between true north and magnetic north (as well as inclination deviations, but I digress) that can be applied to a compass heading to ensure when traveling, no matter where you are, the direction that is output is the direction you're supposed to be heading regardless of location.

      So, a GPS software says you're to head in X.AB direction per grid north, and this software calculates the magnetic deviation from that. It would be up to the end user to combine these two numbers (addition, essentially) to understand the real magnetic direction they need to travel, which may become X.BC for example. Without the original direction (outside of this module's scope), this module doesn't do anything but produce the deviation itself.

        Geo::MagneticDeviation or Geo::Magnetic::Deviation, perhaps? Or Geo::Navigation::Magnetic(::)Deviation
Re: CPAN distribution naming recommendations
by stevieb (Canon) on Jun 03, 2017 at 03:13 UTC

    Heading off for the night, but my vote so far is Geo::MagneticVariation as suggested by BrowserUK. He provided a decent amount of reference material in this node that is very informative. I learned a lot from it, including the ways I (mis)use certain terminology.