Introduction

Welcome to the PyPO user manual. Here you can find several resources that will assist in using and/or developing PyPO. PyPO is optical simulation software, aimed at engineers/students in the field of (quasi)-optical design that have access to CUDA-capable GPUs. The software can be run multi-threaded, but the real power shines through when running PyPO on the GPU.

Originally, PyPO was developed for laboratory characterisation and optical alignment of wideband integrated superconducting spectrometers operating at sub-mm wavelengths. It is specifically designed to model forward and backward propagation of electromagnetic fields through systems containing (off-axis) quadric and planar reflector surfaces. In addition, it can calculate common metrics to assess performance of the optical system and can also visualise the systems and results.

This homepage contains general information regarding installation instructions, the content of the user manual, contributor guidelines and contact information. After installing, the best place to start for new users would be the PyPO fundamentals tutorials, after which the rest of the tutorials can be studied. PyPO also comes with a suite of demonstrations that show the application of the program in the context of validation tests. For contributor guidelines and general development instructions, please see the instructions for developers page.

Installation

The prerequisites for installing PyPO on any operating system are:

A working Python installation of version 3.8 or higher.
A pip installation.

All other necessary prerequisites are fetched and installed upon installing PyPO.

Install From Source

Prerequisites

PyPO uses CMake to build from source and if a source distribution is desired, it needs to be installed. In addition, wheel is required as well:

pip install cmake wheel

Linux

To install PyPO from source on Linux, clone the git repository:

git clone https://github.com/PyPO-dev/PyPO

Alternatively, download the .zip package from here and unpack in the preferred destination. Navigate to the cloned/unpacked repository and run:

pip install .

MacOS

You will need to have the command line tools package installed:

xcode-select --install

Then, installation of PyPO proceeds in the same fashion as for Linux.

Windows

Install Visual Studio Express. Choose the C++ desktop development package. Important is, is that the MSVC compiler is present

After this is installed, PyPO can be installed just like on Linux.

Dev Install

In order to develop PyPO, we recommend to install PyPO in edit mode. See this section of the developers guidelines page for more info.

Using PyPO On GPU

The full power of PyPO shines through when running on the GPU. In order to use the GPU accelerated libraries for PyPO, a working CUDA installation should be present. For Linux, this article describes nicely how to install CUDA through the apt repository.

For Windows, see the official instructions on the Nvidia website.

Unfortunately, Apple has stopped supporting Nvidia cards since 2015 and therefore, the CUDA libraries for PyPO cannot be installed on MacOS currently.

After installing CUDA, PyPO will detect this and, upon building, will build the CUDA libraries. It is therefore important to re-install PyPO if you installed it before installing CUDA, otherwise the libraries will not be built.

Optional Dependencies

PyPO contains several optional features such as a graphical user interface (GUI). For developers, an automated testing framework is present as well as a documentation generator. The prerequisites for these features are not installed through the regular install. Instead, they can be installed separately as needed.

To use the GUI, PySide6, pyqtdarktheme and attrs need to be installed:

pip install PySide6 pyqtdarktheme attrs

The automated tests are run using the nose2 framework:

pip install nose2

For running the interactive notebooks for the tutorials and demos, Jupyter notebook needs to be installed:

pip install notebook

Documentation in PyPO is generated using Doxygen. Please see their installation page for instructions regarding installation.

User Manual

For a basic understanding of PyPO and its design, we refer to the explanations page. These explanations are less related to using PyPO, but more to how PyPO works under the hood.

Several tutorials have been developed in order to demonstrate the usage and functionality of PyPO:

the first set of tutorials showcase the functionalities of the package,
the second and final set show how to use the GUI.

Notebooks demonstrating usage in the context of validation tests are grouped together in the demonstrations page. These can serve as good starting points for experimenting with PyPO in actual physical simulations.

The software documentation for PyPO is split into two parts:

the first part forms a comprehensive API reference for all public methods of PyPO,
the second part forms a reference for all internal Python, C/C++ and CUDA code.

In addition, the documentations page contains a comprehensive overview of the common input/output types of PyPO.

Contributor Guidelines

The contributor and development guidelines can be found here. These guidelines contain information on how to raise issues concerning PyPO, how to contribute code but also how to run the unit tests and how to generate documentation.

License

This project is released under the MIT License.

Contact

For questions/support, please contact: PyPO..nosp@m.dev@.nosp@m.gmail.nosp@m..com