Getting started with Finesse development¶
Finesse is an open source program where contributions (of any size) from members of the optical simulation community are welcome and encouraged. This page contains information on how to contribute, either with bug reports or feature requests or with direct development.
Submitting a bug report¶
If you encounter a bug in the code or documentation, especially in a release version, do not hesitate to submit an issue to the Issue Tracker.
When reporting a bug, please include the following:
A short, top-level summary of the bug. In most cases, this should be 1-2 sentences.
A minimal but complete and verifiable code snippet example to reproduce the bug.
The actual result(s) of the example provided versus the expected result(s)
The Finesse version, Python version and platform (i.e. OS version) you are using. You can find the first two from a Python interpreter with, e.g:
import platform import finesse print(platform.python_version()) print(finesse.__version__)
If the bug is Physics-related (e.g. an unexpected discrepancy in results between Finesse and another method) then you should also provide details of the method(s) used to compute the result - in particular the equations used.
Contributing to development¶
The preferred way to contribute to Finesse development is to fork the main repository https://gitlab.com/ifosim/finesse/finesse3, work on this copy of the code then submit a “merge request”.
A brief summary of the process is given below, with more details to be found in the sections later on.
Install git and set up a fork of the main Finesse repository.
Set up the Finesse development environment.
Install the pre-commit hooks that will check your code for style errors when you commit:
$ pre-commit install
Create a new branch on your local copy to hold the changes you want to contribute:
$ git checkout -b <feature-name> origin/develop
The name format should follow either
xyzis an informative branch slug, otherwise the branch might be rejected when pushed.
Once you have reached this stage you can start programming!
Work on your branch, on your machine, using git to do the version control. Push any changes you have committed to your copy of the Finesse repository:
$ git push -u origin <feature-name>
Once you are happy with the state of your changes, submit a merge request. If you are a member of the LIGO / Virgo / KAGRA collaborations, you can go to the web page of your fork of the Finesse repository and click “Merge Request” to send these changes to the maintainers for review. If you are not a member, get in touch by sending an email to the developers.
Linux / macOS¶
Install git using your system package manager.
Install Git for Windows. You can either use the tools this provides directly to clone the Finesse repository or add the path to your git executable to the Windows environment variables - details on how to do this are shown in the next step, but you can skip this if you intend to use the git bash/gui here feature(s) of Git for Windows.
To be able to use git from the command line, and via an Anaconda Prompt, you need to add the path to your git executable (installed in the step above) to the Windows environment variables.
Type “environment variables” into the Windows search bar and open the first result. Click the “Environment Variables…” button.
In the new window that pops up, navigate to the lower panel (System Variables) and find the field named “Path”. Click the “Edit” button with this field highlighted. You will now be presented with a window showing all the currently stored paths. Click the “New” button in this Window and add the following two paths separately:
C:\Program Files\Git\bin\git.exe C:\Program Files\Git\cmd
Note that these paths above are assuming that you did not change the default install location of Git for Windows.
Setting up your fork¶
Finesse development takes place on a server provided primarily for members of the LIGO, Virgo or KAGRA collaborations. If you are a member, you can fork the project on this service:
Log-in to the the LIGO GitLab server with your LIGO / Virgo / KAGRA account.
Go to the Finesse repository homepage: https://gitlab.com/ifosim/finesse/finesse3.
Click on the “Fork” button near the top of the page. This will create a copy of the Finesse repository under your account on the GitLab server. For more information about this step, see Setting up your fork below.
If you are not a member, you can fork Finesse using your preferred git service, or just create your own local repository.
Once you have a fork, change directory to your local copy. Now you want to link your repository to the upstream repository (the main Finesse repository), so that you can fetch changes from trunk. To do this, run:
$ git remote add upstream git://gitlab.com/ifosim/finesse/finesse3.git
upstream here is an arbitrary name we use to refer to the main Finesse repository.
Note the use of
git:// for the URL - this is a read-only URL which means that you
cannot accidentally write to the upstream repository. You can only use it to merge into
Check that your remotes are set-up correctly with:
$ git remote -v show
This should list something similar to:
upstream git://gitlab.com/ifosim/finesse/finesse.git (fetch) upstream git://gitlab.com/ifosim/finesse/finesse.git (push) origin firstname.lastname@example.org:<username>/finesse3.git (fetch) origin email@example.com:<username>/finesse3.git (push)
Occasionally you should synchronize your fork with the upstream Finesse repository to ensure your copy does not get too out-of-date.
write info on syncing forks with upstream
Setting up the Finesse development environment¶
If you’re just getting started, it is easiest to set up Finesse for development using
the Conda environment files provided in the git repository. These install system
prerequisites (such as a C compiler) and install Finesse with all of its development
tools and requirements. Alternatively you can manage the prerequisites yourself (e.g.
via your system package manager) and set up Finesse using the included
configuration. Both approaches are described below.
In these steps Finesse is installed in “editable” mode, meaning that any changes to source files in the local git copy (i.e. after pulling the latest changes from the upstream repository) will be reflected in the installed version. When you change a file or synchronize your fork, you may have to recompile the Finesse C extensions.
Developing via Conda¶
Conda is the free and open source package manager included in the Anaconda and Miniconda scientific computing packages.
Regardless of platform, you need to first install the Conda package manager, either via Anaconda or Miniconda.
Change directory to your local copy of the Finesse repository:
$ cd /path/to/finesse3
Create a new Conda environment using the Finesse environment file:
$ conda env create -n <name_of_environment> -f <environment-spec>.yml
where you should substitute
<name_of_environment> for a suitable name of your
<environment-spec> for either
and macOS) or
The above step should install all necessary requirements to build and install Finesse. Depending on your configuration, Conda may or may not activate your new environment automatically. If it did not, you can simply run:
$ conda activate <name_of_environment>
At this point you should see a
(<name_of_environment>) at the start of your shell
prompt, indicating that the environment is active.
The last step is to install Finesse in editable mode inside your new environment,
meaning changes you make to the code will be reflected in the
PYTHONPATH used by the
Python interpreter. A
Make target to do this is provided:
$ make develop-conda
Troubleshooting Windows installation¶
A number of different errors may occur when attempting to install Finesse from source on Windows. The list below should be a comprehensive guide to addressing these issues.
‘cannot find -lmsvcr140’ error during the compilation process
Here are the steps to resolve this error:
Use the Windows search bar to find a
vcruntime140.dllfile. Open the folder location of this file and copy the file.
Paste this file to:
<ANACONDA_PATH>is the path to your Conda installation and
<ENV_NAME>is the name of your Conda environment that you are using for your Finesse installation.
If you still get this error after the steps above, then use the Windows search bar to find the file
cygwinccompiler.py. Open this file and edit the following lines, from this:
elif int(msc_ver) >= 1900: # VS2015 / MSVC 14.0 return ['msvcr140']
elif int(msc_ver) >= 1900: # VS2015/ MSVC 14.0 return ['vcruntime140']
Developing via Python package manager¶
With this approach you are responsible for ensuring the Finesse system requirements are installed and available.
Finesse and the development extras can be installed using pip with:
$ make develop-pep517
If you change (or pull changes from upstream) any files with names ending
.pxd then you will need to re-build the Finesse C extensions. This means running
make inside a terminal from the top level Finesse git directory.
The Finesse repository contains a PEP 517 compatible build configuration (see
Requirements for building, running and developing Finesse). Most build frontends (such as pip) will install projects
that define PEP 517 compatible build configurations in an isolated environment with
only the necessary build requirements available. This default behaviour presents a
small annoyance when quickly trying to rebuild Finesse extensions during
development, whereupon pip (or whatever build frontend is being used) will first
create a new temporary environment then download (or retrieve from cache) and
install the build requirements, then procede to rebuild the full project and
extensions without checking whether anything actually needs rebuilt. This process is
slow, taking many minutes on some machines. To mitigate this nuisance, the
Makefile in the Finesse project root builds in-place, performing
recompilation of extensions directly within the local directory without first
setting up an isolated build environment. This is much faster and only rebuilds
files that have actually changed, but, in order for this to work, the build
requirements specified in
pyproject.toml have to also be installed in the
local development environment. These are available as an optional set of
setup.cfg named “inplacebuild”, installation of which is
included in the instructions above.
Once PEP 660 is widely supported by build frontends like pip, this step may not be required.