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}(https://pyorbit-collaboration.github.io/). 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.

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. 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. We will try to limit ourself to as few external dependency as possible.

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.

Most likely 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.

PS q q q q q q

Site specific code