MasconCube

Official codebase for the paper MasconCube: Fast and Accurate Gravity Modeling with an Explicit Representation.

MasconCube is a fast and accurate framework for modeling gravitational fields of irregular celestial bodies. It provides an explicit mascon-based representation, enabling efficient training, validation, and comparison against state-of-the-art methods such as GeodesyNets and PINN-GM.

Installation

conda env create -f environment.yml
conda activate masconcube

Or, if you want to install also development dependencies:

conda env create -f environment_dev.yml
conda activate masconcube

Development dependencies include packages for linting and contributing to the project.

Reprouducing the results from the paper

1. Download the 3D meshes from darioizzo/geodesyNets/3dmeshes and copy them inside the data/3dmeshes folder. For more information, see the data README.
2. Generate the ground-truth mascon models in the data/ground_truths folder by running the following script:

   python scripts/generate_ground_truth.py

3. Generate the validation datasets in the data/val_datasets and data/test_datasets folders by running the following script:

   python scripts/generate_val_datasets.py

4. Train MasconCubes with the following command:

   python scripts/train_cubes_all.py [--gpus <gpu1> <gpu2> ...]

5. Train GeodesyNets with the following command:

   python scripts/train_geodesynet_all.py [--gpus <gpu1> <gpu2> ...]

6. Train PINN-GM III with the following command:

   python scripts/train_pinn_all.py [--gpus <gpu1> <gpu2> ...]

7. Evaluate the models and produce plots using the provided notebooks.

Note that steps 5 and 6 are required only to compare the results with previous state-of-the-art methods, and they might take a long time to run. You can skip them if you are only interested in MasconCube. If you want to run them, multiple GPUs are recommended, so that you can run them in parallel. The --gpus argument allows you to specify which GPUs to use for training.

Training on single asteroids

If you want to run the training on single asteroids, you can use the scripts scripts/train.py, scripts/train_geodesynet.py, and scripts/train_pinn.py. For example, to train MasconCube on eros_uniform, you can run:

python scripts/train.py eros_uniform

MasconCube trainings also support TensorBoard logging (development dependencies required). You can run the following command to start TensorBoard:

tensorboard --logdir runs

And then enable logging in the training script by passing the --tensorboard argument:

python scripts/train.py eros_uniform --tensorboard

License

The code is released under the Apache 2.0 license.

Citation

If you find this repository useful, please kindly consider citing the following paper:

@misc{fanti2025masconcube,
      title={MasconCube: Fast and Accurate Gravity Modeling with an Explicit Representation}, 
      author={Pietro Fanti and Dario Izzo},
      year={2025},
      eprint={2509.08607},
      archivePrefix={arXiv},
      primaryClass={astro-ph.EP},
      url={https://arxiv.org/abs/2509.08607}, 
}

Aknowledgements

This codebase is based on the following open-source projects. We thank their authors for making the source code publically available.

• geodesyNets