Contribution Guide

🔴 This is a draft of contribution guide, all suggestions/corrections are welcome.

Introduction

Py-ORBIT is an open source code for simulating particle accelerators. More information can be found at Py-ORBIT website. The code is organized in several repositories to allow flexibility of development for different institutions. All repositories are placed in one GitHub organization - PyORBIT-Collaboration. Generally speaking we encourage to use triangular workflow, but it's up to repository's maintainer how new code is merged in existing code base.

Project structure

The main parts of Py-ORBIT are:

1. Core contains C++ and Python code that provides core functionality. This part is required for running Py-ORBIT code.
2. Extensions provide additional functionality that is not required to run simulations. Usually extensions deal with less typical physics processes (e.g. laser stripping) or interface Py-ORBIT to other accelerator codes (e.g. PTC).
3. Site specific repositories hold code (usually Python scripts) that are specific to particular accelerator installations.
4. Examples repository collects different example of Py-ORBIT usage, they can be machine specific or generalized.

Contributing to Core

You should contribute to the core if your modification is applicable to general simulation of particle accelerator. For core we will try to limit number of dependencies as much as possible. Examples of possible candidates could be:

• Modification that deals with simulation of a generic node (RF gap, bending magnet etc).
• Any bug fix to existing code.
• Performance improvements.
• Simulation of specific particle distribution that is of general interest. Since the core is the most essential part of the code, all contributions have to pass hopefully rigorous checking and testing before merging your code upstream. The only way to to merge your code is creating a pull request. Your pull request has to pass all tests - this is done automatically by continuous integration service. As of now the only test we run is building core and running a test script, but we plan to add more tests that will cover actual simulation results. You cannot push your changes to master.

Contributing to Extensions

If you came up with new functionality that is of general interest you should consider implementing it as an extension. Examples of possible candidates could be:

• New physics process that implements interaction with material.
• GUI that plots results of simulation.
• Glue code that interfaces Py-ORBIT to another software.

Sometime you will need to create a new repository. A good example to follow is PTC extension. One can copy the makefile and modify it accordingly. Current convention assumes that extension will be compiled in a dynamic library that will be placed in $ORBIT_ROOT/lib. It could be useful to implement automated testing for the new extension to make sure that modifications to the core didn't break the extension. It's up to extension's maintainer to enforce any policy for modifying the extension.

Site specific code

We encourage all users of Py-ORBIT to share their code. It's important to separate application scripts and core development. So newcomers will be able to learn form existing project. It's up to site maintainer to enforce any policy for modifying the site specific code. An example of site specific code can be found in JPARC repository.