solprop.plotting.geometry#

Draw the cross-section of a guide or a free-space grid.

The drawing is the outline of a cross-section: a hollow guide’s wall and gas-filled bore, an antiresonant fibre’s tubes and jacket, a solid fibre’s core and cladding, a planar guide’s plates, and a free-space grid’s medium with its absorbing collar. Mode fields, node sets and labels are not drawn: they belong to the figure that shows them.

The geometry is computed once, by outline(), as a tuple of plain shapes in metres (Disc, Ring, Box), each naming the region it fills. draw() paints those shapes into a Matplotlib axes, and thumbnail() makes a small figure of a route’s representative guide for a front end’s route picker. The user guide’s cross-section figures draw the same shapes as SVG, so the guide and the library show one geometry. Colours come from an explicit Palette of #rrggbb strings, which Matplotlib, SVG viewers and Qt all read the same way; LIGHT and DARK are the two built in.

What a model does not describe is drawn to a stated convention, never inferred: a hollow guide’s wall, and an antiresonant fibre’s jacket, are WALL_FRACTION of the guide’s size thick, and a direction a geometry leaves unbounded (a fibre’s cladding, a planar guide’s or a line grid’s y) is drawn to an extent the caller may choose. Everything else is to scale. The manual page is docs/guide/results/plotting.md.

Module Attributes

`Region`	What a shape is: the propagation medium (a hollow guide's gas, free space), a guide's glass or metal wall (a capillary's, a tube's, a plate), a solid guide's core or cladding, or a free-space grid's absorbing collar.
`WALL_FRACTION`	Drawn thickness of a hollow guide's wall, as a fraction of its size: of a capillary's or an antiresonant fibre's core radius (the jacket), of a rectangular guide's larger half-width and of a planar guide's half gap.
`DRAWN_CLADDING`	Default drawn radius of a solid fibre's cladding, in core radii: the cladding is unbounded in the model.
`LIGHT`	The palette on a light ground, the default: the user guide's figures use it.
`DARK`	The same palette on a dark ground.
`Shape`	One shape of an outline.
`THUMBNAILS`	The `(route, representation)` pairs `thumbnail()` draws, each with what it shows.

Functions

`draw`(ax, guide, *[, palette, z, extent])	Draw the cross-section of a guide or a free-space grid into an axes.
`outline`(guide, *[, z, extent])	Return the cross-section of a guide or a free-space grid, as shapes in metres.
`thumbnail`(route, representation[, size, palette])	Return a small square figure of a route's representative cross-section.

Classes

`Box`(lower, upper, region)	A filled axis-aligned rectangle.
`Disc`(centre, radius, region)	A filled circle.
`Palette`(background, medium, medium_edge, ...)	The colours of a cross-section drawing, one fill and one edge per region.
`Ring`(centre, inner, outer, region)	A filled ring between two radii.

class solprop.plotting.geometry.Box(lower, upper, region)[source]#

Bases: object

A filled axis-aligned rectangle.

Attributes:

lowertuple of float: The corner of least x and least y, in m.
uppertuple of float: The corner of greatest x and greatest y, in m.
region{‘medium’, ‘wall’, ‘core’, ‘cladding’, ‘collar’}: What it is.

lower: tuple[float, float]#

region: Literal['medium', 'wall', 'core', 'cladding', 'collar']#

upper: tuple[float, float]#

solprop.plotting.geometry.DARK: Final = Palette(background='#171a1f', medium='#18222f', medium_edge='#7ba6e8', wall='#173528', wall_edge='#5cb98a', core='#1d3150', core_edge='#7ba6e8', cladding='#173528', cladding_edge='#5cb98a', collar='#3a2b15', collar_edge='#e0a44f', boundary='#ee8ca0')#: The same palette on a dark ground.

solprop.plotting.geometry.DRAWN_CLADDING: Final = 3.0#: Default drawn radius of a solid fibre’s cladding, in core radii: the cladding is unbounded in the model.

class solprop.plotting.geometry.Disc(centre, radius, region)[source]#

Bases: object

A filled circle.

Attributes:

centretuple of float: (x, y) in m.
radiusfloat: In m.
region{‘medium’, ‘wall’, ‘core’, ‘cladding’, ‘collar’}: What it is.

centre: tuple[float, float]#

radius: float#

region: Literal['medium', 'wall', 'core', 'cladding', 'collar']#

solprop.plotting.geometry.LIGHT: Final = Palette(background='#fbfbfd', medium='#e9f1fb', medium_edge='#2f5eb0', wall='#d5e9dc', wall_edge='#2c7a55', core='#cfe0f4', core_edge='#2f5eb0', cladding='#d5e9dc', cladding_edge='#2c7a55', collar='#f8e8d2', collar_edge='#a96a15', boundary='#b8334f')#: The palette on a light ground, the default: the user guide’s figures use it.

class solprop.plotting.geometry.Palette(background, medium, medium_edge, wall, wall_edge, core, core_edge, cladding, cladding_edge, collar, collar_edge, boundary)[source]#

Bases: object

The colours of a cross-section drawing, one fill and one edge per region.

Every colour is a #rrggbb string, which Matplotlib, SVG and Qt read alike.

Attributes:

backgroundstr: The ground behind the drawing; thumbnail() paints it, and draw() leaves the axes’ own.
medium, medium_edgestr: The propagation medium: a hollow guide’s gas, free space.
wall, wall_edgestr: A guide’s wall: a capillary’s, a tube’s or the jacket of an antiresonant fibre, a plate.
core, core_edgestr: A solid guide’s core.
cladding, cladding_edgestr: A solid guide’s cladding.
collar, collar_edgestr: A free-space grid’s absorbing collar.
boundarystr: The dashed outline of what a representation propagates, in thumbnail().

Raises:

ProcessingError: If a colour is not a #rrggbb string.

Examples

>>> from dataclasses import replace
>>> from solprop.plotting.geometry import LIGHT
>>> replace(LIGHT, wall="#cccccc").fill("wall")
'#cccccc'

background: str#

boundary: str#

cladding: str#

cladding_edge: str#

collar: str#

collar_edge: str#

core: str#

core_edge: str#

edge(region)[source]#

Return the edge colour of a region.

Parameters:

region{‘medium’, ‘wall’, ‘core’, ‘cladding’, ‘collar’}: The region.

Returns:

str: A #rrggbb colour.

fill(region)[source]#

Return the fill colour of a region.

Parameters:

region{‘medium’, ‘wall’, ‘core’, ‘cladding’, ‘collar’}: The region.

Returns:

str: A #rrggbb colour.

medium: str#

medium_edge: str#

wall: str#

wall_edge: str#

solprop.plotting.geometry.Region#

What a shape is: the propagation medium (a hollow guide’s gas, free space), a guide’s glass or metal wall (a capillary’s, a tube’s, a plate), a solid guide’s core or cladding, or a free-space grid’s absorbing collar.

alias of Literal[‘medium’, ‘wall’, ‘core’, ‘cladding’, ‘collar’]

class solprop.plotting.geometry.Ring(centre, inner, outer, region)[source]#

Bases: object

A filled ring between two radii.

Attributes:

centretuple of float: (x, y) in m.
inner, outerfloat: The two radii, in m, 0 < inner < outer.
region{‘medium’, ‘wall’, ‘core’, ‘cladding’, ‘collar’}: What it is.

centre: tuple[float, float]#

inner: float#

outer: float#

region: Literal['medium', 'wall', 'core', 'cladding', 'collar']#

solprop.plotting.geometry.Shape = solprop.plotting.geometry.Disc | solprop.plotting.geometry.Ring | solprop.plotting.geometry.Box#: One shape of an outline.

solprop.plotting.geometry.THUMBNAILS: Final[Mapping[tuple[str, str], str]] = {('capillary', 'mode_averaged'): "a capillary of 50 um bore radius, and the disc of its HE11 mode's effective area", ('capillary', 'multimode'): 'a capillary of 50 um bore radius', ('free', 'free'): 'Cartesian free space: the periodic box and its collar', ('gnlse', 'mode_averaged'): "a step-index strand, 1.25 um in radius, and the disc of its mode's effective area", ('planar', 'slab'): 'a planar guide resolved in y, with its periodic y collar', ('radial', 'radial'): 'radial free space with its absorbing collar', ('waveguide', 'multimode'): 'a rectangular hollow guide, 100 um by 50 um'}#: The (route, representation) pairs thumbnail() draws, each with what it shows. A route is a prop_* entry point’s name and a representation one of SimulationKind.

solprop.plotting.geometry.WALL_FRACTION: Final = 0.18#: Drawn thickness of a hollow guide’s wall, as a fraction of its size: of a capillary’s or an antiresonant fibre’s core radius (the jacket), of a rectangular guide’s larger half-width and of a planar guide’s half gap. None of these models has a wall thickness of its own: the wall enters only through the effective index.

solprop.plotting.geometry.draw(ax, guide, *, palette=Palette(background='#fbfbfd', medium='#e9f1fb', medium_edge='#2f5eb0', wall='#d5e9dc', wall_edge='#2c7a55', core='#cfe0f4', core_edge='#2f5eb0', cladding='#d5e9dc', cladding_edge='#2c7a55', collar='#f8e8d2', collar_edge='#a96a15', boundary='#b8334f'), z=0.0, extent=None)[source]#

Draw the cross-section of a guide or a free-space grid into an axes.

The shapes of outline(), filled and edged by region, in micrometres, on equal axes labelled x (um) and y (um). The axes’ own background is left alone; thumbnail() paints the palette’s.

Parameters:

axmatplotlib.axes.Axes: The axes to draw into.
guideobject: The guide or grid, any that outline() takes.
palettePalette, optional: The colours; LIGHT by default.
zfloat, optional: Position along the guide, in m. Default 0.
extentfloat or None, optional: How far to draw an unbounded direction, in m, as for outline().

Returns:

list of matplotlib.patches.Patch: The patches added, back to front.

Raises:

ProcessingError: As outline() does.

Examples

>>> import matplotlib.pyplot as plt
>>> from solprop.modes import MarcatiliMode, TubeLattice, VincettiMode
>>> from solprop.plotting.geometry import draw
>>> lattice = TubeLattice(wall_thickness=180e-9, tube_radius=9e-6, n_tubes=6)
>>> fibre = VincettiMode(15e-6, cladding=1.45, lattice=lattice)
>>> figure, ax = plt.subplots()
>>> len(draw(ax, fibre))
8
>>> plt.close(figure)

solprop.plotting.geometry.outline(guide, *, z=0.0, extent=None)[source]#

Return the cross-section of a guide or a free-space grid, as shapes in metres.

The shapes are in drawing order, back to front, centred on the guide’s axis. A hollow guide’s wall and an antiresonant fibre’s jacket are WALL_FRACTION of its size thick, since no model carries a wall thickness; everything else is to scale.

Parameters:

guideobject: What to draw: a capillary (MarcatiliMode, and the tabulated modes built on it, drawn as their field’s bore), an antiresonant fibre (VincettiMode), a step-index fibre (StepIndexMode), a graded-index provider (GradedIndexProvider), a rectangular guide (RectMode), a planar guide (SlabMode), a PlanarGrid, a ModeCollection or a ModalGuide of any of these, or a free-space grid (RadialGrid, FreeGrid, LineGrid).
zfloat, optional: Position along the guide, in m, where a radius or a width that varies along z is read. Default 0.
extentfloat or None, optional: How far to draw what the geometry leaves unbounded, in m: the cladding radius of a solid fibre (DRAWN_CLADDING core radii by default), the half-height in y of a planar guide or a line grid (square by default). Refused for a geometry bounded in every direction.

Returns:

tuple of Shape: The regions, back to front.

Raises:

ProcessingError: If the guide is of a kind this module does not draw, if extent is given for a bounded geometry or is not positive and finite, or if a fibre’s drawn cladding would not enclose its core.

Examples

>>> from solprop.modes import MarcatiliMode
>>> from solprop.plotting.geometry import outline
>>> wall, bore = outline(MarcatiliMode(50e-6, cladding=1.45))
>>> wall.region, bore.region, bore.radius
('wall', 'medium', 5e-05)

solprop.plotting.geometry.thumbnail(route, representation, size=128, *, palette=Palette(background='#fbfbfd', medium='#e9f1fb', medium_edge='#2f5eb0', wall='#d5e9dc', wall_edge='#2c7a55', core='#cfe0f4', core_edge='#2f5eb0', cladding='#d5e9dc', cladding_edge='#2c7a55', collar='#f8e8d2', collar_edge='#a96a15', boundary='#b8334f'))[source]#

Return a small square figure of a route’s representative cross-section.

For a front end’s route picker: the outline of a typical guide or grid on the route (THUMBNAILS says which), with no axes, on the palette’s background. A mode-averaged representation adds the dashed disc of the mode’s effective area, the one area the route propagates.

The figure is a bare matplotlib.figure.Figure, made without matplotlib.pyplot, so it touches no global state and needs no closing: save it with figure.savefig(target, format="png") (size pixels square at its own dpi) or format="svg", or show it in Qt through matplotlib.backends.backend_qtagg.FigureCanvasQTAgg(figure).

Parameters:

routestr: The route: gnlse, capillary, waveguide, radial, free or planar.
representationstr: The transverse representation, as a run records it (SimulationKind).
sizeint, optional: Width and height in pixels, at least 16. Default 128.
palettePalette, optional: The colours; LIGHT by default.

Returns:

matplotlib.figure.Figure: A figure of size / 100 inches square at 100 dpi, with one axes filling it.

Raises:

ProcessingError: If the pair is not in THUMBNAILS or size is too small.

Examples

>>> from solprop.plotting.geometry import DARK, thumbnail
>>> figure = thumbnail("capillary", "mode_averaged", 64, palette=DARK)
>>> figure.canvas.get_width_height()
(64, 64)