Discussion:
[Users] thorns providing citations
Frank Loeffler
8 years ago
Permalink
Hi,

This is a proposal about how thorns can provide citations of resources
(papers, ...), and how Cactus could use those to output a list of 'used
resources'.

I would like to make this the topic for the October-hack-a-day, if I
find one or two more interested people. It shouldn't take more than that
day to get something working. Before that, however, we should discuss
what this should actually look like.

The rest of this email is details about the proposal. If you are not
interested, you can stop reading here. If you are, please let us know
what you think after you've read it.


While I said 'resources', I mean citations, usually to papers, but
really it could be anything.

There is also the question of how to cite something, and in the
following I am assuming bibtex entries, as that is what most likely most
people would find useful.

First of all, thorns would need to have a way to provide citations.
Thorns already provide all kinds of stuff, and most of that is
'announced to Cactus' in configuration.ccl, so let's use that, and not
create yet another .ccl file:

PROVIDES CITATION name AS "xyz"
PROVIDES CITATION name IN bibtex filename, relative to thorn dir
REQUIRES CITATION name

This gives each citation a name, and would use that in a key-value table
as key, where the value is a bibtex-entry, verbatim and (in this
proposal) unparsed by Cactus. The name should ideally be the same as the
key in the bibtex entry, but it doesn't need to be. We could decide to
enforce equality, but then would have to parse the entry / bib file.

This mechanism would only provide a way to define citations, and use
them if you can be sure another thorn already provides it (REQUIRES).

The next question would be how to tell Cactus that a certain citation
should be included in the output, and what that output should look like.
We already have two "classes" of citations in the ET: "requested" and
"optional". "requested" citations should be cited whenever that piece of
code was used, while "optional" are, well, optional. Thus, we should
have a way to provide those. Also, whether a citation should be included
might depend on parameters (we do have a few examples of those), and not
just thorn activation. Thus, I believe the best way to include this is

schedule.ccl:

CITATION name
CITATION OPTIONAL name

These could be stand-alone, top-level statements, or be inside
if-blocks, similar to, e.g., STORAGE statements. These statements only
use the name of the citation as defined above - not the actual citation
string itself.

Once a citation is marked as 'being used', it will not be 'unmarked'
within that run.

Using this information, Cactus will then provide output regarding which
citations are used, by which thorn, and of which type (requested,
optional). This output is updated (overwritten) each time something is
added (but waits until the regular thorn-activation sequence is
completed).

The output should, at least, consist of:
- one bibtex file containing all known entries
- two lists of keys, in machine readable format: requested/optional
- machine readable information about which thorn requested what how

Of course, depending on our wishes, part of this can and should be
configurable via parameters.

Frank Loeffler
Steven R. Brandt
8 years ago
Permalink
...
Would people really remember to put the REQUIRES statement in their
thorn? I'd prefer something more automatic.
...
I think I'd prefer to have the citation come with a comment that makes
it clear when it should be included in a paper.
...
I'd prefer one bibtex file only. There could be a key inside each entry
identifying the thorn.

--Steve
Post by Frank Loeffler
Of course, depending on our wishes, part of this can and should be
configurable via parameters.
Frank Loeffler
_______________________________________________
Users mailing list
http://lists.einsteintoolkit.org/mailman/listinfo/users
Frank Loeffler
8 years ago
Permalink
Post by Steven R. Brandt
Post by Frank Loeffler
This mechanism would only provide a way to define citations, and use
them if you can be sure another thorn already provides it (REQUIRES).
Would people really remember to put the REQUIRES statement in their
thorn? I'd prefer something more automatic.
If we wouldn't have REQUIRES, a missing citation (or typo) could only be
reliably detected at runtime, with a par-file at hand. We could check if
all mentioned entries from schedule.ccl do exist, but they might not,
e.g., by using

if (ThornActive(blafasel)) {
CITATION xyz
}

where thorn xyz provides that citation, but is not compiled in and not
intended to be used for a particular user. Of course, this is quite a
special, constructed case.

We could prefer simple over robust, and don't do any compile-time checks
concerning existence, and generate "warning entries" for used, but not
defined entries at runtime.
Post by Steven R. Brandt
Post by Frank Loeffler
CITATION name
CITATION OPTIONAL name
I think I'd prefer to have the citation come with a comment that makes
it clear when it should be included in a paper.
We could add a human-readable description like this as special key
inside the bibtex file if we are going to parse that anyway.
Post by Steven R. Brandt
Post by Frank Loeffler
- one bibtex file containing all known entries
- two lists of keys, in machine readable format: requested/optional
- machine readable information about which thorn requested what how
I'd prefer one bibtex file only. There could be a key inside each
entry identifying the thorn.
I did mean only one bibtex file. I value the other files because
without, scripts that only want one kind of key would need to parse
bibtex syntax just for that. While bibtex is machine-readable, it isn't
straightforward to quickly write a filter for entries that contain a
certain key.

Frank

Loading...