Kalman-filter based paleomagnetic modeling
==========================================

.. note::
  :code:`paleokalmag` is still under heavy development and interfaces may change without notice until version 1.0.0 is released.


.. image:: dipole_holocene.png
  :alt: xkcd like figure showing the dipole moment over the holocene

:code:`paleokalmag` is a python package for Kalman-filter based modeling of the
paleomagnic field. It can be seen as the paleomagnetic extension of the 
`Kalmag-model <https://doi.org/10.1186/s40623-020-01295-y>`_.

The typical workflow consists of three steps:

1. Set up the data
#. Set up the model
#. Run the model

All steps are demonstrated in notebooks :ref:`here <examples-label>`. If you want to dive deeper, have a look at the :ref:`package documentation <pdoc-label>`.


If you use paleokalmag, please cite the corresponding paper

.. admonition:: Citation

  | **Schanner**, M. A.; **Korte**, M.; **Holschneider**, M. (2022)  
  | ArchKalmag14k: A Kalman-filter based
  | global geomagnetic model for the Holocene
  | *JGR Solid Earth* (127)
  | e2021JB023166
  |
  | |doi-shield|

.. toctree::
   :hidden:

   examples
   package_documentation
   CHANGELOG


Installation
------------
.. note::
  paleokalmag depends on `pymagglobal <https://sec23.git-pages.gfz-potsdam.de/korte/pymagglobal>`_. You have to install it, before running the install command.


:code:`paleokalmag` is distributed via the PyPI registry of the corresponding repository. It can be installed using

.. code-block:: bash

  $ pip3 install paleokalmag --extra-index-url https://public:2kNQxC-mxfHj4qfMJL6z@git.gfz-potsdam.de/api/v4/projects/1793/packages/pypi/simple

paleokalmag further depends on `pybind11 <https://pybind11.readthedocs.io>`_. Depending on your build system, you may have to install cmake, before you can run the :code:`pip3 install ...` command. In our experience, cloning the repository and installing it via :code:`pip install -e .` worked best, especially under Windows.

License
-------
GNU General Public License, Version 3, 29 June 2007

Copyright (C) 2021 Helmholtz Centre Potsdam GFZ, German Research Centre for Geosciences, Potsdam, Germany

paleokalmag is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

paleokalmag is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
   

.. |doi-shield| image:: https://img.shields.io/badge/DOI-10.1029%2F2021JB02316-blue.svg
		      :target: https://doi.org/10.1029/2021JB023166


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
* `Repository <https://git.gfz-potsdam.de/sec23/korte/paleokalmag>`_