finesse.script.spec module

KatScript specification.

This defines supported KatScript syntax and maps it to Finesse Python classes via ItemAdapter objects.

class finesse.script.spec.FsigArgumentsMixin

Bases: object

arguments(**kwargs)

class finesse.script.spec.FsigDocumenter

Bases: FsigArgumentsMixin, CommandMethodDocumenter

argument_descriptions()

The types and descriptions for each argument as parsed from the docstring.

Returns

dict

Mapping of arguments to their type and docstrings as listed in the object’s docstring. Note that the arguments may not correspond to signature argument names; numpydoc allows arguments to share docstrings so some keys may be e.g. n, m.

class finesse.script.spec.FsigDumper

Bases: ItemDumper

class finesse.script.spec.FsigSetter

Bases: FsigArgumentsMixin, ItemSetter

class finesse.script.spec.GaussDumper

Bases: ItemDumper

Dumper for the Gauss component.

Gauss components accept many different forms of argument to define the beam parameter but only store these internally as q parameters. This dumper therefore tries to figure out how the parameters were defined by the user (either via Python or KatScript) and generates parameters based on that.

class finesse.script.spec.KatSpec

Bases: object

KatScript language specification.

This defines the available KatScript elements, commands, and analyses that the parser recognises. These directives are mapped by this object to adapter classes to convert between KatScript and Finesse objects.

Additional directives can be registered at runtime using register_element(), register_command(), and register_analysis(). These adapters will remain for the rest of the lifetime of the object.

Supported KatScript keywords, constants, operators, and functions are not modifiable by users.

This class should not normally be instantiated by user code; the shared instance in KATSPEC should instead be used.

binary_operators = {'*': <function MAKE_simplify_mul.<locals>.simplify_mul>, '**': <function MAKE_simplify_pow.<locals>.simplify_pow>, '+': <function MAKE_simplify_add.<locals>.simplify_add>, '-': <function MAKE_simplify_sub.<locals>.simplify_sub>, '/': <function MAKE_LOP_simplify_truediv.<locals>.simplify_truediv>, '//': <function <lambda>.<locals>.<lambda>>}

constants = {'c0': c, 'pi': π}

property directives

All top level parser directives.

Getter:

Returns a mapping of top level parser directive aliases to adapters.

Type:

ChainMap

expression_functions = {'abs': <function <lambda>>, 'arange': <function <lambda>>, 'arccos': <function <lambda>>, 'arcsin': <function <lambda>>, 'arctan': <function <lambda>>, 'arctan2': <function <lambda>>, 'conj': <function <lambda>>, 'cos': <function <lambda>>, 'deg2rad': <function <lambda>>, 'degrees': <function <lambda>>, 'dot': <function <lambda>>, 'erf': <function <lambda>>, 'exp': <function <lambda>>, 'geomspace': <function <lambda>>, 'imag': <function <lambda>>, 'jv': <function <lambda>>, 'linspace': <function <lambda>>, 'log': <function <lambda>>, 'log10': <function <lambda>>, 'logspace': <function <lambda>>, 'neg': <function <lambda>>, 'pos': <function <lambda>>, 'pow': <function <lambda>>, 'rad2deg': <function <lambda>>, 'radians': <function <lambda>>, 'real': <function <lambda>>, 'sin': <function <lambda>>, 'sqrt': <function <lambda>>, 'std': <function <lambda>>, 'sum': <function <lambda>>, 'tan': <function <lambda>>}

property function_directives

All top level function-style parser directives.

Getter:

Returns a mapping of top level function parser directive aliases to adapters.

Type:

ChainMap

get_element_class(name: str) → type

Get the corresponding python class for a katscript model element.

Parameters

namestr

name of a katscript element

Returns

type

Python class for this element

Raises

ValueError

When the element can not be found

keywords = {'abcd', 'am', 'bandpass', 'bandstop', 'both', 'div', 'even', 'finesse', 'fsr', 'fwhm', 'g', 'gouy', 'highpass', 'l', 'length', 'lin', 'log', 'loss', 'lowpass', 'modesep', 'none', 'odd', 'off', 'pitch', 'pm', 'pole', 'q', 'rc', 'resolution', 's', 'single', 'stability', 'tau', 'w', 'w0', 'x', 'xsplit', 'y', 'yaw', 'ysplit', 'z', 'zr'}

register_analysis(adapter, **kwargs)

Add parser and generator support for an analysis.

Parameters

adapterItemAdapter

The analysis adapter.

Other Parameters

overwritebool, optional

Overwrite analyses with the same aliases, if present. If False and one of adapter’s aliases already exists, a KeyError is raised. Defaults to False.

register_command(adapter, **kwargs)

Add parser and generator support for a command.

Parameters

adapterItemAdapter

The command adapter.

Other Parameters

overwritebool, optional

Overwrite commands with the same aliases, if present. If False and one of adapter’s aliases already exists, a KeyError is raised. Defaults to False.

register_element(adapter, **kwargs)

Add parser and generator support for a model element such as a component or detector.

Parameters

adapterItemAdapter

The element adapter.

Other Parameters

overwritebool, optional

Overwrite elements with the same aliases, if present. If False and one of adapter’s aliases already exists, a KeyError is raised. Defaults to False.

property reserved_names

All reserved names.

This is primarily useful for tests.

Getter:

Returns the names reserved in the parser as special production types.

Type:

list

type_descriptor(_type, default=None)

Get a descriptor for a type that’s suitable for use in user feedback.

This allows something other than Python class names to be displayed to the user inside error messages.

Supports the same parameters as dict.get().

unary_operators = {'+': <function <lambda>>, '-': <function <lambda>>}

class finesse.script.spec.ModesDumper

Bases: SignatureArgumentMixin, ItemDumper

class finesse.script.spec.PhaseConfigDumper

Bases: SignatureArgumentMixin, ItemDumper

class finesse.script.spec.TEMDocumenter

Bases: CommandMethodDocumenter

argument_descriptions()

The types and descriptions for each argument as parsed from the docstring.

Returns

dict

Mapping of arguments to their type and docstrings as listed in the object’s docstring. Note that the arguments may not correspond to signature argument names; numpydoc allows arguments to share docstrings so some keys may be e.g. n, m.

arguments()

class finesse.script.spec.TEMDumper

Bases: SignatureArgumentMixin, ItemDumper

class finesse.script.spec.TEMSetter

Bases: CommandMethodSetter

class finesse.script.spec.VariableDumper

Bases: ItemDumper

Variable for finesse.components.general.Variable.

finesse.script.spec.add_name_to_other_names(name: str, kwargs: dict) → dict

For ‘make_element’ and ‘make_analysis’, adds the name of the python class to the list of ‘other_names’, which get added in ‘ItemAdapter’ to the list of aliases. Allows ‘Xaxis’ to be recognized as ‘xaxis’ and ‘Beamsplitter’ as ‘beamsplitter’.

Parameters

cls_namestr

Name of the class

kwargsdict

kwargs meant to be passed to ItemAdapter

Returns

dict

kwargs with ‘other_names’ modified to include the class name.

finesse.script.spec.make_analysis(analysis_type, full_name, ref_args=None, **kwargs)

Create a standard analysis adapter.

Use this for analyses that follow the normal behaviour: they are of type Action, their constructor signature defines their attributes, and the attributes are available with the same name in the object.

finesse.script.spec.make_element(element_type, full_name, build_last=False, ref_args=None, **kwargs)

Create a standard element adapter.

Use this for elements that follow the normal behaviour: they are of type ModelElement, their constructor signature defines their attributes, and the attributes are available with the same name in the object.