Degenerate Conic

D1MACH Re-Revisited

The classic Fortran routines r1mach (for single precision real numbers), d1mach (for double precision real numbers), and i1mach (for integers) were originally written in the mid-1970s for the purpose of returning basic machine or operating system dependent constants in order to provide portability. Typically, these routines had a bunch of commented out DATA statements, and the user was required to uncomment out the ones for their specific machine. The original versions included constants for the following systems:

• Burroughs 5700/6700/7700
• CDC 6000/7000 series
• Data General Eclipse
• DEC PDP 10 (KA and KI processors)
• DEC PDP 11
• Harris S220
• Honeywell 6000 series
• IBM 360/370 series
• SEL systems 85/86
• Univac 1100 series
• XEROX SIGMA 5/7/9

Over the years, various versions of these routines have been created:

• Seemingly the oldest versions still available (from SLATEC): r1mach.f, d1mach.f, and i1mach.f.
• Updated Fortran 77 versions from the PORT library: r1mach.f, d1mach.f, and i1mach.f.
• More recent Fortran 77 versions from BLAS: r1mach.f, d1mach.f, and i1mach.f.
• Fortran 90 versions by Einarsson (1996): r1mach.f90, d1mach.f90, and i1mach.f90.

In the Fortran 90 versions, the original routines were modified to use various intrinsic functions available in Fortran 90. However, some hard-coded values remained in i1mach. With the advent of more recent standards, it is now possible to provide modern and completely portable versions which are described below. Starting with the Fortran 90 versions, the following changes were made:

• The routines are now in a module. We declare two module parameters which will be used in the routines:

integer, parameter :: sp = kind(1.0)    ! single precision kind
integer, parameter :: dp = kind(1.0d0)  ! double precision kind

Of course, putting them in a module means that they are not quite drop-in replacements for the old routines. If you want to use this module with legacy code, you'd have to update your code to add a use statement. But that's the way it goes. Nobody should be writing Fortran anymore that isn't in a module, so I'm not going to encourage that.

• The comment strings have been updated to Ford-style. I find the old SLATEC comment block style extremely cluttered. Various cosmetic changes were also made (e.g., changing the old .GE. to >=, etc.)

• All three routines were made pure. The error stop construct was used for the out of bounds input condition (Fortran 2008 allows error stop in pure procedures).

• New intrinsic constants available in the Fortran 2008 standard were employed (see below).

The new routines can be found on GitHub. They are shown below without the comment blocks.

The new routines

The new d1mach routine is:

D1MACH

  pure real(dp) function d1mach(i)

    integer, intent(in) :: i

    real(dp), parameter :: x = 1.0_dp
    real(dp), parameter :: b = real(radix(x), dp)

    select case (i)
    case (1); d1mach = b**(minexponent(x) - 1) ! the smallest positive magnitude.
    case (2); d1mach = huge(x)                 ! the largest magnitude.
    case (3); d1mach = b**(-digits(x))         ! the smallest relative spacing.
    case (4); d1mach = b**(1 - digits(x))      ! the largest relative spacing.
    case (5); d1mach = log10(b)
    case default
        error stop 'Error in d1mach - i out of bounds'
    end select

  end function d1mach

This is mostly just a reformatting of the Fortran 90 routine. We make x and b parameters, and use error stop for the error condition rather than this monstrosity:

          WRITE (*, FMT = 9000)
 9000     FORMAT ('1ERROR    1 IN D1MACH - I OUT OF BOUNDS')
          STOP

R1MACH

The updated R1MACH is similar, except the real values are real(sp) (default real, or single precision):

  pure real(sp) function r1mach(i)

    integer, intent(in) :: i

    real(sp), parameter :: x = 1.0_sp
    real(sp), parameter :: b = real(radix(x), sp)

    select case (i)
    case (1); r1mach = b**(minexponent(x) - 1) ! the smallest positive magnitude.
    case (2); r1mach = huge(x)                 ! the largest magnitude.
    case (3); r1mach = b**(-digits(x))         ! the smallest relative spacing.
    case (4); r1mach = b**(1 - digits(x))      ! the largest relative spacing.
    case (5); r1mach = log10(b)
    case default
      error stop 'Error in r1mach - i out of bounds'
    end select

  end function r1mach

I1MACH

The new i1mach routine is:

  pure integer function i1mach(i)

    integer, intent(in) :: i

    real(sp), parameter :: x = 1.0_sp
    real(dp), parameter :: xx = 1.0_dp

    select case (i)
    case (1);  i1mach = input_unit
    case (2);  i1mach = output_unit
    case (3);  i1mach = 0  ! Punch unit is no longer used
    case (4);  i1mach = error_unit
    case (5);  i1mach = numeric_storage_size
    case (6);  i1mach = numeric_storage_size / character_storage_size
    case (7);  i1mach = radix(1)
    case (8);  i1mach = numeric_storage_size - 1
    case (9);  i1mach = huge(1)
    case (10); i1mach = radix(x)
    case (11); i1mach = digits(x)
    case (12); i1mach = minexponent(x)
    case (13); i1mach = maxexponent(x)
    case (14); i1mach = digits(xx)
    case (15); i1mach = minexponent(xx)
    case (16); i1mach = maxexponent(xx)
    case default
      error stop 'Error in i1mach - i out of bounds'
    end select

  end function i1mach

In this one, we make heavy use of constants now in the intrinsic iso_fortran_env module, including input_unit, output_unit, error_unit, numeric_storage_size, and character_storage_size. In the Fortran 90 code, the values for I1MACH(1:4) and I1MACH(6) were totally not portable. This new one is now (almost) entirely portable.

The only remaining parameter that cannot be expressed portably is I1MACH(3), the standard punch unit. If you look at the original i1mach.f from SLATEC, there were a range of values of this parameter used by various machines (e.g. 102 for the Cray, or 7 for the IBM 360/370). Hopefully, this is not something that anybody needs nowadays, so we leave it set to 0 in the updated routine. If the Fortran committee ever adds punch_unit to iso_fortran_env, then we can update it then, and this routine will finally be finished, and the promise of a totally portable machine constants routine will finally be fulfilled.

Another interesting thing to note are I1MACH(7) (which is RADIX(1)) and I1MACH(10) (which is RADIX(1.0)). There was no I1MACH parameter for RADIX(1.0D0). There were machine architectures where I1MACH(7) /= I1MACH(10). For example, the Data General Eclipse S/200 had I1MACH(7)=2 and I1MACH(10)=16. But, it seems unlikely that there would ever be an architecture where the radix would be different for different real kinds. So maybe we are safe?

Results

On my laptop (Apple M1) with gfortran, the three routines produce the following values:

i1mach( 1) =                5
i1mach( 2) =                6
i1mach( 3) =                0
i1mach( 4) =                0
i1mach( 5) =               32
i1mach( 6) =                4
i1mach( 7) =                2
i1mach( 8) =               31
i1mach( 9) =       2147483647
i1mach(10) =                2
i1mach(11) =               24
i1mach(12) =             -125
i1mach(13) =              128
i1mach(14) =               53
i1mach(15) =            -1021
i1mach(16) =             1024

r1mach( 1) =             1.17549435E-038    (            800000 )
r1mach( 2) =             3.40282347E+038    (          7F7FFFFF )
r1mach( 3) =             5.96046448E-008    (          33800000 )
r1mach( 4) =             1.19209290E-007    (          34000000 )
r1mach( 5) =             3.01030010E-001    (          3E9A209B )

d1mach( 1) =   2.22507385850720138E-0308    (    10000000000000 )
d1mach( 2) =   1.79769313486231571E+0308    (  7FEFFFFFFFFFFFFF )
d1mach( 3) =   1.11022302462515654E-0016    (  3CA0000000000000 )
d1mach( 4) =   2.22044604925031308E-0016    (  3CB0000000000000 )
d1mach( 5) =   3.01029995663981198E-0001    (  3FD34413509F79FF )

References

• P. A. Fox, A. D. Hall and N. L. Schryer, Algorithm 528: Framework for a portable library, ACM Transactions on Mathematical Software 4, 2 (June 1978), pp. 177-188.
• David Gay and Eric Grosse, Self-Adapting Fortran 77 Machine Constants: Comment on Algorithm 528, ACM Transactions on Mathematical Software 25, 1 (March 1999), pp. 123-126.
• Bo Einarsson, d1mach revisited: no more uncommenting DATA statements Presented at the IFIP WG 2.5 International Workshop on "Current Directions in Numerical Software and High Performance Computing", 19 - 20 October 1995, Kyoto, Japan.
• An interview with Phyllis A. Fox, Conducted by Thomas Haigh on 7 and 8 June, 2005, Short Hills, New Jersey. Interview conducted by the Society for Industrial and Applied Mathematics.
• Why no punch_unit in iso_fortran_env?, Jun 18, 2022 [Fortran-lang Discourse]

Quadrature Quandary

In today's episode of "What where the Fortran dudes in the 1980s thinking?": consider the following code, which can be found in various forms in the two SLATEC quadrature routines dgaus8 and dqnc79:

K = I1MACH(14)
ANIB = D1MACH(5)*K/0.30102000D0
NBITS = ANIB

Note that the "mach" routines (more on that below) return:

• I1MACH(10) = B, the base. This is equal to 2 on modern hardware.
• I1MACH(14) = T, the number of base-B digits for double precision. This will be 53 on modern hardware.
• D1MACH(5) = LOG10(B), the common logarithm of the base.

First off, consider the 0.30102000D0 magic number. Is this supposed to be log10(2.0d0) (which is 0.30102999566398120)? Is this a 40 year old typo? It looks like they ended it with 2000 when they meant to type 3000? In single precision, log10(2.0) is 0.30103001. Was it just rounded wrong and then somebody added a D0 to it at some point when they converted the routine to double precision? Or is there some deep reason to make this value very slightly less than log10(2.0)?

But it turns out, there is a reason!

If you look at the I1MACH routine from SLATEC you will see constants for computer hardware from the dawn of time (well, at least back to 1975. It was last modified in 1993). The idea was you were supposed to uncomment the one for the hardware you were running on. Remember how I said IMACH(10) was equal to 2? Well, that was not always true. For example, there was something called a Data General Eclipse S/200, where IMACH(10) = 16 and IMACH(14) = 14. Who knew?

So, if we compare two ways to do this (in both single and double precision):

! slatec way:
 anib_real32  = log10(real(b,real32))*k/0.30102000_real32;   nbits_real32  = anib_real32
 anib_real64  = log10(real(b,real64))*k/0.30102000_real64;   nbits_real64  = anib_real64

! naive way:
 anib_real32_alt  = log10(real(b,real32))*k/log10(2.0_real32);   nbits_real32_alt  = anib_real32_alt
 anib_real64_alt  = log10(real(b,real64))*k/log10(2.0_real64);   nbits_real64_alt  = anib_real64_alt

! note that k = imach(11) for real32, and imach14 for real64

We see that, for the following architectures from the i1mach routine, the naive way will give the wrong answer:

• BURROUGHS 5700 SYSTEM (real32: 38 instead of 39, and real64: 77 instead of 78)
• BURROUGHS 6700/7700 SYSTEMS (real32: 38 instead of 39, and real64: 77 instead of 78)

The reason is because of numerical issues and the fact that the real to integer assignment will round down. For example, if the result is 38.99999999, then that will be rounded down to 38. So, the original programmer divided by a value slightly less than log10(2) so the rounding would come out right. Now, why didn't they just use a rounding function like ANINT? Apparently, that was only added in Fortran 77. Work on SLATEC began in 1977, so likely they started with Fortran 66 compilers. And so this bit of code was never changed and we are still using it 40 years later.

Numeric inquiry functions

In spite of most or all of the interesting hardware options of the distant past no longer existing, Fortran is ready for them, just in case they come back! The standard includes a set of what are called numeric inquiry functions that can be used to get these values for different real and integer kinds:

So, the D1MACH and I1MACH routines are totally unnecessary nowadays. Modern versions that are simply wrappers to the intrinsic functions can be found here, which may be useful for backward compatibility purposes when using old codes. I tend to just replace calls to these functions with calls to the intrinsic ones when I have need to modernize old code.

Updating the old code

In modern times, we can replace the mysterious NBITS code with the following (maybe) slightly less mysterious version:

 integer,parameter :: nbits = anint(log10(real(radix(1.0_wp),wp))*digits(1.0_wp)/log10(2.0_wp))

 ! on modern hardware, nbits is: 24 for real32
 !                               53 for real64
 !                              113 for real128

Where:

• wp is the real precision we want (e.g., real32 for single precision, real64 for double precision, and real128 for quad precision).
• radix(1.0_wp) is equivalent to the old I1MACH(10)
• digits(1.0_wp) is equivalent ot the old I1MACH(14)

Thus we don't need the "magic" number anymore, so it's time to retire it. I plan to make this change in the refactored Quadpack library, where these routines are being cleaned up and modernized in order to serve for another 40 years. Note that, for modern systems, this equation reduces to just digits(1.0_wp), but I will keep the full equation, just in case. It will even work on the Burroughs, just in case those come back in style.

Final thought

If you search the web for "0.30102000" you can find various translations of these old quadrature routines. My favorite is this Java one:

//  K = I1MACH(14) --- SLATEC's i1mach(14) is the number of base 2
//  digits for double precision on the machine in question.  For
//  IEEE 754 double precision numbers this is 53.

      k = 53;

//  r1mach(5) is the log base 10 of 2 = .3010299957

//      anib = .3010299957*k/0.30102000E0;

//      nbits = (int)(anib);

      nbits = 53;

Great job guys!

Acknowlegments

Special thanks to Fortran-lang Discourse users @urbanjost, @mecej4, and @RonShepard in this post for helping me get to the bottom of the mysteries of this code.

See also

• P. A. Fox, A. D. Hall and N. L. Schryer, Framework for a portable library, ACM Transactions on Mathematical Software 4, 2 (June 1978), pp. 177-188.
• David Gay and Eric Grosse, d1mach revisited: no more uncommenting DATA statements, Presented at the IFIP WG 2.5 International Workshop on "Current Directions in Numerical Software and High Performance Computing", 19 - 20 October 1995, Kyoto, Japan.
• Fun with 40 year old code, June 11, 2022, [fortran-lang Discourse].
• SLATEC, May 15, 2016 [degenerateconic.com]
  • SLATEC Machine constant routines: D1MACH, I1MACH
  • SLATEC quadrature routines: DGAUS8 , DQNC79
• Quadpack -- Modern Fortran QUADPACK Library for 1D numerical quadrature [GitHub]
• Sorting with Magic Numbers, July 5, 2014 [degenerateconic.com]
• Burroughs large systems [Wikipedia]

The New Features of Fortran 202x

The glacially slow pace of Fortran language development continues! From the smoke-filled room of the Fortran Standards Committee, the next Fortran standard is coming along. It has not yet been given an official name but is currently referred to as "Fortran 202x" (so hopefully we will see it before the end of this decade). Recall that Fortran 90 was originally referred to as "Fortran 198x".

A document (from John Reid) describing the new features is available here and is summarized below:

• The limit on line length has been increased to ten thousand characters, and the limit on total statement length (with all continuation lines) has been increased to a million characters.
• Allocatable-length character variables were added in Fortran 2003, but were ignored by all intrinsic procedures, until now! Better late than never, I suppose. In Fortran 202x, intrinsic routines that return strings can now be passed an allocatable string and it will be auto-allocated to the correct size. This is actually a pretty great addition, since it fixes an annoyance that we've had to live with for 20 years. Of course, what we really need is a real intrinsic string class. Maybe in 20 more years we can have that.
• typeof and classof. No idea what these are for. Probably a half-baked generics feature? What we really need is a real generics feature. Since that is in work for Fortran 202y I don't know why these have been added now. Probably we will discover in 10 years that these aren't good for much, but will be stuck with them until the end of time (see parameterized derived types).
• Conditional expressions. This adds the dreadful C-style (a ? b : c) conditional expression to Fortran. Somebody thought this was a good idea? This abomination can also be passed to an optional procedure argument, with a new .nil. construct to signify not present.
• Improvements to the half-baked binary, octal, and hexadecimal constants.
• Two string parsing routines (split and tokenize) were added. These are basically Fortran 90 style string routines that I guess are OK, but why bother? Or why limit to just these two? See above comment about adding a real string class.
• Trig functions that accept input in degrees have been added (e.g. sind, cosd, etc). These are already commonly available as extensions in many compilers, so now they will just be standardized.
• Half revolution trig function have also been added (acospi, asinpi, etc.). I have no idea what these are good for.
• A selected_logical_kind function was added. This was a missing function that goes along with the selected_real_kind and selected_int_kind functions that were added in Fortran 2003. Logical type parameters (e.g., logical8, logical16, etc. were also added to the intrinsic iso_fortran_env module).
• Some updates to the system_clock intrinsic.
• Some new functions in the ieee_arithmetic module for conformance with the 2020 IEEE standard.
• Update to the c_f_pointer intrinsic procedure to allow for specifying the lower bound.
• New procedures were added to iso_c_binding for conversion between Fortran and C strings. This is nice, since everyone who ever used this feature had to write these themselves. So, now they will be built in.
• A new AT format code, which is like A, but trims the trailing space from a string. Another nice little change that will save a lot of trim() functions.
• Opening a file now includes a new option for setting the leading zeros in real numbers (print them or suppress them).
• Public namelists can now include private variables. Sure, why not?
• Some updates for coarrays (coarrays are the built-in MPI like component of Fortran).
• A new simple procedure specification. A simple procedure is sort of a super pure procedure that doesn't reference any variables outside of the procedure. Presumably, this would allow some additional optimizations from the compiler.
• A new "multiple subscript" array feature. The syntax for this is just dreadful (using the @ character in Fortran for the first time).
• Integer arrays can now be used to specify the rank and bounds of an array. I tried to read the description of this, but don't get it. Maybe it's useful for something.
• Can now specify the rank of a variable using an integer constant. This is nice, and makes the rank parts of the language a little more consistent with the other parts. Again, this is something that is cleaning up a half-baked feature from a previous standard.
• Reduction specifier for do concurrent, which is putting more OpenMP-like control into the actual language (but just enough so people will still complain that is isn't enough).
• enumeration types have been added for some reason. In addition, the half-baked Fortran 2003 enum has been extended so it can now be used to create a new type. I'm not entirely sure why we now have two different ways to do this.

So, there you have it. There are some nice additions that current users of Fortran will appreciate. It will likely be years before compilers implement all of this though. Fortran 202x will be the 3rd minor update of Fortran since Fortran 2003 was released 20 years ago. Unfortunately, there really isn't much here that is going to convince anybody new to start using Fortran (or to switch from Python or Julia). What we need are major additions to bring Fortran up to speed where it has fallen behind (e.g., in such areas as generics, exception handling, and string manipulation). Or how about some radical upgrades like automatic differentiation or built-in units for variables?

References

• J. Reid, The new features of Fortran 202x, ISO/IEC JTC1/SC22/WG5 N2194, March 21, 2022
• JTC1/SC22/WG5
• INCITS PL22.3, the US Fortran Programming Language Standards Technical Committee
• The new features of Fortran 2015 (degenerateconic.com)

Packs

There are a lot of classic Fortran libraries from the 1970s to the early 1990s whose names end in "pack" (or, more specifically, "PACK"). I presume this stands for "package", and it seems to have been a common nomenclature for software libraries back in the day. Here is a list:

Note that some of these dates are my best guesses for the original release date. I can update the table if I get better information.

LAPACK is the only one of these "packs" that has seen continuous development since it began. But the majority of these codes were abandoned by their original developers and organizations decades ago, and they have been frozen ever since, a symptom of the overall decline in the Fortran ecosystem. Though in a state of benign neglect, they yet remain useful to the present day. For example, SciPy includes wrappers to MINPACK and QUADPACK (and lots of other FORTRAN 77 code). However, the only "upstream" for many of these packages is Netlib, a sourcecode graveyard from another time that has no collaborative component. So, mostly any updates anybody makes are never distributed to anyone else. Frequently, these codes are converted to other languages (e.g, by f2c) and fixes or updates are made in the C code that never get back into the Fortran code. I've mentioned before how Fortran users end up calling Fortran wrappers to C code that was originally converted from FORTRAN 77 code that was never modernized.

The problem is that these classic codes, while great, are not perfect. They are written in the obsolete FORTRAN 77 fixed-form style, which nobody wants anything to do with nowadays, but that continues to poison the Fortran ecosystem. They are littered with now-unnecessary and confusing spaghetti code constructs such as GOTOs and arithmetic IF statements. They are not easy to incorporate into modern codes (there is no package manager for Netlib). Development could have continued up to the present day, and each of these libraries could have state of the art, modern Fortran implementations of both the classic and the latest algorithms. Well it's not too late. We have the internet now, and ways to collaborate on code (e.g, GitHub). We can restart development of some of these libraries:

• Convert them to free-form source
• Clean up the formatting
• Remove obsolete and now-unnecessary clutter
• Clean up the doc strings so we can use FORD to auto-generate online documentation
• Put them in a module so there is no chance of calling them with the wrong input types
• Update them for multiple real kinds
• Add automated unit testing
• Add C APIs so that they can be called from C (and, more importantly, any language that is interoperable with C, such as Python)
• Start adding newer algorithms developed in recent decades

Consider QUADPACK. This library has been used for decades, and translated into numerous other programming languages. The FORTRAN 77 version is still used in SciPy. Note that recently some minor bugs where found in the decades-old code. The edits actually made it back to Netlib through some opaque process, but the comment was made "I do not expect a lots of edits on the package. It feels like a bug here and there." Unfortunately, this has been the perception of these classic libraries: the old Fortran code is used because it works but nobody really wants to maintain it. Well, I've started a complete refactor of QUADPACK, and have already added new features as well as new methods not present in the original library. Also consider FFTPACK and MINPACK, which were recently brought under the fortran-lang group on GitHub and development restarted as community projects. Our (ambitious) goal is to try to get SciPy to use these modernized libraries instead of the old ones. Other libraries can also move in this direction. Note: we don't have forever. SciPy recently replaced FFTPACK with a new library rewritten in C++. It's inevitable that all the old FORTRAN 77 code is going to be replaced. No one wants to work with it, and for good reason.

It's time for the Fortran community to show examples of how modern Fortran upgrades to these libraries are a better option than rewriting them from scratch in another language. With a little spit and polish, these classic libraries can have decades more life left in them. There's no need for our entire scientific programming heritage to be rewritten every few years in yet another new programming language (C, C++, Matlab, Octave, R, Python, Julia, Rust, Go, Dart, Chapel, Zig, etc, etc, etc). These libraries can be used as-is in other languages such as Python, but modernizing also makes them easier to use in actual Fortran applications. We already have the new versions available for use via the Fortran Package Manager (FPM), so adding them to your Fortran project is now a simple addition to your fpm.toml file:

[dependencies]
minpack = { git="https://github.com/fortran-lang/minpack.git" }
quadpack = { git="https://github.com/jacobwilliams/quadpack.git" }

Now isn't that better than manually downloading unversioned source files from an ftp server set up before many of the people reading this were born?

Update: See also this thread at the fortran-lang Discourse.

References

• Jack Dongarra, Gene Golub, Eric Grosse, Cleve Moler, Keith Moore, "Netlib and NA-Net: building a scientific computing community", IEEE Annals of the History of Computing, 30 (2): 30-41, 2008
• Cleve Moler, A Brief History of MATLAB, MathWorks.
• J. J. Dongarra, C. B. Moler, EISPACK: A package for solving matrix eigenvalue problems.
• J. J. Moré, B. S. Garbow, and K. E. Hillstrom, User Guide for MINPACK-1, Argonne National Laboratory Report ANL-80-74, Argonne, Ill., 1980.
• Robert Piessens, Elise de Doncker-Kapenga, Christoph W. Überhuber, David Kahaner, "QUADPACK: A subroutine package for automatic integration", Springer-Verlag, ISBN 978-3-540-12553-2, 1983

Modified Equinoctial Elements

Last time, I mentioned an alternative orbital element set different from the classical elements. Modified equinoctial elements \((p,f,g,h,k,L)\) are another alternative that are applicable to all orbits and have nonsingular equations of motion (except for a singularity at \(i = \pi\)). They are defined as [1]:

• \(p = a (1 - e^2)\)
• \(f = e \cos (\omega + \Omega)\)
• \(g = e \sin (\omega + \Omega)\)
• \(h = \tan (i/2) \cos \Omega\)
• \(k = \tan (i/2) \sin \Omega\)
• \(L = \Omega + \omega + \nu\)

Where \(a\) is the semimajor axis, \(p\) is the semi-latus rectum, \(i\) is the inclination, \(e\) is the eccentricity, \(\omega\) is the argument of periapsis, \(\Omega\) is the right ascension of the ascending node, \(L\) is the true longitude, and \(\nu\) is the true anomaly. \((f,g)\) are the x and y components of the eccentricity vector in the orbital frame, and \((h,k)\) are the x and y components of the node vector in the orbital frame.

The conversion from Cartesian state (position and velocity) to modified equinoctial elements is given in this Fortran subroutine:

subroutine cartesian_to_equinoctial(mu,rv,evec)

use iso_fortran_env, only: wp => real64

implicit none

real(wp),intent(in)               :: mu    !! central body gravitational parameter (km^3/s^2)
real(wp),dimension(6),intent(in)  :: rv    !! Cartesian state vector
real(wp),dimension(6),intent(out) :: evec  !! Modified equinoctial element vector: [p,f,g,h,k,L]

real(wp),dimension(3) :: r,v,hvec,hhat,ecc,fhat,ghat,rhat,vhat
real(wp) :: hmag,rmag,p,f,g,h,k,L,kk,hh,s2,tkh,rdv

r = rv(1:3)
v = rv(4:6)

rdv      = dot_product(r,v)
rhat     = unit(r)
rmag     = norm2(r)
hvec     = cross(r,v)
hmag     = norm2(hvec)
hhat     = unit(hvec)
vhat     = (rmag*v - rdv*rhat)/hmag
p        = hmag*hmag / mu
k        = hhat(1)/(1.0_wp + hhat(3))
h        = -hhat(2)/(1.0_wp + hhat(3))
kk       = k*k
hh       = h*h
s2       = 1.0_wp+hh+kk
tkh      = 2.0_wp*k*h
ecc      = cross(v,hvec)/mu - rhat
fhat(1)  = 1.0_wp-kk+hh
fhat(2)  = tkh
fhat(3)  = -2.0_wp*k
ghat(1)  = tkh
ghat(2)  = 1.0_wp+kk-hh
ghat(3)  = 2.0_wp*h
fhat     = fhat/s2
ghat     = ghat/s2
f        = dot_product(ecc,fhat)
g        = dot_product(ecc,ghat)
L        = atan2(rhat(2)-vhat(1),rhat(1)+vhat(2))

evec = [p,f,g,h,k,L]

end subroutine cartesian_to_equinoctial

Where cross is a cross product function and unit is a unit vector function (\(\mathbf{u} = \mathbf{v} / |\mathbf{v}|\)).

The inverse routine (modified equinoctial to Cartesian) is:

subroutine equinoctial_to_cartesian(mu,evec,rv)

use iso_fortran_env, only: wp => real64

implicit none

real(wp),intent(in)               :: mu   !! central body gravitational parameter (km^3/s^2)
real(wp),dimension(6),intent(in)  :: evec !! Modified equinoctial element vector : [p,f,g,h,k,L]
real(wp),dimension(6),intent(out) :: rv   !! Cartesian state vector

real(wp) :: p,f,g,h,k,L,s2,r,w,cL,sL,smp,hh,kk,tkh
real(wp) :: x,y,xdot,ydot
real(wp),dimension(3) :: fhat,ghat

p = evec(1)
f = evec(2)
g = evec(3)
h = evec(4)
k = evec(5)
L = evec(6)

kk      = k*k
hh      = h*h
tkh     = 2.0_wp*k*h
s2      = 1.0_wp + hh + kk
cL      = cos(L)
sL      = sin(L)
w       = 1.0_wp + f*cL + g*sL
r       = p/w
smp     = sqrt(mu/p)
fhat(1) = 1.0_wp-kk+hh
fhat(2) = tkh
fhat(3) = -2.0_wp*k
ghat(1) = tkh
ghat(2) = 1.0_wp+kk-hh
ghat(3) = 2.0_wp*h
fhat    = fhat/s2
ghat    = ghat/s2
x       = r*cL
y       = r*sL
xdot    = -smp * (g + sL)
ydot    =  smp * (f + cL)

rv(1:3) = x*fhat + y*ghat
rv(4:6) = xdot*fhat + ydot*ghat

end subroutine equinoctial_to_cartesian

The equations of motion are:

subroutine modified_equinoctial_derivs(mu,evec,scn,evecd)

use iso_fortran_env, only: wp => real64

implicit none

real(wp),intent(in)               :: mu    !! central body gravitational parameter (km^3/s^2)
real(wp),dimension(6),intent(in)  :: evec  !! modified equinoctial element vector : [p,f,g,h,k,L]
real(wp),dimension(3),intent(in)  :: scn   !! Perturbation (in the RSW frame) (km/sec^2)
real(wp),dimension(6),intent(out) :: evecd !! derivative of `evec`

real(wp) :: p,f,g,h,k,L,c,s,n,sqrtpm,sl,cl,s2no2w,s2,w

p      = evec(1)
f      = evec(2)
g      = evec(3)
h      = evec(4)
k      = evec(5)
L      = evec(6)
s      = scn(1)
c      = scn(2)
n      = scn(3)
sqrtpm = sqrt(p/mu)
sl     = sin(L)
cl     = cos(L)
s2     = 1.0_wp + h*h + k*k
w      = 1.0_wp + f*cl + g*sl
s2no2w = s2*n / (2.0_wp*w)

evecd(1) = (2.0_wp*p*c/w) * sqrtpm
evecd(2) = sqrtpm * ( s*sl + ((w+1.0_wp)*cl+f)*c/w - g*n*(h*sl-k*cl)/w )
evecd(3) = sqrtpm * (-s*cl + ((w+1.0_wp)*sl+g)*c/w + f*n*(h*sl-k*cl)/w )
evecd(4) = sqrtpm * s2no2w * cl
evecd(5) = sqrtpm * s2no2w * sl
evecd(6) = sqrt(mu*p)*(w/p)**2 + sqrtpm * ((h*sl-k*cl)*n)/w

end subroutine modified_equinoctial_derivs

The 3-element scn vector contains the components of the perturbing acceleration (e.g. from a thrusting engine, other celestial bodies, etc.) in the directions perpendicular to the radius vector, in the "along track" direction, and the direction of the angular momentum vector.

Integration using modified equinoctial elements will generally be more efficient than a Cowell type integration of the Cartesian state elements. You only have to worry about the one singularity (note that there is also an alternate retrograde formulation where the singularity is moved to \(i = 0\)).

See also

• Gooding Universal Elements [degenerateconic.com]
• modified_equinoctial_module in Fortran Astrodynamics Toolkit

References

1. M. J. H. Walker, B. Ireland, Joyce Owens, "A Set of Modified Equinoctial Orbit Elements" Celestial Mechanics, Volume 36, Issue 4, p 409-419. (1985)
2. Walker, M. J. H, "Erratum - a Set of Modified Equinoctial Orbit Elements" Celestial Mechanics, Volume 38, Issue 4, p 391-392. (1986)
3. Broucke, R. A. & Cefola, P. J., "On the Equinoctial Orbit Elements" Celestial Mechanics, Volume 5, Issue 3, p 303-310. (1972)
4. D. A. Danielson, C. P. Sagovac, B. Neta, L. W. Early, "Semianalytic Satellite Theory", Naval Postgraduate School Department of Mathematics, 1995
5. P. J. Cefola, "Equinoctial orbit elements - Application to artificial satellite orbits", Astrodynamics Conference, 11-12 September 1972.

Gooding Universal Elements

There are various different 6-element sets that can be used to represent the state (position and velocity) of a spacecraft. The classical Keplerian element set (\(a\), \(e\), \(i\), \(\Omega\), \(\omega\), \(\nu\)) is perhaps the most common, but not the only one. The Gooding universal element set [1] is:

• \(\alpha\) : twice the negative energy per unit mass (\(2 \mu / r - v^2\) or \(\mu/a\))
• \(q\) : periapsis radius magnitude (a.k.a. \(r_p\))
• \(i\) : inclination
• \(\Omega\) : right ascension of the ascending node
• \(\omega\) : argument of periapsis
• \(\tau\) : time since last periapsis passage

The nice thing about this set is that it is always defined, even for parabolas and rectilinear orbits (which other orbital element sets tend to ignore). A table from [1] shows the relationship between \(\alpha\) and \(q\) for the different types of conics:

One advantage of this formulation is for trajectory optimization purposes, since if \(\alpha\) is an optimization variable, the orbit can transition from an ellipse to a hyperbola while iterating without encountering any singularities (which is not true if semimajor axis and eccentricity are being used, since \(a \rightarrow \infty\) for a parabola and then becomes negative for a hyperbola).

Gooding's original paper from 1988 includes Fortran 77 code for the transformations to and from position and velocity, coded with great care to avoid loss of accuracy due to numerical issues. Two other papers [2-3] also include some components of the algorithm. Modernized versions of these routines can be found in the Fortran Astrodynamics Toolkit. For example, a modernized version of ekepl1 (from [2]) for solving Kepler's equation:

pure function ekepl1(em, e)
  !!  Solve kepler's equation, `em = ekepl - e*sin(ekepl)`,
  !!  with legendre-based starter and halley iterator

  implicit none

  real(wp) :: ekepl1
  real(wp),intent(in) :: em
  real(wp),intent(in) :: e

  real(wp) :: c,s,psi,xi,eta,fd,fdd,f

  real(wp),parameter :: testsq = 1.0e-8_wp

  c = e*cos(em)
  s = e*sin(em)
  psi = s/sqrt(1.0_wp - c - c + e*e)

  do
    xi = cos(psi)
    eta = sin(psi)
    fd = (1.0_wp - c*xi) + s*eta
    fdd = c*eta + s*xi
    f = psi - fdd
    psi = psi - f*fd/(fd*fd - 0.5_wp*f*fdd)
    if (f*f < testsq) exit
   end do

   ekepl1 = em + psi

end function ekepl1

The Gooding universal element set can be found in NASA's Copernicus tool, and is being used in the design and optimization of the Artemis I trajectory.

See also

• Lambert's Problem [degenerateconic.com]
• gooding_module in Fortran Astrodynamics Toolkit

References

1. R. H. Gooding, "On universal elements, and conversion procedures to and from position and velocity" Celestial Mechanics 44 (1988), 283-298.
2. A. W. Odell, R. H. Gooding, "Procedures for solving Kepler's equation" Celestial Mechanics 38 (1986), 307-334.
3. R. H. Gooding, A. W. Odell. "The hyperbolic Kepler equation (and the elliptic equation revisited)" Celestial Mechanics 44 (1988), 267-282.
4. J, Williams, J. S. Senent, and D. E. Lee, "Recent improvements to the copernicus trajectory design and optimization system", Advances in the Astronautical Sciences 143, January 2012 (AAS 12-236)
5. G. Hintz, "Survey of Orbit Element Sets", Journal of Guidance Control and Dynamics, 31(3):785-790, May 2008

Fortran Filesystem Blues

One of my major pet peeves about Fortran is that it contains virtually no high-level access to the file system. The file system is one of those things that the Fortran standard pretends doesn't exist. It's one of those idiosyncratic things about the Fortran standard, like how it uses the word "processor" instead of "compiler", and doesn't acknowledge the existence of source code files so it doesn't bother to recommend a file extension for Fortran (gotta preserve that backward compatibility just in case punch cards come back).

There are various hacky workarounds to do various things that poor Fortran programmers have had to use for decades. Basically, all you have is OPEN, CLOSE, READ, WRITE, and INQUIRE. Here are a few examples:

Deleting a file

Here's a standard Fortran routine that can be used to delete a file:

function delete_file(name) result(istat)

  implicit none

  character(len=*),intent(in) :: name
  integer :: istat

  integer :: iunit

  open(name=name,newunit=iunit,status='OLD',iostat=istat)
  if (istat==0) close(iunit,status='DELETE',iostat=istat)

end function delete_file

As you can see, it's just a little trick, using a feature of CLOSE to delete a file after closing it (but first, we had to open it). Of course, note that the error codes are non-standard (the Fortran standard also doesn't consider this information important and lets the different compilers do whatever they want -- so of course, they all do something different). And of course, there is no exception handling in Fortran either (a post for another time).

Creating a directory

There is absolutely no standard ability in Fortran to create or delete a directory. Again, Fortran basically pretends that directories don't exist. Note that the Intel Fortran Compiler provides a super useful non-standard extension of the INQUIRE statement to allow it to be used to get information about directories. It's a pretty ridiculous state of affairs (Fortran added a bazillion IEEE routines in Fortran 2018 for some reason that nobody needed, but it still doesn't have something like this that everybody has needed for decades). Intel's IFPORT portability module provides many useful (non-standard) routines for accessing the file system (for example DELFILESQQ for deleting files and DELDIRQQ for deleting a directory). I use these all the time and the fact that they are non-standard and not present in other compilers is a major source of annoyance.

For some file or directory operations, you can always resort to using system calls, and thus have to provide different methods for different platforms (of course Fortran provides no standard way to get any information about the platform, so you have to resort to non-standard, possibly compiler-specific, preprocessor directives to do that). For example, to create a directory you could use:

subroutine make_directory(name)

  implicit none

  character(len=*),intent(in) :: name

  call execute_command_line ('mkdir '//name)

end subroutine make_directory

That one was easy because "mkdir" works on macOS, Window, and Linux. See previous post about getting command line calls into strings, which can also be useful for some things like this.

Getting a list of files

How about getting a list of all the files that match a specific pattern? Again, this can be done if you are using the Intel compiler using the IFPORT module GETFILEINFOQQ routine:

function get_filenames(pattern, maxlen) result(list)

  use ifport

  implicit none

  character(len=*),intent(in) :: pattern
  integer,intent(in) :: maxlen
  character(len=maxlen),dimension(:),allocatable :: list

  integer(kind=int_ptr_kind()) :: handle
  type(file$infoi8) :: info
  integer :: length

  allocate(list(0))
  handle = file$first
  do
    length = GETFILEINFOQQ(trim(pattern), info, handle)
    if ((handle==file$last) .or. (handle==file$error)) exit
    list = [list, info%name]
  end do

end function get_filenames

The file$infoi8 type is some super-weird non-standard Intel thing. Note that this example only returns the file names, not the full paths. To get the full path is left as an exercise to the reader. Also note that Fortran doesn't provide a good string class, so we just set a maximum string length as an argument to this function (but note that Intel is only returning a 255-character string anyway).

Final thoughts

There are various libraries out there that can do some of this. For example, M_system (a Fortran module interface for calling POSIX C system routines). Hopefully, a comprehensive set of filsystem routines will eventually make it into the Fortran Standard Library.

See also

• Portability Library Routines [Intel]
• getfileinfoqq -- Intel Portability Function that returns information about the specified file. [Intel]
• Interface to POSIX I/O API [Fortran stdlib issue]

Atmosphere Models

The drag force magnitude on a spacecraft can be computed using the following equation:

Which can be easily implemented in the following Fortran function:

pure function drag(density, v, area, cd)

    use iso_fortran_env, only: wp => real64

    implicit none

    real(wp) :: drag !! drag force magnitude (N)
    real(wp), intent(in) :: density !! atmospheric density (kg/m^3)
    real(wp), intent(in) :: v       !! relative velocity magnitude (m/s)
    real(wp), intent(in) :: area    !! spacecraft cross-sectional area (m^2)
    real(wp), intent(in) :: cd      !! spacecraft drag coefficient

    drag = 0.5_wp * density * v**2 * area * cd

end function drag

The density \(\rho\) is computed using an atmosphere model. Here is a listing of some atmosphere model codes available in Fortran:

• 1976 Standard Atmosphere
• INPE-atmosphere-models -- My archive of models originally from this page (which now seems to be gone). Includes five models:
  • Jacchia 70
  • Jacchia-Roberts
  • Jacchia 77
  • LaFontaine-Hughes
  • Jacchia-Lineberry
• MSIS86
• MSISE90
• NRLMSISE00
• NRLMSIS 2.0
• Earth Global Reference Atmospheric Model 2010 (Earth GRAM 2010)

See also

• Fox & Mcdonald, "Introduction To Fluid Mechanics", Wiley
• Drag Coefficient [Wikipedia]
• U.S. Standard Atmosphere, 1976, U.S. Government Printing Office, Washington, D.C., 1976.
• ModelWeb Catalogue and Archive [NASA GSFC]
• W. W. Vaughan, "Guide to Reference and Standard Atmospheric Models", AIAA G-003C-2010, January 2010

Great Circle

If we assume that the Earth is a sphere of radius \(r\), the shortest distance between two sites (\([\phi_1,\lambda_1]\) and \([\phi_2,\lambda_2]\)) on the surface is the great-circle distance, which can be computed in several ways:

Law of Cosines equation:

This equation, while mathematically correct, is not usually recommended for use, since it is ill-conditioned for sites that are very close to each other.

Using the haversine equation:

The haversine one is better, but can be ill-conditioned for near antipodal points.

Using the Vincenty equation:

This one is accurate for any two points on a sphere.

Code

Fortran implementations of these algorithms are given here:

Law of Cosines:

pure function gcdist(r,lat1,long1,lat2,long2) &
              result(d)

implicit none

real(wp) :: d !! great circle distance from 1 to 2 [km]
real(wp),intent(in) :: r     !! radius of the body [km]
real(wp),intent(in) :: long1 !! longitude of first site [rad]
real(wp),intent(in) :: lat1  !! latitude of the first site [rad]
real(wp),intent(in) :: long2 !! longitude of the second site [rad]
real(wp),intent(in) :: lat2  !! latitude of the second site [rad]

real(wp) :: clat1,clat2,slat1,slat2,dlon,cdlon

clat1 = cos(lat1)
clat2 = cos(lat2)
slat1 = sin(lat1)
slat2 = sin(lat2)
dlon = long1-long2
cdlon = cos(dlon)

d = r * acos(slat1*slat2+clat1*clat2*cdlon)

end function gcdist

Haversine:

pure function gcdist_haversine(r,lat1,long1,lat2,long2) &
              result(d)

implicit none

real(wp) :: d !! great circle distance from 1 to 2 [km]
real(wp),intent(in) :: r     !! radius of the body [km]
real(wp),intent(in) :: long1 !! longitude of first site [rad]
real(wp),intent(in) :: lat1  !! latitude of the first site [rad]
real(wp),intent(in) :: long2 !! longitude of the second site [rad]
real(wp),intent(in) :: lat2  !! latitude of the second site [rad]

real(wp) :: dlat,clat1,clat2,dlon,a

dlat  = lat1-lat2
clat1 = cos(lat1)
clat2 = cos(lat2)
dlon  = long1-long2

a = sin(dlat/2.0_wp)**2 + clat1*clat2*sin(dlon/2.0_wp)**2
d = r * 2.0_wp * asin(min(1.0_wp,sqrt(a)))

end function gcdist_haversine

Vincenty:

pure function gcdist_vincenty(r,lat1,long1,lat2,long2) &
              result(d)

implicit none

real(wp) :: d !! great circle distance from 1 to 2 [km]
real(wp),intent(in) :: r     !! radius of the body [km]
real(wp),intent(in) :: long1 !! longitude of first site [rad]
real(wp),intent(in) :: lat1  !! latitude of the first site [rad]
real(wp),intent(in) :: long2 !! longitude of the second site [rad]
real(wp),intent(in) :: lat2  !! latitude of the second site [rad]

real(wp) :: c1,s1,c2,s2,dlon,clon,slon

c1   = cos(lat1)
s1   = sin(lat1)
c2   = cos(lat2)
s2   = sin(lat2)
dlon = long1-long2
clon = cos(dlon)
slon = sin(dlon)

d = r*atan2(sqrt((c2*slon)**2+(c1*s2-s1*c2*clon)**2), &
    (s1*s2+c1*c2*clon))

end function gcdist_vincenty

Test cases

Using a radius of the Earth of 6,378,137 meters, here are a few test cases (using double precision (real64) arithmetic):

Close points

The distance between the following very close points \(([\phi_1,\lambda_1], [\phi_2,\lambda_2]) =([0, 0.000001], [0.0, 0.0])\) (radians) is:

Houston to New York

The distance between the following two points \(([\phi_1,\lambda_1], [\phi_2,\lambda_2]) =([29.97, -95.35], [40.77, -73.98])\) (deg) is:

Antipodal points

The distance between the following two antipodal points \(([\phi_1,\lambda_1], [\phi_2,\lambda_2]) = ([0, 0], [0.0, \pi/2])\) (radians) is:

Nearly antipodal points

The distance between the following two nearly antipodal points \(([\phi_1,\lambda_1], [\phi_2,\lambda_2]) = ([10^{-8}, 10^{-8}], [0.0, \pi/2])\) (radians) is:

Other methods

For a more accurate result, using an oblate-spheroid model of the Earth, the Vincenty inverse geodetic algorithm can be used (the equation above is just a special case of the more general algorithm when the ellipsoidal major and minor axes are equal). For the Houston to New York case, the difference between the spherical and oblate-spheroid equations is 282 meters.

See also

• GCDIST, a Fortran 77 version of the Law of Cosines formula, 1996.
• J. Williams, Direct and Inverse, January 31, 2016 [degenerateconic.com]
• GIS FAQ Q5.1: Great circle distance between 2 points [Movable Type Scripts]

Visual Studio Code + Fortran

With the right plugins, Microsoft Visual Studio Code can be turned into a very good modern Fortran IDE. Here are some of my favorites:

• FORTRAN IntelliSense (hansec.fortran-ls). To use this, you must pip install fortran-language-server.
• vscode-modern-fortran-formatter (yukiuuh.vscode-modern-fortran-formatter). To use this, you must pip install fprettify.
• Modern Fortran (krvajalm.linter-gfortran)
• Fortran Breakpoint Support (ekibun.fortranbreaker)

Historically, good full-featured IDEs for modern Fortran have been hard to find. Intel Fortran integrates with the full MS Visual Studio, and I used that for many years. But, except for syntax highlighting and automatic determination of compile order, it is basically terrible. I always have to disable the "IntelliSense" features since it brings the interface to a crawl (it's been like this for years and they don't seem to care enough to fix it). Unfortunately, Intel's excellent Fortran debugger also only works from within Visual Studio, so if you need to use it, you are stuck in that environment.

I've pretty much converted to use VSCode now for all Fortran coding (on both Mac and Windows). In the past, I have also used TextWrangler, Sublime Text, and Atom.

See also:

• vscode-icons -- A nice set of icons for various file formats, although the Fortran icon is terrible. I submitted a pull request to use the new one from fortran-lang.org. As of Oct 2021, it has yet to be merged.
• "Parse File…" with lagging visual studio [Intel Fortran Forum]. Note: I believe one of my comments on this post was censored by the admins. I distinctly remember asking if we were a bunch of suckers for continuing to give money to a multi-billion dollar corporation (Intel) when they can't be bothered to fix their defective product.
• Fortran IDEs at fortran-lang.org.
• Is Visual Studio Code Really The Best Code Editor?, February 28, 2021. [tabnine.com]