fix citations:

David Hendriks performed many tests of the code, by using it in his binary_c-python project https://gitlab.com/binary_c/binary_c-python, and helped with documentation.

External code from and probably modified in *libcdict*:

* uthash by Troy Hanson 

* uthash by Troy Hanson and Arthur O'Dwyer

* ryu by Ulf Adams 

* jsmn by Serge Zaitsev

* fast double parser by Daniel Lemire

Originally part of the binary_c project https://gitlab.com/binary_c/

*libcdict* uses uthash, (c) 2003-2018, Troy D. Hanson

*libcdict* uses uthash, (c) 2003-2018, Troy D. Hanson, maintained by Arthur O'Dwyer

http://troydhanson.github.com/uthash/

Please see its usage licence in uthash.h.

## Contribution to the software

Should you wish to contribute to the software, please submit new code via libcdict's gitlab page via its merge-requests feature.

Should you wish to contribute to the software, please submit bug reports and new code via libcdict's gitlab page https://gitlab.com/rob.izzard/libcdict through the Issues and Merge Requests sections, respectively. You can contact the authors through gitlab 

## Report issues or problems with the software

  adsnote = {Provided by the SAO/NASA Astrophysics Data System}

}

@misc{uthash,

@misc{uthash_github,

  author = {Hansen, T.~D.},

  title = {{uthash}: a hash table for {C} structures},

  year = {2022},

  publisher = {GitHub},

  journal = {GitHub repository},

  url = {https://troydhanson.github.io/uthash/}

}

@misc{jsmn,

@misc{jsmn_homepage,

  author = {Zaitsev, S.},

  title = {{jsmn}, a minimalistic {JSON} parser in {C}},

  year = {2023},

  url = {https://zserge.com/jsmn/}

}

@misc{jsmn_github,

  author = {Zaitsev, S.},

  title = {{jsmn}, a minimalistic {JSON} parser in {C}},

  year = {2022},

  publisher = {GitHub},

  journal = {GitHub repository},

  url = {https://github.com/zserge/jsmn}

}

@misc{fastdoubleparser,

@misc{fastdoubleparser_github,

  author = {Lemire, D.},

  title = {{fast_double_parser}: $4\times$ faster than \texttt{strtod}},

  year = {2022},

  publisher = {GitHub},

  journal = {GitHub repository},

  url = {https://github.com/lemire/fast_double_parser}

}

      doi = {10.1002/spe.2984}

}

@misc{ryu,

@misc{ryugithub,

  author = {Adams, U.},

  title = {{Ry\={u}} & {Ry\={u}} {Printf}},

  year = {2022},

  publisher = {GitHub},

  journal = {GitHub repository},

  url = {https://github.com/ulfjack/ryu}

}

keywords = {performance, string, float}

}

@misc{adams:2019,

  title={Ryū revisited: printf floating point conversion},

  volume={3},

  url={http://dx.doi.org/10.1145/3360595},

  DOI={10.1145/3360595},

  number={OOPSLA},

  journal={Proceedings of the ACM on Programming Languages},

  publisher={Association for Computing Machinery (ACM)},

  author={Adams, U.},

  year={2019},

  month=oct,

  pages={1–23},

  language={en}

}

@misc{meson,

@misc{meson_github,

  author = {J. Pakkanen},

  title = {The {Meson} Build System},

  year = {2022},

  url = {https://github.com/mesonbuild/meson}

}

@misc{ninja,

@misc{meson_homepage,

  author = {J. Pakkanen},

  title = {The {Meson} Build System},

  year = {2022},

  url = {https://mesonbuild.com/}

}

@misc{ninja_github,

  author = {Martin, E.},

  title = {{Ninja}, a small build system with a focus on speed.},

  year = {2022},

  publisher = {GitHub},

  journal = {GitHub repository},

  url = {https://github.com/mesonbuild/meson}

  url = {https://github.com/ninja-build/ninja}

}

@misc{ninja_homepage,

  author = {Martin, E.},

  title = {{Ninja}, a small build system with a focus on speed.},

  year = {2022},

  url = {https://ninja-build.org/}

}

@misc{bokeh,

  title = {{Bokeh}, Interactive Data Visualization.},

@misc{bokeh_homepage,

  author = {{Bokeh~homepage}},

  title = {Bokeh},

  year = {2022},

  url = {https://bokeh.org/},

}

@misc{bokeh_github,

  author= {{Bokeh~GitHub}},

  title = {Bokeh},

  year = {2022},

  publisher = {GitHub},

  journal = {GitHub repository},

  url = {https://gitlab.com/rob.izzard/libcdict/-/tree/}

}

@misc{glibhashtable,

  author = {Glib docs},

@misc{glib_gitlab,

  author = {GLib~GitLab},

  title = {GLib},

  year = {2023},

  publisher = {Gnome},

  journal = {GitLab repostiory},

  url = {https://gitlab.gnome.org/GNOME/glib},

}

@article{Hendriks:2023,

doi = {10.21105/joss.04642}, url = {https://doi.org/10.21105/joss.04642}, year = {2023}, publisher = {The Open Journal}, volume = {8}, number = {85}, pages = {4642}, author = {D. D. Hendriks and R. G. Izzard}, title = {binary_c-python: A Python-based stellar population synthesis tool and interface to binary_c}, journal = {Journal of Open Source Software} }

@misc{binary_c_python_gitlab,

title = {binary_c-python},

year = {2023},

journal = {GitLab repostiory},

url = {https://gitlab.com/binary_c/binary_c-python/},

}

@misc{glib_manual_hashtable,

  author = {GLib~documentation},

  title = {\textsc{glib} hash tables},

  year = {2022},

  publisher = {Gitlab},

  journal = {\textsc{glib} official documentation},

  url = {https://docs.gtk.org/glib/callback.HashFunc.html}

}

@ARTICLE{izzard:2023,

       author = {{Izzard}, R.~G. and {Jermyn}, A.~S.},

        title = "{Circumbinary discs for stellar population models}",

      journal = {\mnras},

     keywords = {accretion, accretion discs, stars: AGB and post-AGB, binaries: general, circumstellar matter, stars: wind, outflows},

         year = 2023,

        month = may,

       volume = {521},

       number = {1},

        pages = {35-50},

          doi = {10.1093/mnras/stac2899},

       adsurl = {https://ui.adsabs.harvard.edu/abs/2023MNRAS.521...35I},

      adsnote = {Provided by the SAO/NASA Astrophysics Data System}

}

 No newline at end of file

    corresponding: true

    affiliation: 1

  - name: David D. Hendriks

    orcid: 0000-0002-8717-6046

    affiliation: 1

  - name: Daniel P. Nemergut

    affiliation: 1

affiliations:

 - name: Department of Physics, University of Surrey, Guildford, GU2 7XH, Surrey, UK

 - name: Department of Physics, School of Mathematics and Physics, University of Surrey, Guildford, GU2 7XH, Surrey, UK

   index: 1

date: 28 July 2022

bibliography: paper.bib

# Summary

A common requirement in science is to store and share large sets of simulation data in an efficient, nested, flexible and human-readable way. Such datasets contain number counts and distributions, i.e. histograms and maps, of arbitrary dimension and variable type, e.g. floating-point number, integer or character string. Modern high-level programming languages like Perl and Python have associated arrays, knowns as dictionaries or hashes, respectively, to fulfil this storage need. Low-level languages used more commonly for fast computational simulations, such as C and FORTRAN, lack this functionality. We present a `libcdict`, a C dictionary library, to mostly solve this problem. `Libcdict` provides C and FORTRAN application programming interfaces (APIs) to native dictionaries, called `cdict`s, and functions for `cdict` to load and save these as JSON and hence for easy interpretation in other software and languages like Perl, Python and R. 

A common requirement in science is to store and share large sets of simulation data in an efficient, nested, flexible and human-readable way. Such datasets contain number counts and distributions, i.e. histograms and maps, of arbitrary dimension and variable type, e.g. floating-point number, integer or character string. Modern high-level programming languages like Perl and Python have associated arrays, knowns as dictionaries or hashes, respectively, to fulfil this storage need. Low-level languages used more commonly for fast computational simulations, such as C and Fortran, lack this functionality. We present a `libcdict`, a C dictionary library, to mostly solve this problem. `Libcdict` provides C and Fortran application programming interfaces (APIs) to native dictionaries, called `cdict`s, and functions for `cdict` to load and save these as JSON and hence for easy interpretation in other software and languages like Perl, Python and R. 

# Statement of need

Users of high-level languages such as Perl or Python have access to associated-array data structures through dictionaries and hashes, respectively. These allow arbitrary data types to be stored in array-like structures. These are in turn accessed through key-value pairs which allow the value to be a further, nested associated array, allowing arbitrary nesting of data. Compiled low-level languages, like C and FORTRAN, are more suited to high-speed and repeated calculations typical in science. These languages lack native associated-array functionality. While there are pure hash-table solutions out there, such as `glib` [@glibhashtable] and `uthash` [@uthash], these do not combine a simple API for setting and adding to nested structures, a small library footprint, fast input and output, and standardised JSON output to easily interface with other languages and tools. `libcdict` provides an API for such functionality which allows `cdict`s to be nested in `cdict`s, hence arbitrarily-nested dictionaries of variables in C just as in Perl or Python. 

Users of high-level languages such as Perl or Python have access to associated-array data structures through dictionaries and hashes, respectively. These allow arbitrary data types to be stored in array-like structures. These are in turn accessed through key-value pairs which allow the value to be a further, nested associated array, allowing arbitrary nesting of data. Compiled low-level languages, like C and Fortran, are more suited to high-speed and repeated calculations typical in science. These languages lack native associated-array functionality. While there are pure hash-table solutions out there, such as `glib` [@glib_manual_hashtable;@glib_gitlab] and `uthash` [@uthash_github], these do not combine a simple API for setting and adding to nested structures, a small library footprint, fast input and output, and standardised JSON output to easily interface with other languages and tools. `libcdict` provides an API for such functionality which allows `cdict`s to be nested in `cdict`s, hence arbitrarily-nested dictionaries of variables in C just as in Perl or Python. 

`libcdict` is written in C and provides an API through a set of C macros. Nested `cdict` structures have values in them set with a single line of code. `libcdict` has been used for the last year in the `binary_c` single- and binary-star population nucleosynthesis framework [@izzard:2004; @izzard:2006; @izzard:2009; @izzard:2018] which computes the evolution of millions of single- and binary-stellar systems in only a few hours using its `binary_c-python` Python frontend.  We provide `libcdict` as open-source code on Gitlab subject to the GPL3. `libcdict` also has a comprehensive test suite run through its configuration program `cdict-config`.

`libcdict` is written in C and provides an API through a set of C macros. Nested `cdict` structures have values in them set with a single line of code. `libcdict` has been used for the last year in the `binary_c` single- and binary-star population nucleosynthesis framework [@izzard:2004; @izzard:2006; @izzard:2009; @izzard:2018; @izzard:2023] which computes the evolution of millions of single- and binary-stellar systems in only a few hours using its `binary_c-python` Python frontend [@Hendriks:2023].  We provide `libcdict` as open-source code on Gitlab subject to the GPL3. `libcdict` also has a comprehensive test suite run through its configuration program `cdict-config`.

# Using libcdict

`libcdict` is flexible but pragmatic. Keys to `cdict`s can be any C scalar or pointer. Values can be scalars, pointers, arrays or other `cdict`s, but arrays must be of a single C type. Values can store metadata of arbitrary type. Pointer values are optionally garbage collected when a `cdict` is freed. A set of API macros provides simple nesting facilities so that placing a value in a nested location given a list of keys is a simple task for the C programmer. Issues such as C variable typing are automatically handled for the user.

Variables are internally hashed using `uthash` [@uthash]. `libcdict` provides a custom JSON output function and inputs JSON using `jsmn` [@jsmn]. Floating-point input and output uses `fast double parser` [@fastdoubleparser; @lemire:2021] and `Ryū` [@ryu; @adams:2018], respectively, both of which are considerably faster than equivalent C library functions. `libdict` allows customizable floating-point accuracy for output and when comparing floating-point numbers, e.g. during sorting of key or variable lists. 

Variables are internally hashed using `uthash` [@uthash_github]. `libcdict` provides a custom JSON output function and inputs JSON using `jsmn` [@jsmn_github; @jsmn_homepage]. Floating-point input and output uses `fast double parser` [@fastdoubleparser_github; @lemire:2021] and `Ryū` [@ryugithub; @adams:2018; @adams:2019], respectively, both of which are considerably faster than equivalent C library functions. `libdict` allows customizable floating-point accuracy for output and when comparing floating-point numbers, e.g. during sorting of key or variable lists. 

Installation uses `meson` [@meson] and `ninja` [@ninja]. `libcdict` has been tested with the GCC (10.3.0) and Clang (12.0.0) compilers.

Installation uses `meson` [@meson_github; @meson_homepage] and `ninja` [@ninja_github; @ninja_homepage]. `libcdict` has been tested with the GCC (10.3.0) and Clang (12.0.0) compilers.

# `libcdict` in stellar-population statistics calculations

To overcome this problem, `binary_c` internally generates an associative-array `cdict` in native C. This `cdict`, and the stellar statistics it contains, is filled inside the `binary_c` simulation as each star is simulated. Generation of the stellar-population data in the `cdict` is efficient because it is only in C and communication with the frontend (Python) code is kept to a minimum. The `cdict`'s dataset is output \emph{only once}, as human-readable JSON easily understood by Perl or Python, at the end of the simulation. Large simulations are often split across clusters of machines using `binary_c-python`. The data from each run are stored as JSON chunks then merged in Python when the final run completes. The overhead involved in this joining is small compared to the effort of simulating the stars: the goal of `libcdict` has thus been achieved.

We provide an interactive example made with `binary_c` and `binary_c-python` using `libcdict` in its `examples` directory [@cdictexamples]. The `libcdict` JSON output of a Hertzsprung-Russell diagram, the most important diagnostic plot in stellar astrophysics, is plotted using `Bokeh` [@bokeh] to provide immediate access to nested data sets.

We provide an interactive example made with `binary_c` and `binary_c-python` using `libcdict` in its `examples` directory [@cdictexamples]. The `libcdict` JSON output of a Hertzsprung-Russell diagram, the most important diagnostic plot in stellar astrophysics, is plotted using `Bokeh` [@bokeh_github; @bokeh_homepage] to provide immediate access to nested data sets.

# Acknowledgements

RGI acknowledges funding by STFC grants ST/L003910/1 and ST/R000603/1. DDH acknowledges funding by UKRI/UoS grant H120341A. We thank the authors of software used by `libcdict`, especially Troy Hanson for `uthash`, Ulf Adams and the `Ryū` team, Serge Zaitsev and the `jsmu` team, and Daniel Lemire for `fast double parser`.

RGI acknowledges funding by STFC grants ST/L003910/1 and ST/R000603/1. DDH acknowledges funding by UKRI/UoS grant H120341A. We thank the authors of software used by `libcdict`, especially Troy Hanson and Arthur O'Dwyer for `uthash`, Ulf Adams and the `Ryū` team, Serge Zaitsev and the `jsmu` team, and Daniel Lemire for `fast double parser`.

# References