Citing Otter
============

If you use Otter in a scientific publication, please cite Chongbing Qu and
Dominik Kraus, *Otter*, version 0.2.4, computer software (2026),
https://github.com/otter-hed/otter.

The same metadata are provided in ``CITATION.cff`` and through GitHub's
**Cite this repository** menu. Model references document scientific
provenance; they are not additional software-citation requirements.

The complete reference registry is kept in the repository root:
:download:`CITATIONS.md <../../CITATIONS.md>`.

Runtime citation API
--------------------

Electronic, ionic, workflow, and mixture configuration objects expose a
three-style provenance API:

.. code-block:: python

   config.citation(style="plain")   # readable references
   config.citation(style="bibtex")  # copyable BibTeX entries
   config.citation(style="cite")    # an unevaluated ``\\cite{...}``

The keys are available as ``config.citation_keys``. They are resolved from
the packaged ``otter/literature.bib`` file, so installed workflows do not
need the documentation dependencies. The ``otter.literature`` module also
provides ``bibliography_entries`` and the three formatting helpers for
applications that need to build their own reports.

.. autoclass:: otter.literature.CitationMixin
   :members: citation

.. autofunction:: otter.literature.bibliography_entries

.. autofunction:: otter.literature.write_citations_markdown

Reference rules for contributors
--------------------------------

* Add a stable key, authors, year, and DOI to ``src/otter/literature.bib``
  before introducing a new literature reference.
* Put ``:cite:p:`` or ``:cite:t:`` beside equations and model descriptions in
  RST, and add a ``References`` section with the canonical key to Python
  docstrings.
* Expose the selected keys through ``citation_keys`` for every selectable
  model. Test ``plain``, ``bibtex``, and ``cite`` output.
* Identify Otter-specific discretization, regularization, and convergence
  choices separately; a paper describing a physical model does not validate
  every numerical implementation detail.

The HTML bibliography below is generated by Sphinx from the same BibTeX file.
It is therefore the authoritative rendered view of the key registry.