.. _readme:

AstroGeoFit Documentation
=========================

.. image:: https://img.shields.io/badge/python-3.11%2B-blue
    :alt: Python Version

.. image:: https://img.shields.io/badge/license-GPLv3-blue
    :alt: License

Table of Contents
-----------------

-  :ref:`description`
-  :ref:`features`
-  :ref:`downloading_the_package`
-  :ref:`installation_explanation`
-  :ref:`get_started_with_astrogeofit`
-  :ref:`library_section_explanation`
-  :ref:`results`
-  :ref:`citations`
-  :ref:`license_explanation`
-  :ref:`authors_contributors`
-  :ref:`acknowledgments`
-  :ref:`requests`

.. _description:

Description
-----------

AstroGeoFit is an Astronomical Calibration Tool for the Geological Time Scale,
developed as part of the AstroGeo project funded by the European Research Council (ERC)
(AstroGeo-885250), led by Jacques Laskar (CNRS). The software is licensed under the GNU GPL 3.0 License.
AstroGeoFit combines a genetic algorithm with Bayesian methods to calibrate geological time
from sedimentary records, aiming to optimally tune geological time series.

.. _features:

Features
--------

- Genetic algorithm optimization for the determination of time-depth transfer function.
- Bayesian framework for probabilistic analysis.
- Extraction of the astronomical components from the sedimentary record.
- Support for user-defined priors and stratigraphic constraints.
- Visualization tools for tuning diagnostics.

.. _prerequisites_message:

Pre-Requisits
-------------

Before downloading the package, it is recommended to check the pre-requisits of the tool: :ref:`prerequisites`.

.. _downloading_the_package:

Download `AstroGeoFit`
----------------------

This tool can be downloaded from the main web page of the `AstroGeo` project, or from the following link: https://www.astrogeo.eu/wp-content/astrogeofit/astrogeofit_latest.zip .

The files that the user can expect to find are listed in the following section :ref:`download_the_package`

.. _installation_explanation:

Installation and Updates
------------------------

In order to facilitate the installation and the updating of the package, a guide is provided in the section :ref:`installation_updates`.

.. _get_started_with_astrogeofit:

Get Started with `AstroGeoFit`
------------------------------

In order to get a first contact with `AstroGeoFit` and see how it works, we developed a step-by-step guide with an execution example which can be found in the
:ref:`get_started_agf` section. If it's is the first time that you use this tool, we strongly recommend to follow it.


.. _library_section_explanation:

`AstroGeoFit` Python Library
----------------------------

The functions of `AstroGeoFit` can be also executed as a **Python library**. There is a guide on how to use
the tool as a library in the section :ref:`library_documentation`.

.. _results:

Results
-------

This tool shows the results of the analysis using diferent pre-established plots.

A detailed explanation of these figures that can be obtained as results can be found in :ref:`visualization-results`

.. _citations:

Citation
--------

AstroGeoFit will be released alongside the following publication.  
Please cite this article when using the AstroGeoFit software in scientific work:

Hoang, N., Laskar, J., Hara, N., Wu, Y., Sultanov, A., Sinnesael, M., Westerhold, T., & Bujons, P.  
**AstroGeoFit: A Genetic Algorithm and Bayesian approach for the Astronomical Calibration of the Geological Timescale**  
*Paleoceanography and Paleoclimatology*, 2025.

.. _license_explanation:

License
-------

This software is licensed under the GNU GPL 3.0.s. See :ref:`license`.

Copyright (c) 2025 CNRS

Lead author : Jacques Laskar

.. _authors_contributors:

Authors and Contributors
------------------------

**Primary code developers**:

- Nam Hoang – Algorithm design and initial prototype
- Pau Bujons – Software engineering and clean implementation

**Scientific contributors**:

- Jacques Laskar – Project lead, conceptualization, methodology, documentation
- Nam Hoang - Methodology, Bayesian framework and statistical analysis
- Yujing Wu – Testing, stratigraphic data analysis and documentation
- Nathan Hara – Bayesian framework and statistical analysis
- Arsen Sultanov – Bayesian framework, statistical analysis and prototyping

.. _acknowledgments:

Acknowledgements
----------------

This software was developed as part of the ERC-funded **AstroGeo** project
with support from the **European Research Council** (ERC) under the European Union’s Horizon 2020
research and innovation program (Advanced Grant AstroGeo-885250).

.. _requests:

Requests and Inquiries
----------------------

For any request or inquirie please address to: `astrogeofit@astrogeo.eu <mailto:astrogeofit@astrogeo.eu>`_.

.. footer:: Requests/Inquiries: astrogeofit@astrogeo.eu