Commit 41ef9991 authored by Sean Leavey's avatar Sean Leavey
Browse files

Update documentation

parent cd6042ce
......@@ -32,7 +32,16 @@ some settings are stored also in the former.
In addition to Python dependencies, |Finesse| requires some system dependencies in order
to be built. These are not required for end users using an appropriate wheel. These are
independent of Python and are therefore not specified in ``setup.cfg``.
independent of Python and are therefore not specified in ``setup.cfg``. Currently, these
are:
- Python 3.8 or higher
- SuiteSparse 4.0 or higher
Python 3.8 is a hard requirement due to the use of positional-only arguments, walrus
operators, the use of :class:`functools.singledispatchmethod` and the requirement for
``dict`` to be reversible in the code. SuiteSparse is used for building and solving
matrix systems, a core part of |Finesse|'s functionality.
.. note::
......@@ -42,12 +51,13 @@ independent of Python and are therefore not specified in ``setup.cfg``.
built package is installed in the user's environment. This is usually beneficial
because it means build dependencies (such as Cython) don't need to be available in
the local environment, but when debugging build issues it may be useful to switch
this behaviour off. In ``pip`` this can be done with the ``--no-build-isolation``
flag when running ``pip install``. Note that you'll need to ensure the build
dependencies listed in ``pyproject.toml`` are available.
this behaviour off. In pip this can be done with the ``--no-build-isolation`` flag
when running ``pip install``. Note that you'll need to ensure the build dependencies
listed in ``pyproject.toml`` are available. You can get these by installing the
``inplacebuild`` extras.
Modifying dependencies
----------------------
Modifying Python dependencies
-----------------------------
Runtime dependencies, i.e. those required for running |Finesse| on a user's computer,
are listed in the ``install_requires`` key of the ``[options]`` section of
......
......@@ -19,9 +19,9 @@ JupyterLab
Repository: https://git.ligo.org/finesse/katscript-jupyterlab
The JupyterLab extension is distributed in two places; via ``pip`` and ``npm``.
New versions should be published at both locations. You need to have `nodejs
<https://nodejs.org/en/>`_ installed to work with the extension.
The JupyterLab extension is distributed in two places; via pip and npm. New versions
should be published at both locations. You need to have `nodejs
<https://nodejs.org/en/>`__ installed to work with the extension.
pip
---
......
.. include:: ../../defs.hrst
.. _dev_get_started:
Getting started with Finesse development
----------------------------------------
|Finesse| is an open source program where any contributions (of any size) from members
of the optical simulation community are welcome and encouraged.
The project is hosted on `<https://git.ligo.org/finesse/finesse3>`_.
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
<https://git.ligo.org/finesse/finesse3/issues>`_.
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:
.. jupyter-execute::
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.
.. _how_to_contribute:
Contributing to the project
***************************
For more in-depth guides on the points in this section see the pages below.
.. toctree::
:maxdepth: 1
setup_fork
These pages are also linked when relevant in the numbered list below.
How to contribute
~~~~~~~~~~~~~~~~~
The preferred way to contribute to |Finesse| is to fork the main repository
`<https://git.ligo.org/finesse/finesse3>`_, work on this copy
of the code then submit a "merge request".
A brief overview of the process is given below, with more details to be found in the
sections later on.
1. Log-in to the the `LIGO GitLab server <https://git.ligo.org/users/sign_in>`_ with
your LIGO / Virgo / KAGRA account.
2. Go to the |Finesse| repository homepage: `<https://git.ligo.org/finesse/finesse3>`_.
3. 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 details on this see* - :ref:`setup_fork`
4. Clone this copy to your local disk, via HTTPS::
git clone https://git.ligo.org/<username>/finesse3.git
Or via SSH::
git clone git@git.ligo.org:<username>/finesse3.git
Replacing `<username>` with your username on the LIGO GitLab server.
5. Install the project with developer dependencies using a Python packaging tool such as
`pip <https://pip.pypa.io/en/stable/installing/>`__::
pip install -e .[test,docs,dev]
6. Install the pre-commit hooks that will check your code for style errors when you
commit::
pre-commit install
7. Create a new branch on your local copy to hold the additions / changes you want to
contribute::
git checkout -b <feature-name> origin/master
and start programming! **Note that you should never work in the** `master`
**branch**.
8. Work on this 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>
9. Once you are happy with the state of your changes, go to the webpage of your fork of
the |Finesse| repository and click "Merge Request" to send these changes to the
maintainers of |Finesse| for review.
.. include:: ../../defs.hrst
.. _setup_fork:
Setting up your fork
~~~~~~~~~~~~~~~~~~~~
Before reading this you should read steps 1 - 4 in :ref:`how_to_contribute`. After these
steps you will be ready to complete the following process:
1. After cloning, change directory to your local copy of your fork of the |Finesse| 3
repository::
cd finesse3
2. Now you want to link your repository to the upstream repository (the main |Finesse| 3
repo), so that you can fetch changes from trunk. To do this, run::
git remote add upstream git://git.ligo.org/finesse/finesse3.git
`upstream` here is an arbitrary name we use to refer to the main |Finesse| 3
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 your fork.
3. Check that your remotes are set-up correctly with::
git remote -v show
This should give you something similar to::
upstream git://git.ligo.org/finesse/finesse.git (fetch)
upstream git://git.ligo.org/finesse/finesse.git (push)
origin git@git.ligo.org:<username>/finesse3.git (fetch)
origin git@git.ligo.org:<username>/finesse3.git (push)
......@@ -4,7 +4,7 @@ Developer guide
.. toctree::
:maxdepth: 3
get_started/index
setting_up
codeguide/index
packaging
documenting
......
......@@ -3,43 +3,36 @@
.. _packaging:
Packaging Finesse
-----------------
=================
|Finesse| is currently packaged for `pip <https://pypi.org/>`_ and `conda
<https://conda.io/>`_. |Finesse| requires the following system dependencies in addition
to those for pip found in ``requirements.txt``:
<https://conda.io/>`_. |Finesse| requires some :ref:`system dependencies
<requirements_guide>` in addition to those defined in the ``setuputils`` configuration.
- Python 3.8 or higher
- SuiteSparse 4.0 or higher
Conda
-----
Python 3.8 is a hard requirement due to the use of positional-only arguments, walrus
operators, the use of :py:class:`functools.singledispatchmethod` and the requirement for
``dict`` to be reversible in the code.
.. todo:: document the packaging procedure for Conda
Pip
***
Wheels
------
Python wheels are built for most Linux platforms (so-called `manylinux` wheels). This
procedure is automated as part of the CI pipeline (see ``.gitlab-ci.yml`` in the
source), but it is quite simple. The Red Hat based Docker image ``manylinux2014``
provided by PyPA is used. The only upstream dependency is currently
Platform-specific `wheels <https://pythonwheels.com/>`__ are built for most Linux
platforms (so-called `manylinux` wheels) and Mac OSX. This procedure is automated as
part of the continuous integration pipeline (see :source:`.gitlab-ci.yml
</.gitlab-ci.yml>`), but it is quite simple. The Red Hat based Docker image
``manylinux2014`` provided by PyPA is used. The only upstream dependency is currently
``suitesparse-devel`` which provides the KLU C headers used by |Finesse|'s simulation
module.
The procedure for building a `bdist_wheel` for the `manylinux` target is::
The procedure for building a `bdist_wheel` for the `manylinux` target is:
.. code-block:: console
$ yum install -y suitesparse-devel
$ /path/to/pip wheel . --no-deps -w wheelhouse
$ auditwheel repair wheelhouse/*.whl
These commands should be run from the source code root on the Docker image. The
``/path/to/pip`` parts should be replaced by the path to `pip` for the Python version
being targeted.
Conda
*****
.. todo:: Create and document the packaging procedure for Conda.
The conda environment is defined in ``environment.yml`` for most platforms but
``environment-win.yml`` for Windows.
``/path/to/pip`` parts should be replaced by the path to `pip` corresponding to the
Python version being targeted.
.. include:: /defs.hrst
.. _dev_get_started:
========================================
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
<https://git.ligo.org/finesse/finesse3/issues>`_.
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:
.. jupyter-execute::
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.
.. _how_to_contribute:
Contributing to development
===========================
The preferred way to contribute to |Finesse| development is to fork the main repository
`<https://git.ligo.org/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.
1. :ref:`Install git <installing_git>` and set up a :ref:`fork <setup_fork>` of the main
|Finesse| repository.
2. Set up the :ref:`Finesse development environment <setting_up_finesse_dev_env>`.
3. Install the pre-commit hooks that will check your code for style errors when you
commit:
.. code-block:: console
$ pre-commit install
4. Create a new branch on your local copy to hold the changes you want to contribute:
.. code-block:: console
$ git checkout -b <feature-name> origin/develop
The name format should follow either ``feature/xyz`` or ``fix/xyz`` where ``xyz`` is
an informative branch slug, otherwise the branch might be rejected when pushed.
Once you have reached this stage you can start programming!
5. 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:
.. code-block:: console
$ git push -u origin <feature-name>
6. 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.
.. _installing_git:
Installing git
--------------
Linux / OSX
~~~~~~~~~~~
Install git using your system package manager.
Windows
~~~~~~~
Install `Git for Windows <https://gitforwindows.org/>`_. 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.*
.. _setup_fork:
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:
1. Log-in to the the `LIGO GitLab server <https://git.ligo.org/users/sign_in>`_ with
your LIGO / Virgo / KAGRA account.
2. Go to the |Finesse| repository homepage: `<https://git.ligo.org/finesse/finesse3>`__.
3. 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 :ref:`setup_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:
.. code-block:: console
$ git remote add upstream git://git.ligo.org/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
your fork.
Check that your remotes are set-up correctly with:
.. code-block:: console
$ git remote -v show
This should list something similar to::
upstream git://git.ligo.org/finesse/finesse.git (fetch)
upstream git://git.ligo.org/finesse/finesse.git (push)
origin git@git.ligo.org:<username>/finesse3.git (fetch)
origin git@git.ligo.org:<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.
.. todo:: write info on syncing forks with upstream
.. _setting_up_finesse_dev_env:
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 dependencies. Alternatively you can manage the prerequisites yourself (e.g.
via your system package manager) and set up |Finesse| using the included ``setuputils``
configuration. Both approaches are described below.
.. note::
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 :ref:`recompile
<rebuilding_extensions>` the |Finesse| C extensions.
Developing via Conda
~~~~~~~~~~~~~~~~~~~~
`Conda <https://docs.conda.io/en/>`__ is the free and open source package manager
included in the `Anaconda <https://www.anaconda.com/products/individual>`__ and
`Miniconda <https://docs.conda.io/en/latest/miniconda.html>`__ scientific computing
packages.
Regardless of platform, you need to first install the Conda package manager, either via
`Anaconda <https://www.anaconda.com/products/individual>`__ or `Miniconda
<https://docs.conda.io/en/latest/miniconda.html>`__.
Change directory to your local copy of the |Finesse| repository:
.. code-block:: console
$ cd /path/to/finesse3
Create a new Conda environment using the |Finesse| environment file:
.. code-block:: console
$ conda env create -n <name_of_environment> -f <environment-spec>.yml
where you should substitute ``<name_of_environment>`` for a suitable name of your
choice, e.g: ``finesse3``, and ``<environment-spec>`` for either ``environment`` (Linux
and Mac OSX) or ``environment-win`` (Windows).
The above step should install all necessary dependencies and 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:
.. code-block:: console
$ 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.
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.
.. rubric:: 'cannot find -lmsvcr140' error during the compilation process
Here are the steps to resolve this error:
1. Use the Windows search bar to find a ``vcruntime140.dll`` file. Open the folder
location of this file and copy the file.
2. Paste this file to: ``C:\<ANACONDA_PATH>\envs\<ENV_NAME>\Library\mingw-w64\lib``
where ``<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.
3. 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']
to this::
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| :ref:`system
requirements <requirements_guide>` are installed and available.
|Finesse| and the development extras can be installed using pip with:
.. code-block:: console
$ pip install -e .[test,docs,lint,inplacebuild]
You may wish to install ``finesse`` inside a virtual environment; see the `standard
installation guide <installation>`__ for more details. If on the other hand you wish to
manage the |Finesse| dependencies entirely yourself (e.g. using your system package
manager or using the system Python environment), you can ask pip to install only the
``finesse`` package itself and not its dependencies by adding the ``--no-deps`` flag.
.. note::
If you wish to install |Finesse| as an editable system package, you may need to wait
until changes suggested in :pep:`660` are implemented in the Python packaging
ecosystem.
.. _rebuilding_extensions:
Rebuilding extensions
---------------------
If you change (or pull changes from upstream) any files with names ending ``.pyx`` /
``.pxd`` then you will need to re-build the Finesse C extensions. On Linux / OSX this
means running ``make`` whereas on Windows it means executing ``make.bat``, both from the
top level |Finesse| git directory.
.. note::
The |Finesse| repository contains a :pep:`517` compatible build configuration that
separately specifies the dependencies required to *build* and to *run* |Finesse|.
Most packaging frontends (such as pip) will install projects that define PEP 517
compatible build configurations in an isolated environment with only the explicitly
specified build dependencies (defined in ``pyproject.toml``) available, then move the
compiled project back to the user's environment. This guarantees that the project is
built using explicit, deterministic packages, and helps to catch errors that might
not have arisen with a traditional *in-place* build (such as dependency clobbering or
implicit use of system packages).
The default use of isolated build environments 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 dependencies, then
procede to rebuild the full project and extensions without checking what 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 far, far faster and
only rebuilds files that have actually changed, but, in order for this to work, the
build dependencies specified in ``pyproject.toml`` have to *also* be installed in the
local development environment. These are available as an optional set of requirements
in ``setup.cfg`` named "inplacebuild", installation of which is included in the
instructions above.
.. include:: ../defs.hrst
.. _getting_help:
Getting help
============
.. todo:: write help section (for LSC members and for public)
......@@ -23,6 +23,7 @@ interferometers will find the :ref:`physics` section useful.
extensions
key_concepts
migrating_from_Finesse_2
getting_help
examples/1_simple_cav
examples/2_pdh_lock
examples/3_near_unstable
......
......@@ -4,212 +4,76 @@
Installation
============
For most users we recommend installing the **release version** of |Finesse| as this will
always be the most stable. Any bugs found in release versions can be debugged more
easily than in an arbitrary development version, so subsequent minor releases will
typically address these issues faster. If however you need some feature or bugfix
that's only available in the latest development version then you can install from
source.
The recommended way to install |Finesse| is to use the Conda package. This handles the
installation of the system and Python requirements in order to run |Finesse|, and is
available on most platforms.
Release version
---------------
|Finesse| 3 is still under active development. There is currently no stable release
version available, though there is an early alpha version available on `PyPI
<https://pypi.org/project/finesse/>`__. It will eventually also be available via Conda.
Via PyPI