Using via the command line#

Invoking cavcalc via the command line is a simple, and convenient, way to interact with the program. For details on all the available options run:

cavcalc -h

or just:

cavcalc

Calculating single parameters#

By specifying a target to compute, cavcalc will show you the value of this property given the input arguments you provided. For example, here we calculate the beam radius on the mirrors of a symmetric cavity, given its length and radii of curvature of both mirrors:

cavcalc w -L 1 -Rc 2.5

which results in:

Given:
	Cavity length = 1 m

	Radius of curvature of both mirrors = 2.5 m

	Wavelength of beam = 1064 nm

Computed:
	Radius of beam at mirrors = 0.6506551687525748 mm

Units can be given for both the target, and any input parameter:

cavcalc modesep -u MHz -L 10cm -gouy 0.3rad

yielding:

Given:
	Cavity length = 10 cm

	Round-trip Gouy phase = 0.3 rad

	[UNUSED] Wavelength of beam = 1064 nm

Computed:
	Mode separation frequency = 71.57017738855461 MHz

Hint

Units support is provided via the package Pint, so any units defined in the Pint unit-registry can be used in cavcalc.

So, yes, you can compute the FSR in units of 1/month for a cavity with a length in parsecs if you really want to:

cavcalc FSR -u 1/month -L 0.67pc

Given:
	Cavity length = 0.67 pc

	[UNUSED] Wavelength of beam = 1064 nm

Computed:
	FSR = 0.019067250857459746 / month

(but you probably shouldn’t…)

See the linked documentation above for an up-to-date reference on the relevant units defined in the registry.

Computing all available parameters#

The default behaviour of cavcalc, i.e. when it is given no target, is to attempt to compute all the properties that it possibly can from the set of input arguments provided. For example, we could request the properties of a cavity based on knowledge of its length and mirror radii of curvature:

cavcalc -L 33cm -Rc1 30cm -Rc2 20cm

Given:
	Cavity length = 33 cm

	Radius of curvature of first mirror = 30 cm
	Radius of curvature of second mirror = 20 cm

	Wavelength of beam = 1064 nm

Computed:
	FSR = 454230996.96969694 Hz
	Mode separation frequency = 189841605.0631232 Hz

	Position of beam waist (from first mirror) = 0.26812499999999995 m

	Radius of beam at first mirror = 0.5428480523810602 mm
	Radius of beam at second mirror = 0.2129225240005281 mm
	Radius of beam at waist = 0.17694681643710908 mm

	Stability g-factor of cavity = 0.06500000000000004
	Stability g-factor of first mirror = -0.10000000000000009
	Stability g-factor of second mirror = -0.6499999999999999

	Round-trip Gouy phase = 209.54136050014282 deg

	Divergence angle = 0.10966577294286263 deg

This is flexible in that, as usual, any valid argument can be used. Following on from the above example, we could flip this around to instead compute all we can from the cavity length and beam radii on the mirrors:

cavcalc -L 33cm -w1 542.85um -w2 212.92um

giving us values consistent with the above cavity:

Given:
	Cavity length = 33 cm

	Radius of beam at first mirror = 542.85 µm
	Radius of beam at second mirror = 212.92 µm

	Wavelength of beam = 1064 nm

Computed:
	FSR = 454230996.96969694 Hz
	Mode separation frequency = [189846138.40893644 189846138.4089364] Hz

	Position of beam waist (from first mirror) = [0.2681279878873774 0.31136839530042726] m

	Radius of curvature of first mirror = [0.3000036643177014 0.366661192957933] m
	Radius of curvature of second mirror = [0.20000815302646005 0.9426759882025959] m

	Radius of beam at waist = [0.1769482481502113 0.21080536082624143] mm

	Stability g-factor of cavity = [0.06498454174718371 0.06498454174718371]
	Stability g-factor of first mirror = [-0.09998656433253654 0.09998656433253654]
	Stability g-factor of second mirror = [-0.6499327402735564 0.6499327402735564]

	Round-trip Gouy phase = [209.5377676046697 150.4622323953303] deg

	Divergence angle = [0.10966488562387439 0.09205181651507605] deg

Note that, in this case, we also get a set of values corresponding to a different cavity geometry - i.e. on the opposite side of the stability plot. This is simply a result of the equations which govern Fabry-Perot cavity dynamics; and the varying cavity shapes that they represent (e.g. near-concentric vs. near plane-parallel for the same beam radius values). The above output shows that cavcalc computes, and shows, both scenarios when input values result in them.

Working with cavcalc.ini files — local unit overrides

The -u (units override for target) option only applies to single-target mode; i.e. when a target is specified. To override units for computed properties in multi-target mode, when invoking via the CLI, you should use a cavcalc.ini configuration file. This can be done by either:

  • modifying the config file located at $XDG_CONFIG_HOME/cavcalc/cavcalc.ini, typically ~/.config/cavcalc/cavcalc.ini, on *nix systems, or %APPDATA%\cavcalc\cavcalc.ini on Windows,

  • or making a new cavcalc.ini file in the current working directory (or wherever you are invoking cavcalc from). Note that this new file doesn’t need to contain all the options that the file referenced above contains, you would only need to override the specific units that you want.

You should prefer the latter option from above generally, as the former would result in behaviour changing for any usage of cavcalc on your system until such modifications are reversed. Using a new, trimmed down cavcalc.ini file in your working directory is the recommended approach for this use case.

As an example, let’s assume you are working in the directory ~/work/local/cav_design_x, and you want any cavcalc commands executed from this folder to use default units of mm for distances and mirror radii of curvatures, microns for beam radii, and GHz for frequencies. To do this, you could create a new file ~/work/local/cav_design_x/cavcalc.ini with the following contents:

[units]

Beamsizes = um
RoCs = mm
Distances = mm
Frequencies = GHz

Then invoking cavcalc from this directory would use these unit category overrides as the defaults, e.g:

cavcalc -L 56 -Rc1 25.5 -Rc2 35

Given:
	Cavity length = 56 mm

	Radius of curvature of first mirror = 25.5 mm
	Radius of curvature of second mirror = 35 mm

	Wavelength of beam = 1064 nm

Computed:
	FSR = 2.676718375 GHz
	Mode separation frequency = 0.47731829070785287 GHz

	Position of beam waist (from first mirror) = 22.834951456310677 mm

	Radius of beam at first mirror = 158.99728556011118 µm
	Radius of beam at second mirror = 224.48840499807176 µm
	Radius of beam at waist = 51.401072623419914 µm

	Stability g-factor of cavity = 0.7176470588235291
	Stability g-factor of first mirror = -1.1960784313725488
	Stability g-factor of second mirror = -0.5999999999999999

	Round-trip Gouy phase = 295.80401051536586 deg

	Divergence angle = 0.3775164852670658 deg

Alternatively, you could use the Python API without needing to create or modify cavcalc.ini files. The function to use for this is configure(), allowing for temporary overrides of parameter units within context-managed scopes. See Using via the Python API for more information on using cavcalc via the API.

Evaluating and plotting parameters over data-ranges#

In addition to the scalar input values shown previously, cavcalc also supports a data-range syntax for such input arguments; resulting in targets being computed over arrays of values. This then enables automatic plotting of such targets via the CLI.

The data-range syntax is -param "start stop num [units]", where start, stop are the first and last values of the array, num is the number of points, and units (optional) represents the physical units of the quantity. Values may also be read in from a file via -param <file>; as long as the data in <file> represents a 1D array.

A few examples follow:

  • Round-trip Gouy phase versus mirror radii of curvature:

    cavcalc gouy -L 12.4mm -Rc "10 20 499 mm" --plot
../_images/command_line_6_0.png

  • Beam radius at the waist (on a log-scale) versus beam radius at the mirrors:

    cavcalc w0 -u um -L 15cm -w "200 1000 500 um" --logyplot
../_images/command_line_7_0.png

  • Mode separation frequency versus both cavity length and g-factor of first mirror, with a fixed second mirror g-factor:

    cavcalc modesep -u MHz -L "20 30 200" -g1 "-1 0 200" -g2 -0.6 --plot
../_images/command_line_8_0.png

  • FWHM versus mirror losses with fixed transmission values:

    cavcalc FWHM -L 4km -T1 0.014 -L1 "1e-5 1e-3 201" -T2 5e-6 -L2 "1e-5 1e-3 201" --logxplot
../_images/command_line_9_0.png

Hint

Arguments can be set to reference other parameters. In the last example above, the loss values at both mirrors are repeated - so we could instead write:

cavcalc FWHM -L 4km -T1 0.014 -L1 "1e-5 1e-3 201" -T2 5e-6 -L2 L1 --logxplot

to produce the same results.

This referencing can be applied to any parameters with the same dimensionality, and can be used to reference data-ranges (as we saw above) or scalar values. One can also reference parameters which themselves are references, so long as there are no self-references or loops in the referencing chain.

Grid evaluation and image plots#

Parameters with multiple dependencies can be computed over more than just a single dimension. By using the --mesh option, one can specify grids over which to compute cavity properties. If multiple data-range arguments are given without meshing, then the target(s) will be computed over these simultaneously; as we saw in the last two examples of the previous section.

The --mesh argument can be set to true, such that any data-range arguments are meshed together in the order that they were given, or it can be given as --mesh "param1,param2,..." where the param<n> values here represent the names of the data-range parameters specified. Multiple mesh-grids over different parameter combination can be defined by delimiting with ;, e.g: --mesh "g1,g2;L,R1,R2" would create a mesh-grid of parameters g1 and g2, as well as another separate mesh of parameters L, R1, and R2, respectively.

Here are a few examples of this in action:

  • Beam radius at mirrors versus the cavity length and round-trip Gouy phase on a grid:

    cavcalc w -L "1 10 100 km" -gouy "20 120 100 deg" --mesh true --plot
../_images/command_line_10_0.png

  • Waist radius versus the individual mirror g-factors on a grid, with a colour map specified, and using a log-scale:

    cavcalc w0 -L 1 -g1 "-2 2 399" -g2 g1 --mesh true --logplot --cmap nipy_spectral
../_images/command_line_11_0.png

  • Divergence angle versus the beam radius at the mirrors, and the wavelength of the beam, on a grid. Notice here that wl was specified before w, but we used --mesh "w,wl" to explicitly declare that the mesh-grid should constructed in this order; resulting in w being the x-axis parameter on the plots below:

    cavcalc div -L 34mm -wl "1 2 200 um" -w "150 300 200 um" --mesh "w,wl" --plot -u arcmin
../_images/command_line_12_0.png

  • Pole frequency versus mirror losses on a grid, with fixed transmission values:

    cavcalc pole -u GHz -L 67um -L1 "1e-6 1e-4 200" -T1 0.02 -L2 L1 -T2 1e-4 --plot --mesh true --cmap cividis
../_images/command_line_13_0.png

Note

You can also use data-ranges, and meshes, when no target is specified (i.e. for computing all available parameters over the arrays given). This works identically to the single target mode, with no change in syntax for invoking cavcalc. By using the --plot option (or the log-plot alternatives) in this mode, you will get separate figures for each target which was computed as an array.

This will often result in quite a few figures being produced when some common arguments (like cavity length and mirror radii of curvature) are given, so in the interest of saving space on this page, a short example is shown below; where we only specify an array of values for gs and give nothing else to cavcalc:

cavcalc -gs "-1 1 201" --plot
../_images/command_line_14_0.png ../_images/command_line_14_1.png

Saving and loading cavcalc results#

The CLI provides two arguments, "-save" and "-load", which can be used for saving the output to a binary file, and loading an output from such a file, respectively. Any extension may be given to the file when saving it. The standard Python package pickle is used for supporting serialisation of the output objects produced by cavcalc.

The default behaviour when loading is to just get the output object “as-is” from the file; so you do not need to re-specify the target if the loaded file represents an output object from a previous single-target mode call. If you do specify a target, but this does not match the one computed in the output file, then an error message will be shown.

You can specify a single target when loading a file representing a multi-target output object (so long as that target was computed), e.g:

cavcalc -L 10cm -Rc1 6cm -Rc2 7.85cm -save "10cm_resonator.cav"

The above saves a multi-target output object to a file "10cm_resonator.cav" within the current working directory. Then we can show just the beam radius at the waist from this file via:

cavcalc w0 -u um -load "10cm_resonator.cav"

Given:
	Cavity length = 10 cm

	Radius of curvature of first mirror = 6 cm
	Radius of curvature of second mirror = 7.85 cm

	Wavelength of beam = 1064 nm

Computed:
	Radius of beam at waist = 100.10323552763585 µm