Changelog

This changelog describes the changes made between the different alpha versions of |Finesse|. When seeing unexpected behavior with existing finesse scripts after updating, you should read the entries between the last working version and the version introducing the issues, to see if there are any entries that are relevant to your code. See Updating Finesse for instructions on how to update to the latest version.

Note

You are currently looking at the documentation for |Finesse| 3.0a33. Some of the changes listed for older versions may no longer be relevant, or contain broken links to non-existing documentation pages.

3.0a33

Changed

Added

  • Added new finesse.components.telescope.Telescope component which represents an ideal telescope between to parts of an optical system. For example, it allows the use to perfectly mode match two cavities without needing to design or specify the exact telescope details.

  • Connector._trace_through has been added as an internal flag to stop the beam tracer from trying to trace through a connector. This can be used for components like finesse.components.telescope.Telescope, which only connect optical fields and shouldn’t allow beam tracing through it as it isn’t well defined. Or the user could use this to fix a place that a mismatch should occur.

  • Added an option to specify the transmission and reflection conventions for finesse.components.mirror.Mirror and finesse.components.beamsplitter.Beamsplitter. The transmission and reflection phase relationship can be changed by setting the imaginary_transmission argument to either real or imaginary. By default this is imaginary (True), so a \(\I\) phase on transmission. If set to be the real convention then the phase is 0 on transmission and 180 degrees on reflection on the port 1 side.

Removed

  • zero_tem00_gouy optional argument was removed from finesse.cymath.homs.HGModes constructor as it was not being used internally or elsewhere.

Fixed

  • Fixed issue #699 by giving finesse.components.readout.ReadoutRF a default frequency value of f=0.

  • Fixed passing arguments in the wrong order to finesse.model.Model.link() not raising an exception.

  • Improved exception messages from the beam tracer to removed “bug encountered!” which wasn’t true in many cases. BeamTraceExceptions are now thrown with more useful messages to the user.

3.0a32

Fixed

Added

Changes

  • Added ipykernel as doc build dependency as that doesn’t seem to get installed now through other dependencies and leads to the doc build complaining that python3 doesn’t exist.

3.0a31

Added

  • Wheels for linux/macos 3.13

3.0a30

Added

  • finesse.components.lens.AstigmaticLens element added with x and y focal length parameters. Works the same as a finesse.components.lens.Lens and also has an OPD map attribute.

  • Added simple sinusoidal and Helical LG mode calculation functions to finesse.cymath.laguerre module, see example

  • Added developer documentation page on the internal matrix solver.

  • Added reverse_gouy and flip_lr options to finesse.knm.map.Map.scatter_matrix() to allow for more flexibility in how the scatter matrix is computed.

Fixed

  • Fixed #685: Figure dictionary return by solution.plot() method has correct strings keys when single detector is present.

  • Fixed #669: finesse.knm.maps.Map.remove_piston`() accepts spot_size only with type float and not np.float

  • Fixed #666: finesse.analysis.actions.dc.DCFieldsSolution and finesse.analysis.actions.lti.FrequencyResponseSolution` cannot select themselves by name

  • Fixed #573: Symbolic changing division in lens focal length makes cavity unstable

  • Fixed a collection of warnings in various tests

Changed

  • Drop support for Python 3.9 due to various packages no longer supporting it

  • Allows a superclass of finesse.knm.maps.Map to be used as a base class for custom maps. This allows for more flexibility in defining custom maps that define their own aperture and surface functions. The following example demonstrates:

class CustomMap(Map):
   def __init__(self):
      x = ...
      y = ...
      super().__init__(
         self,
         x,
         y,
         opd=self.surface,
         amplitude=self.aperture,
      )

   def aperture(self, model=None):
      return ...

   def surface(self, model=None):
      return ...

  • finesse.exceptions.NotChangeableDuringSimulation` now raised when trying to change a parameter that is not changeable during a simulation. This also fixes a bug where these changes are circumvented by using symbolics. Parameters that are not changeable during a simulation are flagged because some internal logic has not been implement yet to handle these changes.

3.0a29

Fixed

Added

  • Added a new utility function finesse.utilities.bug_report.bug_report() to make it easier to report issues by automatically collecting relevant information. See Reporting issues for an example.

  • Added a show and path argument to finesse.model.Model.plot_graph() to control whether to show the plot and whether to save it to disk.

Changed

  • Use a more numerically stable method for calculating the frequency response of zpk filters which is more robust with filters with a large number of roots.

  • FieldDetectors now work with planewave models and no longer throw a warning.

3.0a28

This release includes two changes to default way of handling phases in |Finesse|, which are listed below. The effect of these changes is subtle, and described in detail in Phase configuration settings and Mirror and beamsplitter phase relationships.

Warning

If your simulations produce different results after updating to this release, it is likely that your previous results were incorrect, since the old default can break power conservation in certain setups.

You can switch between the two settings using finesse.model.Model.phase_config()

# new default
model.phase_config(False, True)
# old default
model.phase_config(True, True)

You can use this to check if your results are impacted by this change.

The changes have been tested with both the finesse-ligo and finesse-virgo packages, so if you are using these you will probably not be affected.

If you have any questions, do not hestitate to contact us via the matrix channel.

Breaking Changes

  • The default value for zero_k00 finesse.model.Model.phase_config() has been changed to False. See Phase configuration settings for more information and an example of how the old default can break power conservation in the simulation Any simulation running with higher order modes and a cavity could be affected by this change and users using finesse.knm.maps.Map should make sure they use optimizers for locking.

  • The phase relationship on transmission has been changed to a new default. It will be identical to the previous relationship for most cases, but will prevent power conservation issues in more complicated setups. You can set the _settings.phase_config.v2_transmission_phase to True if you want to revert to the old (Finesse 2) behavior, but the new behavior is likely more physically correct. See Mirror and beamsplitter phase relationships for more details.

Added

Changed

  • finesse.model.Model.get_elements_of_type() now returns a tuple instead of a generator, and accepts element names as strings as well as python classes as arguments:

  • Added an option full_output to finesse.gaussian.optimise_HG00_q_scipy() to return the optimized array of HG modes alongside the fit result. This replaces the previous return_fit_result argument.

  • Include parity flip on reflection in Mirror and Beamsplitter ABCD methods. See also the new _s and _t suffixes in methods in finesse.tracing.abcd and the #123. For backward compatible code, use something like:

try:
   from finesse.tracing.abcd import space, beamsplitter_refl

   beamsplitter_refl_t = lambda *args: beamsplitter_refl(*args, "x")
   beamsplitter_refl_s = lambda *args: beamsplitter_refl(*args, "y")
except ImportError:
   # Handle newer versions which separate the beamsplitter refl # into the tangential
   and sagittal planes from 3.0a28 from finesse.tracing.abcd import (
      space, beamsplitter_refl_s, beamsplitter_refl_t,
   )

  • Changes the examples in the documentation to indicate that parsing an action in KatScript and calling model.run() without any arguments is not recommended.

Removed

Fixed

  • Single solution outputs can be seleceted by their name now, so you do not need to add extra actions or put them in series unnecessarily.

  • Clarified the docstrings for the finesse.components.cavity.Cavity class its finesse.components.cavity.Cavity.path() method.

  • The shape of DCFieldsSolution is reverted to [nodes, frequencies, HOMs], as described in finesse.analysis.actions.dc.DCFieldsSolutions

  • When removing a Readouts component, remove the associated output detectors as well (note that removing components from a model is unreliable in general)

  • Parameters of autogenerated spaces and wires not generating a correct full_name attribute.

  • Fixed issue #659 - missing sol = model.run() in documentation for Maximise action

3.0a27

  • Allow detectors and ports to be visualized with component_tree method. See an example in the [docs](https://finesse.ifosim.org/docs/develop/usage/python_api/models_and_components.html#visualizing-the-model)

  • Fix finesse.gaussian.HGMode ignoring shape of the given y vector when n=m.

  • Option to keep only a subset of symbols in symbolic Model.ABCD method

  • Add options to specify the plane of incidence for a beamsplitter and to misalign a beamsplitter

  • Add pytest-xdist and configure it for faster (parallel) test running

  • Fix slow optimal q detector test slowdown

  • Fix broken cli test overwriting user config

3.0a26

  • Fixed inadvertently adding cython as a runtime dependency in 3.0a25

  • Added documentation on defining manual beam parameters

  • Expanded docstring on mirror curvature

  • Better error message for degree of freedom illegal self referencing

  • Generate conda files automatically from pyproject.toml

3.0a24

New features

Documentation changes

Other

3.0a23

  • Fix memory leak issue during model building

  • Changing the ‘disabled’ argument of the Lock component to ‘enabled’ to avoid double negative if conditions in the code

  • Minor performance fixes

  • Fix for the Optimizer action that would sometimes leave the model in an incorrect state after optimization

  • “Did you mean” suggestions for katscript keyword arguments on syntax errors

  • Adds warning for unreasonable katscript line lengths and better message on parsing recursion errors

  • Evaluate symbolic references in the component info tables

  • allows overlap_contour to work with (qx,qy) input

3.0a22

  • phase_config now locked when the model is built

  • Symbol.lambdify was added to change Finesse symbolic expressions into a Python callable function

  • Added initial benchmarking tests for tracking performance changes over time

  • KnmMatrix.plot can be set to amplitude or phase now with the mode option

  • Locks now throw an explicit exception LostLock when it fails

  • Added Matplotlib helper function that plots arrows along a line at several points

3.0a21

Adds support for Python 3.12

3.0a20

3.0a19

  • Requiring Matploblib < 3.8 until fixes are made for plotting routines

  • Parameters that are external controlled, such as those set by a DegreeOfFreedom will explicitly shown the symbolic reference now as opposed to hiding it. See #571

3.0a18

  • Fixed FieldDetector not conjugating lower sideband

  • Fixed DegreeOfFreedom using custom AC_IN and AC_OUT not filling the matrix correctly

  • Variable element removed, now calls model.add_parameter instead. this means some code using var.value.value will no longer work.

  • Added extra factorisation step when refactor returns a singular matrix with KLU, a warning will show when this happens.

  • Model.display_signal_blockdiagram now takes nodes name list and only show paths with those nodes in for cleaner diagrams

  • Model.path can take a symbolic=True keyword argument now for calculating symbolic path lengths

  • phase_level deprecated and replaced with model.phase_config method

  • unparing unsupported KatScript values will result in a __FIX_ME__ token

  • Parameters now support boolean checks

  • Python 3.11 wheels now built

  • SetLockGains now just optimises gains and not demodulation phases

  • OptimiseRFReadoutDemodPhaseDC now accepts Readout detector outputs REFL9_I or REFL9_Q for example, to optimise for either quadrature. Readout names supported and will default to _I with a warning

  • Fixed Hello-Vinet function substrate_thermal_expansion_depth #567

3.0a17

  • Fixing block diagram generation for signal paths

  • DOF has simpler interface for specifying just a DC actuation instead of using LocalDegreesOfFreedom

  • This also allows user to specify their own AC connections to the DOF.AC.i and DOF.AC.o as they see fit

  • Reworking signal node and port connections and attached_to attributes so they work

  • Wires now connect anything to anything, had some logic about input and output that isn’t needed anymore. Wires also have a gain now for simply rescaling inputs before summing with multiple other signal nodes

3.0a15

Adding additional features for degrees of freedom to allow for better/easier modelling of ASC and other more complex effects. LocalDegreesOfFreedom replaces DOFDefinition, which now has separate AC input and output nodes. Also tested against Sidles-Sigg theory and no internal code changes were needed.

3.0a14

Same as a13 but redoing conda dist for source

3.0a12

Pinning to less than Cython 3

3.0a11

Packaging/CI for windows still problematic, switching to conda instead of mamba due to 404 package errors

3.0a10

Attempt at fixing bad windows tag processing

3.0a9

New alpha update

3.0a8

Bad pypi source pushed for a7

3.0a7

Some recent fixes that improves memory allocation errors/checking and some usability errors.

3.0a6

Alpha 6 release

3.0a5

alpha 5, testing pypi deploy pipeline

3.0a4

alpha 4

3.0a3

Primarily fixes for Windows