# include RePriMand in the ET

Issue #2551 resolved
Roland Haas created an issue

RePrimAnd https://github.com/wokast/RePrimAnd implements and advanced con2prim scheme and EOS that could be used in the ET.

This will most likely be a multi-step process with first only the library and its C++ interface being available followed eventually by a Cactus native interface and possible wrappers for existing codes that use EOS_Omni. There is also a design challenge in defining, once more, the set of primitives that ID thorns provide and con2prim must compute.

The public RePrimAnd repository contains a prototype for an external libraries thorn. It is located in the folder

ET_interface/thorns/RePrimAnd

The thorn already contains an archive of the library. It built successfully with the latest ET release (Lorentz). It depends on other external libraries: BOOST and GSL (the latter is likely to be dropped in the future). For the time being, it also requires the meson build system to be installed on the build host. This could be replaced by a make with moderate effort.

The only documentation of the thorn so far is a README file pointing to the repository, which links to the latest online documentation of the library.

1. reporter

Also see #2414 for a similar framework.

2. reporter

I would note that the non-commercial CC licenses are incompatible with GPL, since GPL compatibility requires that commercial use is allowed. This is not much of an issue for us since we never distribute a derived object, but eg the compiled Cactus executable (or a tarball of the full source code) cannot be distributed if it contains both CC-NC and GPL code since the licenses conflict (but one can still use it internally of course). See https://www.gnu.org/licenses/license-list.en.html#CC-BY-NC

Noted. Not going to change the license unless there is a real problem with CC4.

3. reporter

We currently state (http://einsteintoolkit.org/contribute.html) that

All components must be distributed under an open source licence so that others can use these components without restrictions (except as mandated by scientific integrity), can modify and improve them as necessary, and can pass on these modifications to their collaborators as they see fit.

We suggest GPL compatible and link to the the OSI’s definition page (https://opensource.org/licenses/category). I do not think that the issue has come up before. So for not I will take note and bring it with in some initial review for discussion in the ET call (the questions whether this is problem). It certainly would be problem if this was intended to be a “Cactus*” thing since all “Cactus*” must be LGPL so that explicitly derived object can be distributed without exposing all code. This is for example why AEILocalInterp is in Numerical and not CactusNumerical (the author explicitly requires it to be GPL and not LGPL). The ET however does not have that LGPL requirement.

4. reporter
5. reporter

No progress reviewing this yet. Should have time this week.

6. reporter

https://github.com/wokast/RePrimAnd/pull/8 has simple Makefile that avoids meson and ninja. It is only good for use in the ET ExternalLibray environment and is in the “dist” directory of the ET_Interface thorn. Ie does not touch the library proper.

7. reporter
• changed status to open

Thanks for providing the Makefile. I have checked that it compiles on my system and merged the pull request.

8. reporter

One unrelated issue to mention: since git uses a delta compression between revisions in the repo, you likely will (eventually) have a smaller repository by storing an uncompressed tarball (just *.tar) rather than a compressed tarball (*.tar.gz) in the repo (since git can run a useful diff even on the tar file, but no on a compressed file since compression makes the whole file change if a single byte a the beginning of the tarfile changes). This is not much of an issue for the ET since it can (and will) use svn checkout to get just the ET_interface thorn and only the trunk copy (and not the full version history git would do).

9. reporter

Is there way to use sphinx to generate TeX documentation that could be included in the ET? This could be a once-per-release step, but I would prefer having offline TeX files rather than always referring to online HTML files if possible..

Sphinx can do Latex. If this can be embedded in other latex documents is a different question. Is the idea to have an offline copy distributed with the ET or also to embed this into the ET latex documentation? If it is just the offline aspect, I’d prefer to embed the html doc which are not that big either.

10. reporter

Ideally there would be a TeX file documetnation.tex that can be used in the usual ET manner. Ie:

• is included in the online doumentation auto-generated from the documentation.tex files
• can be use to create a local thornguide / thorndoc using the respective make targets
• can be used with cd FOO/doc; pdflatex documentation.tex to create documentation.pdf. The goal here is uniformity of available documentation to avoid situations where some thorns might have “README.md”, others “index.html”, and more again “Start.docx”.

Said tex file should ideally be using the sphinx generated tex files, but some thorns instead just point to the actual documentation (eg. https://www.einsteintoolkit.org/thornguide/WVUThorns/Baikal/documentation.html). This approach, of course, is a poor substitute for the real thing.

Really good documetnation is eg in https://www.einsteintoolkit.org/thornguide/CactusNumerical/MoL/documentation.html and there’s of course also empty documentation eg https://www.einsteintoolkit.org/thornguide/CactusUtils/Vectors/documentation.html which should be avoided.

11. reporter

Pull request with minimal docs is here: https://github.com/wokast/RePrimAnd/pull/15

Pull request with review comments is here: https://github.com/wokast/RePrimAnd/pull/14

• the HDF5 files in EOS will not be visible to the user right now (they are in the tarball but not copied anywhere where the user can find them). Should they be?
• the Python script to create HDF5 EOS files should be provided in exe/sim/foo.py

12. reporter

Sphinx’s LaTeX output option produces broken LaTeX for me:

! Extra alignment tab has been changed to \cr.
<template> }\$\hfill \endtemplate

l.2819 ... \epsilon}(\rho, \theta, Y_e)\end{split}


This with RePrimAnd hash 6ec1def "Merge pull request #13 from rhaas80/public" of RePrimAnd sphinx 4.2.0-5, doxygen 1.9.1 on my Debian bookworm box.

There seems to be no way to produce LaTeX output in sphinx that could be included in the Cactus documentation.tex file (ie that does not include the document preamble and documentclass).

13. reporter

The deep freeze for the release is going to be very soon. The documentation should go into public as soon as possible. Please also take a look at the review comments.

I’ve been collecting commits in the development repo (In the public repo I’d like a condensed history meaningful to users), including the tex documentation from the pull request. I’ll push to public today.

I also went through the review comments (very useful, thanks again). I have commented inside the pull request on some concerns that are non-issues as far as I can tell. The rest will be addressed in today's push. Due to time constraints, for the time being I will not fix all the error messages that should include the offending numbers in the message. This will probably go in the next release, which will also provide a TOV solver. Hope this is ok for the current ET release.

I have just pushed recent changed to the public repository. Those include:

• minor changes triggered by code review
• updated natural constants and option to use own
• tex documentation, now pointing to new online location on github pages
• minor changes to Roland’s thorn building (no library version in archive name, .tar instead .tar.xz)
• Placed copy of EOS file creation Python module in src/utils
• fixing build problems of standalone library (not relevant for ET thorn)

The online documentation is now on https://wokast.github.io/RePrimAnd/index.html

I have checked that ET builds from scratch with a fresh clone of the public repo on my system.

Once we decide to include a given commit (hopefully this one) I will tag it as a release so it gets archived on Zenodo as well, with corresponding DOI. The DOI could then be mentioned in the ET release notes.

14. reporter

You also can request up to one (not a hard rule but strongly encouraged) citations that people should use when using RePrimAnd, as well as multiple (any number, but you may provide indication under which circumstances which ones are suggested) suggested citations. Those will be listed on: https://www.einsteintoolkit.org/citation.html

To provide the citation please provide bibtex entries to be included in einsteintoolkit.bib (in the manifest repo) that should look something like this:

@Misc{Kranc:web,
suggested-for ="McLachlan/ML_BSSN",
key =          {Kranc},
title =        {{Kranc}: {Kranc} Assembles Numerical Code},
url =          {http://kranccode.org/},
}

@Misc{EinsteinToolkit:2021_05,
requested-for ={EinsteinToolkit},
author       = {Zachariah Etienne and Steven R. Brandt and Peter Diener and William E. Gabella and Miguel Gracia-Linares and Roland Haas and Atul Kedia and Miguel Alcubierre and Daniela Alic and Gabrielle Allen and Marcus Ansorg and Maria Babiuc-Hamilton and Luca Baiotti and Werner Benger and Eloisa Bentivegna and Sebastiano Bernuzzi and Tanja Bode and Gabriele Bozzola and Brockton Brendal and Bernd Bruegmann and Manuela Campanelli and Federico Cipolletta and Giovanni Corvino and Samuel Cupp and Roberto De Pietri and Harry Dimmelmeier and Rion Dooley and Nils Dorband and Matthew Elley and Yaakoub El Khamra and Joshua Faber and Toni Font and Joachim Frieben and Bruno Giacomazzo and Tom Goodale and Carsten Gundlach and Ian Hawke and Scott Hawley and Ian Hinder and E. A. Huerta and Sascha Husa and Sai Iyer and Daniel Johnson and Thorsten Kellermann and Andrew Knapp and Michael Koppitz and Pablo Laguna and Gerd Lanferman and Frank L{\"o}ffler and Joan Masso and Lars Menger and Andre Merzky and Jonah Maxwell Miller and Mark Miller and Philipp Moesta and Pedro Montero and Bruno Mundim and Andrea Nerozzi and Scott C. Noble and Christian Ott and Ravi Paruchuri and Denis Pollney and David Radice and Thomas Radke and Christian Reisswig and Luciano Rezzolla and David Rideout and Matei Ripeanu and Lorenzo Sala and Jascha A Schewtschenko and Erik Schnetter and Bernard Schutz and Ed Seidel and Eric Seidel and John Shalf and Ken Sible and Ulrich Sperhake and Nikolaos Stergioulas and Wai-Mo Suen and Bela Szilagyi and Ryoji Takahashi and Michael Thomas and Jonathan Thornburg and Malcolm Tobias and Aaryn Tonita and Paul Walker and Mew-Bing Wan and Barry Wardell and Leonardo Werneck and Helvi Witek and Miguel Zilh{\~a}o and Burkhard Zink and Yosef Zlochower},
title        = {The Einstein Toolkit},
month        = may,
year         = 2021,
note         = {To find out more, visit http://einsteintoolkit.org},
publisher    = {Zenodo},
version      = {The "Lorentz" release, ET\_2021\_05},
doi          = {10.5281/zenodo.4884780},
url          = {https://doi.org/10.5281/zenodo.4884780}
}

@article{Noble:2005gf,
requested-for = {WVUThorns/IllinoisGRMHD},
author         = "Noble, Scott C. and Gammie, Charles F. and McKinney,
Jonathan C. and Del Zanna, Luca",
title          = "{Primitive variable solvers for conservative general
relativistic magnetohydrodynamics}",
journal        = "Astrophys. J.",
volume         = "641",
pages          = "626-637",
doi            = "10.1086/500349",
year           = "2006",
eprint         = "arXiv:astro-ph/0512420",
SLACcitation   = "%%CITATION = ASTRO-PH/0512420;%%",
}


the preferred entry format is SPIRES-like, in that SPIRES keys are strongly recommended but we list all authors. The top of einsteintoolkit.th explains the convention: https://bitbucket.org/einsteintoolkit/manifest/raw/master/einsteintoolkit.bib

@article{Kastaun:2020uxr,
author = "Kastaun, Wolfgang and Kalinani, Jay Vijay and Ciolfi, Riccardo",
title = "{Robust Recovery of Primitive Variables in Relativistic Ideal Magnetohydrodynamics}",
eprint = "2005.01821",
archivePrefix = "arXiv",
primaryClass = "gr-qc",
doi = "10.1103/PhysRevD.103.023018",
journal = "Phys. Rev. D",
volume = "103",
number = "2",
pages = "023018",
year = "2021"
}


15. reporter

Applied as git hash b786700 "einsteintoolkit.bib: add Kastaun:2020uxr" of manifest

16. reporter

Closing this ticket. More work to do for full inclusion but good enough for now.