Zig Library

[thomas992]

I wanted to make this issue to talk about my intention to convert the astronomy engine to Zig to be used as a library for zig-gamedev. I hope to be able to make an accurate solar system in a game environment, that could be used as an HTML background with WebAssembly. First I want to render a solar system, then I want to render it from somewhere on Earth's ocean. Later on I would like to be able to simulate entities anywhere in space, outside the typical rendering, so you could launch missiles from the moon, see it on a display within the game, and then it lands on the map. Or simulate ICBMs circling the planet, satellites. I was hoping to call it zspace and have it specifically integrated for this game engine.

[meshula]

@cosinekitty fwiw, Zig would get my vote for another language to add. I do a lot of math prototyping in zig because I like the way it handles precision issues For example, it forces you to ensure that the variable you assign after multiplying two integers has sufficient bits to hold the result. There's a number of things it does like that that have exposed issues in my numerics code that I hadn't spotted.

[cosinekitty]

Hi @thomas992, that sounds like a great project!

Fair warning: supporting a new programming language in this Astronomy Engine repo is a large task. Expect about a month of daily work to complete this. I'm not sure that's what you mean, but if so, I wrote the following. If you just want to create your own fork, some of the following will probably still be useful, but you can ignore some of the painful parts.

Here are some tips:

First make sure you can get the developer's build process working for the 5 currently supported languages. This build process isn't needed by developers who use Astronomy Engine, but it is required for contributors. It is highly recommended to do your development work in either Linux or Mac. Windows is possible, but it does not include unit testing of demo programs. In the case of Windows, at least when you push changes, GitHub Actions will run tests for all 3 operating systems and help you catch issues you missed.

The build process does three important things:

• Runs a code generator that creates certain lookup tables. All of the original source code exists as "templates" in the directory generate/template. This is where you actually develop the code for all the languages. The generated source code is written to child directories beneath generate/source. Warning: it is easy to lose work by accidentally editing the generated source; the next time you run the build process, it will overwrite everything you did!
• Extracts API documentation from source code comments and generates GitHub flavored Markdown from it. This is where all the online documentation comes from. This is actually one of the more annoying parts, because I end up having to cobble together something different to make each language work.
• Runs exhaustive unit tests. There are unit tests that verify correctness against data sets from JPL Horizons and other authoritative sources, within tolerance limits. There are also unit tests that compare calculations from the multiple languages against each other for strict agreement. Finally, there are tests that all of the demo programs produce the exact expected output for selected test cases.

Once you get the existing build process to run to completion without errors, then you are ready to begin adding support for a new language.

You will create the template file in the generate/template directory as mentioned above. Then I can help you update the code generator to produce data tables in Zig format. I will be happy to help with this part, with guidance from you about Zig syntax, which I don't know anything about.

You can follow along with this checklist of Astronomy Engine functions. The 97 functions listed under the "C/C++" column are the minimal complete set. There are extra optional functions in other languages that have more advanced features like iterators/enumerators.

You will need to implement the functions, implement their unit tests, figure out how to create an online documentation generator, and port the demo programs. For a lot of this, fortunately, you can follow the pattern of the existing implementations. I will be happy to provide guidance and advice along the way.

On my end, to support a new language, I would want assurances that you would be around as needed when bugs or new feature requests come along. At the very least, we would need to work together to update the developer guide so I know what tools to install on all 3 operating systems. While working on this, it would also be the ideal time to update the GitHub Actions configuration file to install tools and run Zig unit tests automatically by GitHub Actions.

I totally understand if this is more than you bargained for. I'm also posting this so people get a better picture of what it's like for me to add a new language, and why I'm often less eager than people would hope to take on all the work by myself, especially when I don't know anything about the language or its toolset.

You might decide you just want to port a small subset of Astronomy Engine to Zig for your own purposes, in your own separately-maintained repo, and that would be great too.

What do you think about all this?

[thomas992]

Have to see how it goes over the next few days. The build process makes sense to me, probably because I have not looked long enough though lol. I could supply the markdown documentation generator. Making proper documentation is one of my primary objectives for the project, to show the mathematical formulas used in the function, with references to the data. Exposing the formulas and data sources adds more scrutiny which results in better formulas from the community. There is a lot of this I do not understand just yet but I hopefully make some significant progress without an understanding of planetary theory, trig. Zig is capable of doing WebAssembly I think it will become the primary languages in mobile and desktop. I am developing on Linux first. I will probably make a fork in a few days after I made some ground.

[cosinekitty]

@thomas992 I'm closing this as an issue, but feel free to create a discussion if/when you want to work on a Zig port for Astronomy Engine.

I also wonder if calling the existing C/C++ version of Astronomy Engine from Zig, as described here, might be a better option. When adding a new language, porting the astronomy calculations is only part of the work. Most of the work is adding documentation and unit tests. It may be less hassle for everyone if the Astronomy Engine repo contains external declarations for the C structs and functions that can be used from Zig, rather than native Zig code.

I'm sure there are factors I don't know about yet, but I thought I would at least mention this as a possibility.