Pythia 8 Guidelines for Code Contributions and Authorship
Contributions to the Pythia 8 source code
On the Pythia web pages and documentation, contributions to the development of Pythia 8 are acknowledged in four categories (described in more detail under the respective headings below):
- Bug fixes and incremental updates;
- Further Contributions;
- Former Authors;
Contributions of the first type are documented in the program’s Update History. The latter three are also acknowledged on the front page of Pythia’s HTML manual.
Bug fixes and incremental updates
Many people have contributed to bug fixes and incremental updates of Pythia 8. Such contributions are usually acknowledged in direct connection with the corresponding entry in Pythia’s Update History.
Frequent examples are reports by users of unexpected “suspicious behaviour” encountered in the context of some specific study. This is often due to the use case simply going beyond Pythia’s intended limits of applicability, but does sometimes point to genuine bugs in the program. We are grateful for such reports, which can help to weed out bugs that would otherwise live on in the code, or can help us document Pythia’s intended uses and limits of applicability better.
Other examples include more technical reports that a piece of code fails to conform to a specified standard, produces undefined behaviour in some context, or violates thread safety, for instance. Such reports have even occasionally been accompanied by explicit patches that correct the problem. When that is possible, it is a major help, vastly reducing the workload on our side.
In cases where further examination is likely to be needed by the authors, standalone main programs that reproduce the behaviour are crucially important, so we request that such programs be included when users report suspicious behaviour, along with relevant input cards/settings and/or (small) examples of input files, as appropriate.
Further Contributions are typically results of standalone research or development projects by non-authors, deemed of sufficient interest and quality to include in the main Pythia distribution, assuming the contributors want to do this and are willing to help make it happen. Further Contributions can also represent permission to include into Pythia a piece of code that exists separately, with permission to distribute that code together with Pythia.
After the contribution has been merged into Pythia (including relevant documentation), the original contributor is “off the hook”; the Pythia team agrees to assume the main responsibility for further maintenance and support of the contributed code, and unless agreed otherwise there is no expectation of continued development on the part of the original contributor. They may of course still be consulted in case of questions.
Further Contributions can span from extended student projects to smaller, more targeted code contributions such as interfaces to external libraries.
Authors, in addition to making substantial contributions to the code, also accept ongoing active responsibility for the development, support, and maintenance of Pythia. Each author agrees to one or more areas of scientific, technical, and/or administrative responsibilities, for which they are the main go-to person, so that:
- user questions are followed up on in a timely manner;
- bug reports and recommendations for optimisations are pursued;
- relevant parts of the code are kept up to date in terms of maintenance, validation (including relevant components of the CI/CD test suite) and general code organisation, including responsibility for handling and validating any merge requests pertaining to it, and following up on any relevant gitlab issues;
- code reviews of/for other areas of the code are actioned;
- relevant documentation (mainly the HTML manual and update notes) is kept up to date;
- relevant example programs are kept up to date (and extended/adapted if the need arises);
- shared administrative tasks pertaining to Pythia are taken care of, eg in the context of organising Pythia meetings, updating and maintaining the Pythia web site, etc.
Collegiate, collaborative, and inclusive conduct is expected at all times.
When joining the collaboration, a new author’s area of responsibility is typically limited to the substantial contribution that qualifies them for authorship in the first place. In such cases, authorship would typically be considered after the substantial contribution has passed review by a (non-supervisor) collaboration member and is being included in a public release, though individual cases may vary.
Since Pythia is a collaborative effort, the need sometimes also arises for authors to accept responsibilities for further areas, e.g., when new “further contributions” are added, or when current authors leave the collaboration.
Changes to the author list and to areas of responsibilities for existing authors are discussed with and agreed upon collectively by the Triumvirate (see Organisation below).
Former Authors are authors whose active/ongoing responsibilities have ceased and who have therefore effectively left the collaboration.
There is no expectation of continued development on the part of the former author, though they may be contacted in case of questions.
Typically, former authors are expected to remain on the author list for a period of roughly a year after leaving the collaboration, but final decisions will be made between the Triumvirate and the leaving author.
Authors can of course also request to leave the collaboration at any time.
Benefits of Contributing to Pythia 8
This section collects some brief points highlighting beneficial aspects of being a Pythia contributor.
A vessel for bringing your science to others. Implementing a physics model in a publicly accessible event generator like Pythia means it will be available for others to use and base their own studies on.
Science that you can use and build on. A sustained engagement means you can build on your previous work (and that of your collaborators) to make further advances with higher degrees of complexity / accuracy / detail / efficiency.
Improving Pythia for others. Since Pythia is used by many people for many purposes, improving it by even a simple bug fix has follow-on effects improving it for the next person(s) to use it. Likewise, tuning and similar studies can help ensure that lessons learned are passed on.
Review of code, modelling assumptions, implementation, and documentation. If you are a contributor, your contribution will be reviewed, both in terms of physics and in terms of code quality and implementation, documentation, and examples. It will also be subjected to validation checks. All of this may improve it, and often you learn in the process. As a Pythia author, you will both review and be reviewed. This also exposes you to new physics ideas, new algorithmic tools and tricks, new ways of writing and interfacing codes, new mathematical techniques, etc.
Collaboration network. You can engage in collaborative science projects with the Pythia team and participate in Pythia meetings and events, and/or with the wider MC community. The latter is represented in particular by the multi-institute MCnet collaboration which also includes the Herwig, Sherpa, and MadGraph_aMC@NLO projects, in addition to Rivet and a few other, more specialised projects.
Opportunities for talks. Sometimes we receive external requests for Pythia talks at workshops and at summer schools, which are allocated among the author team and contributors.
Opportunities for training. For example, attending event-generator summer schools and/or doing studentship projects with Pythia authors.
Opportunities for teaching experience. For example, giving summer school lectures and/or leading Pythia tutorials.
Organisation of Pythia 8
The Pythia collaboration has the following three main administrative / managerial roles (also called the “triumvirate”): Spokesperson, Codemaster, and Webmaster. There can also be deputies to these roles. Their main duties are as follows:
- Represent the collaboration
- Call up meetings and organise the agenda.
- Assign user issues on the “releases” git branch, and act as back stop for them to ensure they do not fall through the cracks.
- Coordinate presentations and funding proposals.
- Maintain a general overview of developments across Pythia, coordinate where relevant, and also catch up on issues.
- Maintain overview of long-term directions, and strategic opportunities in the field.
- Term limit provisionally one year, with possible extension, reviewed annually.
- A deputy can be assigned by the collaboration to help with specific duties, e.g. calling meetings and assigning user issues.
- Torbjörn Sjöstrand is honorary spokesperson for life.
- Assign issues and code reviews on main development git repository and handle merge requests;
- Take care of releases and code quality;
- Term limits provisionally one year, with possible extension, reviewed annually;
- One or two deputies can be assigned by the collaboration to help manage the workload;
- For help-desk (releases) issues, the spokespeople are the primary line of defence; codemaster can choose to step in on individual questions, and can be consulted by spokespeople.
- Host web pages for online manual and GitLab;
- Take care of the Pythia domain name;
- Make sure that online manual is up-to-date;
- Keep track of papers, talks, lectures, and tutorials
Experimental Contact Persons In addition to the roles above, Pythia Collaboration members can act as designated contacts for specific experiments. Typically, this involves actively engaging with the MC and analysis groups in the corresponding experiment to understand if there are Pythia-related issues that should be brought up with the Pythia Collaboration, and facilitating the propagation of new Pythia developments back to the experiment.
- Regular monthly meetings
- All Authors can attend, review code status and issues, input experimental collaborations;
- Also other people can attend by invitation from Authors, accepted by the Spokesperson. These would normally not vote on decision making matters.
- Decide for code releases;
- Continue discussions from the week-long meeting;
- Present physics talks, and hands-on sessions;
Coordinate Pythia participation in training events.
Annual Pythia weeks
- All authors can attend, focus on physics and long-term plans;
- Discuss about larger projects (e.g. manuals);
- Review appointments of Triumvirate.
- Management meetings (triumvirate)
- Limited attendance to Triumvirate;
- Decisions for new Authors and leaving Authors;
- Assigning and keeping an eye on issues for Authors;
- Suggestions for new code releases.