Contribution Guide

Thank you for considering to contribute to PyOpticL! The following guide will explain how contributions can be made.

Register as a collaborator:

If you are using PyOpticL to design a research apparatus at another institution, please reach out to be registered as an official collaborator!

email: rniffenegger at umass dot edu

Join the Discord!

You can join with the link here: https://discord.gg/neykWFc5 Please tell us what you are working on and what you are trying to achieve with PyOpticL - you may find other researchers already working on a similar goal :) Please ensure you are using 2FA on Discord.

---

Types of contributions

Baseplates

Researchers using PyOpticL as a tool to build specific baseplates that may be isolated from a larger system

PyOpticL is a helpful tool for developing space efficient and performant optical subsystems. We recognize that some labs will leverage PyOpticL to achieve a limited scope of goals (e.g. a single baseplate to lock the frequency of a laser; a single baseplate to shutter a laser with an AOM, etc…)

In these cases, we are happy to add baseplate designs to a folder within the GitHub repository for 'one-off' designs. In order to push such a baseplate design, please consider the following guidelines:

1. Check for duplication: Ensure your design is not already covered by an existing example

2. Avoid custom parts: Use standard, modular components. PyOpticL's mission is to provide highly modular layout tools and a reliance on highly custom parts and mounts goes directly against its main purpose!

3. Submit changes via fork: if you need to modify optomech.py, do so in a fork and submit a pull request once tested. ( See Modifying optomech.py below)

4. Maintain Modularity: Every part should be a distinct element to ensure modularity and compatibility with other baseplate elements. Groups of elements automatically become a new baseplate!

5. Follow best practices:

   • Align with the optical table grid (Imperial or Metric)
   • Include an optical 'passthrough' so that plates can be chained together
   • Provide sufficient degrees of freedom for each component requiring precise optical alignment (this generally means that 2 kinematic mirrors are required before every precision aligned optic). Micro-optical designs may be exempt from this requirement.

6. Comment your code: Describe your baseplates purpose and design logic.

7. Submit improvements: If your baseplate improves an existing design, please contact us so that we can review and update the example baseplates!

Components

Researchers may want to submit additions to PyOpticL's bundled component library. These additions are only for general purpose components that are widely applicable and not specific to particular designs. Such application-specific components should be retained as external libraries.

The optomech.py file is central to PyOpticL. It defines parts that are widely available or easy to 3D print. To keep collaboration and iteration simple:

1. Use general, standard components: Name parts using manufacturer terminology

2. Ensure Accuracy: Optical centers and angles must be carefully measured in CAD

3. Ensure Modularity: New components should be self-contained and must not break or modify existing functionality

Large System Development

Larger systems should be structured as nested, modular subsystems composed of baseplates.

Best Practices:

1. Hierarchy: Systems are composed of subsystems and subsystems are composed of baseplates etc.
2. Modularity: Subsystems should be composed out of existing baseplates wherever possible to avoid duplicate plates and keep systems modular
3. Interchangeability: Subsystems should have plates which "tap" power from a main "bus" line
4. Grid Alignment:
   1. Align beam handoff between plates to the table grid.
   2. Even fiber couplers should respect the grid for modularity

How to Contribute

1. JOIN THE DISCORD and let us know what you are working on!

2. Fork the PyopticL repository

3. Make local changes to the library

   a. Keep your changes contained to modular blocks of code that can be efficiently reviewed and merged

   b. Comment your code when appropriate and avoid overly verbose or LLM-generated code blocks

4. When you have a working baseplate, components, etc. - submit a pull request and we will work with you to get it merged!