at.plot.resonances#

AT plotting functions related to resonances.

Functions

farey_sequence(nthorder[, verbose])

Return the Farey sequence, and the resonance sequence of nth order.

plot_tune_diagram([orders, periodicity, ...])

Plot the tune diagram and resonance lines for the given orders, periodicity and window.

create_linepalette([linestyle, linecolor, ...])

Create a line palette to plot resonance lines.
create_linepalette(linestyle=None, linecolor=None, linewidth=None, addtolabel=None)[source]#

Create a line palette to plot resonance lines.

Parameters:

  • linestyle (str | dict) –

    If a dictionary is passed, it should contain {“normal”: style1, “skew”: style2}

    If ‘dots’ it uses dotted styles as linestyles. Equivalent to: {“normal”: “dashdot”, “skew”: “dotted”}

    Default: {“normal”: ‘-’, “skew”: ‘–‘}

  • linecolor (str) – line color, e.g. “k”. Default: custom values. See plot_tune_diagram()

  • linewidth (int) – line width. Default: custom values. See plot_tune_diagram()

  • addtolabel (str) – adds a string to the line label

Returns:

palette – dictionary containing the line properties for resonance plots.

farey_sequence(nthorder, verbose=False)[source]#

Return the Farey sequence, and the resonance sequence of nth order.

Parameters:

  • nthorder (int) – natural number bigger than 0.

  • verbose (bool) – prints extra info. Default: False.

Returns:

  • fareyseqfloat – list of elements with the Farey sequence in Float format. See Eqs.(1,2,3) of [1].

  • fareyseqfrac – list of elements with the Farey sequence in Fraction format. See Eqs.(1,2,3) of [1].

Raises:

ValueError – if given order is lower than 0, or window is zero.

[1] R.Tomas. ‘From Farey sequences to resonance diagrams.

Phys.Rev.Acc.Beams 17, 014001 (2014)’

plot_tune_diagram(orders=(1, 2, 3), periodicity=1, window=(0, 1, 0, 1), verbose=False, legend=False, show=True, block=False, debug=False, axes=None, linestyle=None, linecolor=None, linewidth=None, addtolabel=None, **kwargs)[source]#

Plot the tune diagram and resonance lines for the given orders, periodicity and window.

The resonance equation is \(a\nu_x + b\nu_y = c\) with \(a,b\) and \(c\) integers. The order is: \(N=abs(a)+abs(b)\).

Parameters:

  • orders (int | tuple[int]) – integer or tuple of integers larger than zero. Default (1, 2, 3).

  • periodicity (int) – periodicity of the machine, integer larger than zero. Default: 1.

  • window (list) – (nux_min, nux_max, nuy_min, nuy_max): tuple of 4 values for the tune minimum and maximum window. Default: (0, 1, 0, 1). window is ignored if the parameter axes is given.

  • verbose (bool) – print verbose output.

  • legend (bool) – print legend on the plot. Default: False.

  • show (bool) – show plot. Default: True.

  • block (bool) – passed to plot.show(). Default: False.

  • debug (bool) – extra output to check line construction. Default: False.

  • axes (matplotlib.axes.Axes) – Axes for plotting the resonances. If None, a new figure will be created. Note that if axes are given then window is ignored.

  • linestyle (dict or str) –

    line style for normal and skew resonances.

    If a dictionary is passed, it should contain {“normal”: style1, “skew”: style2}

    If ‘dots’ it uses dotted styles as linestyles. Equivalent to: {“normal”: “dashdot”, “skew”: “dotted”}

    Default: {“normal”: ‘-’, “skew”: ‘–‘}

  • linecolor (str or any) – single color for all resonances. Default: custom palette. See Lines Color and Width

  • linewidth (int) – line width for all resonances. Default: custom values. See Lines Color and Width

  • addtolabel (str) – adds a string to the line label, e.g. for the fourth order normal resonance “4n”+addtolabel

Keyword Arguments:

  • only (str) –

    if ‘normal’, plot only normal resonances.

    if ‘skew’ plots only skew resonances.

    Otherwise, ignored. See the notes on Normal and Skew convention.

  • linedict (dict) – dictionary of custom line styles. See notes below.

Returns:

  • Axes (matplotlib.axes.Axes) – object from matplotlib.axes._axes

  • legend_h (list) – list of handles for the legend

  • legend_lab (list) – list of labels for the legend

NOTES:

Normal and Skew convention: Line style is similar to reson.m from Matlab Middle Layer, MML, by L. Nadolski. Normal resonances are plotted with a continuous line. Skew resonances, i.e. N-abs(a) is odd, are plotted in dashed lines.

Lines Color and Width: Line style is similar to reson.m from Matlab Middle Layer, MML, by L. Nadolski. 1st: black, width 4 2nd: blue, width 3 3rd: red, width 2 4th: green, width 1 5th: magenta, witdh 1 6th: cyan, width 1 7th: yellow, width 1 8th: darkcyan, width 1 9th: ‘lightgreen’, width 1 10th to 15th: RGB increased in steps of 0.1, width 1

Custom Style: You could pass a custom line style in a dictionary as linedict=mydictionary, where mydictionary should contain two entries: dict(“normal”: normald, “skew”: skewd). normald and skewd are also dictionaries, each entry contains as key the resonance order and as value the line properties to use in the plot. The default dictionary is created with create_linepalette() mydictionary = at.plot.resonances.create_linepalette() you could edit the needed entries.

Raises:

ValueError – if given resonances are lower than 0, or window is zero.