# PLaSK User Manual

#### Page Contents

- `plask` package
  - Modules
  - Classes
  - Functions
  - Constants
  - Descriptions
    - `loadxpl()`
    - `runxpl()`
    - `print_log()`
    - `save_field()`
    - `load_field()`
    - `plot_profile()`
    - `plot_field()`
    - `plot_vectors()`
    - `plot_stream()`
    - `plot_geometry()`
    - `plot_mesh()`
    - `plot_boundary()`

# `plask` package

PLaSK (Photonic Laser Simulation Kit) is a comprehensive toolkit for simulation of various micro-scale photonic devices. It is particularly well suited for analysis of semiconductor lasers, as it allows to perform simulations of various physical phenomena with different models: thermal, electrical, quantum and optical. PLaSK takes care of considering mutual interactions between these models and allows to easily perform complex self-consistent analysis of complete devices.

## Modules

`geometry` | PLaSK geometry classes.
`mesh` | Meshes classes.
`material` | Materials and material database.
`flow` | Data flow classes for standard properties.
`phys` | Basic physical constants and utility functions.
`util` | Auxiliary PLaSK utilities.

## Classes

`config` | Global PLaSK configuration.
`vec` | PLaSK vector.
`Data` | Data returned by field providers.
`IterativeParams` | Iterative matrix parameters
`Manager` | Main input manager.
`MaterialField` | Distribution of materials for a given geometry on a mesh.
`StepProfile` | Step profile for use in custom providers.
`Solver` | Base class for all solvers.
`XplWriter` | XPL writer that can save existing geometries and meshes to the XPL.

## Functions

`loadxpl`(source[, defs, sections, ...]) | Load the XPL file.
`runxpl`(source[, defs]) | Load and run the code from the XPL file.
`print_log`(level, *args) | Print log message into a specified log level.
`save_field`(field, file[, path, mode, compress]) | Save field to HDF5 file.
`load_field`(file[, path]) | Load field from HDF5 file.
`plot_profile`(field[, comp, swap_axes, axes, ...]) | Plot a scalar real field value along one axis.
`plot_field`(field[, levels, plane, fill, ...]) | Plot scalar real fields as two-dimensional color map.
`plot_vectors`(field[, plane, axes, figure, ...]) | Plot vector field with arrows.
`plot_stream`(field[, plane, axes, figure, ...]) | Plot vector field as a streamlines.
`plot_geometry`(geometry[, color, lw, plane, ...]) | Plot specified geometry.
`plot_mesh`(mesh[, color, lw, plane, margin, ...]) | Plot two-dimensional mesh.
`plot_boundary`(boundary, mesh, geometry[, ...]) | Plot boundary conditions.

## Constants

`JOBID` | Job index: either a job ID in batch submission system or a float indicating lauch time (that can be converted to `time.time()`).
`ARRAYID` | Array index in batch submission system. `None` if the job is not a part of an array.
`PROCID` | Process index for parallel computations (eg. MPI). `None` if this is a regular or serial job.

## Descriptions

Function Details

plask.loadxpl(source, defs={}, sections=None, destination=None, update=False)

  Load the XPL file. All sections contents is read into the destination scope.

  Parameters:

    - source (str) – Name of the XPL file or open file object.

    - defs (dict) – Optional dictionary with substitution variables. Values specified in the <defines> section of the XPL file are overridden with the one specified in this parameter.

    - sections (list) – List of section names to read.

    - destination (dict) – Destination scope. If None, `globals()` is used.

    - update (bool) – If the flag is `False`, all data got from the previous call to `loadxpl()` are discarded. Set it to `True` if you want to append some data from another file.

plask.runxpl(source, defs={})

  Load and run the code from the XPL file. Unlike `loadxpl()` this function does not modify the current global scope.

  Parameters:

    - source (str) – Name of the XPL file or open file object.

    - defs (dict) – Optional dictionary with substitution variables. Values specified in the <defines> section of the XPL file are overridden with the one specified in this parameter.

plask.print_log(level, *args)

  Print log message into a specified log level.

  Parameters:

    - level (str) – Log level to print the message to.

    - args – Items to print. They are concatenated together and separated by space, similarly to the `print` function.

plask.save_field(field, file, path='', mode='a', compress=None)

  Save field to HDF5 file.

  Parameters:

    - file (str or file) – File to save to. It should be either a filename or a h5py.File object opened for writing.

    - field (plask.Data) – Field to save. It should be an object returned by PLaSK provider that contains calculated field.

    - path (str) – HDF5 path (group and dataset name), under which the data is saved in the HDF5 file.

    - mode (str) – Mode used for opening new files.

    - compress (None or int) – Compression level. If None, data is not compressed.

  If `file` is a string, a new HDF5 file is opened with the mode specified by `mode`. Then both the data and its mesh are written to this file under the path specified by the `path` argument. It can contain slashes (‘/’), in which case a corresponding hierarchy is created in the HDF5 file.

  Saved data can later be restored by any HDF5-aware application, or by `load_field` function of PLaSK.

  Example

  You may save data retrieved from a provider to file as follows:

      >>> data = my_solver.outMyData(my_mesh)
      >>> save_field('myfile.h5', data, 'mygroup/mydata', 'a')

  In another PLaSK session, you may retrieve this data and plot it or provide to some receiver:

      >>> data = load_field('myfile.h5', 'mygroup/mydata')
      >>> plot_field(data)
      >>> other_solver.inMyData = data

plask.load_field(file, path='/')

  Load field from HDF5 file.

  Parameters:

    - file (str or file) – File to load from. It should be either a filename or a h5py.File object opened for reading.

    - path (str) – HDF5 path (group and dataset name), under which the data is located in the HDF5 file.

  Returns:

    Read plask.Data object.

  If `file` is a string, a new HDF5 file is opened for reading. Then both the data and its mesh are read from this file from the path specified by the `path` argument. `path` can contain slashes (‘/’), in which case the corresponding hierarchy in the HDF5 file is used.

  Example

  You may save data retrieved from a provider to file as follows:

      >>> data = my_solver.outMyData(my_mesh)
      >>> save_field('myfile.h5', data, 'mygroup/mydata', 'a')

  In another PLaSK session, you may retrieve this data and plot it or provide to some receiver:

      >>> data = load_field('myfile.h5', 'mygroup/mydata')
      >>> plot_field(data)
      >>> other_solver.inMyData = data

plask.plot_profile(field, comp=None, swap_axes=False, axes=None, figure=None, **kwargs)

  Plot a scalar real field value along one axis.

  This function creates a classical plot of a scalar field. The field must be obtained on a rectangular mesh that has a single point in all dimensions but one. In other words, the field must be obtained over a single line which is used as an argument axis of this plot.

  Parameters:

    - field (Data) – The field to plot. As it is usually returned by providers, it already contains the mesh and field values.

    - comp (int or str) – If the vector field is plotted, this argument must specify the component to plot. It can be either a component number or its name.

    - swap_axes (bool) – If False, the mesh position is plotted on the horizontal axis and the field value on the vertical one and otherwise if this argument is True.

    - axes (Axes) – Matplotlib axes to which the geometry is drawn. If None (the default), new axes are created.

    - figure (Figure) – Matplotlib destination figure. This parameter is ignored if axes are given. In None, the geometry is plotted to the current figure.

    - **kwargs – Keyword arguments passed to `plot` function.

plask.plot_field(field, levels=16, plane=None, fill=True, antialiased=False, comp=None, axes=None, figure=None, **kwargs)

  Plot scalar real fields as two-dimensional color map.

  This function uses `contourf` of `contour` functions to plot scalar real fields returned by providers. It can also plot a single component of a vector or tensor field; in such case the component must be specified with the `comp` argument.

  Parameters:

    - field (Data) – The field to plot. As it is usually returned by providers, it already contains the mesh and field values.

    - levels (int or sequence) – Number of value bands to plot of a sequence containing the bands.

    - plane (str) – If the field to plot is a 3D one, this argument must be used to select to which the field is projected. The field mesh must be flat in this plane i.e. all its points must lie at the same level alongside the axis perpendicular to the specified plane.

    - fill (bool) – If True, `contourf` is used to plot the field i.e. the bands are filled. Otherwise the coutours are plotted with `contour`.

    - antialiased (bool) – If True, the antialiasing is enabled.

    - comp (int or str) – If the vector field is plotted, this argument must specify the component to plot. It can be either a component number or its name. If you specify norm or abs, the norm of the vector is plotted.

    - axes (Axes) – Matplotlib axes to which the geometry is drawn. If None (the default), new axes are created.

    - figure (Figure) – Matplotlib destination figure. This parameter is ignored if axes are given. In None, the geometry is plotted to the current figure.

    - **kwargs – Keyword arguments passed to `contourf` or `contour`.

plask.plot_vectors(field, plane=None, axes=None, figure=None, angles='xy', scale_units='xy', **kwargs)

  Plot vector field with arrows.

  This function uses `quiver` to plot a vector field returned by some providers with arrows.

  Parameters:

    - field (Data) – The field to plot. As it is usually returned by providers, it already contains the mesh and field values.

    - plane (str) – If the field to plot is a 3D one, this argument must be used to select to which the field is projected. The field mesh must be flat in this plane i.e. all its poinst must lie at the same level alongside the axis perpendicular to the specified plane.

    - axes (Axes) – Matplotlib axes to which the geometry is drawn. If None (the default), new axes are created.

    - figure (Figure) – Matplotlib destination figure. This parameter is ignored if axes are given. In None, the geometry is plotted to the current figure.

    - angles (str) – This is equivalent to the `angles` argument of `quiver`, however, the default value is ‘xy’, which makes more sense for the physical fields.

    - scale_units (str) – `scale_units` argument of `quiver`, with ‘xy’ as the default.

    - **kwargs – Keyword arguments passed to `quiver`.

plask.plot_stream(field, plane=None, axes=None, figure=None, scale=8.0, color='k', **kwargs)

  Plot vector field as a streamlines.

  This function uses `streamplot` to plot a vector field returned by some providers using streamlines.

  Parameters:

    - field (Data) – The field to plot. As it is usually returned by providers, it already contains the mesh and field values.

    - plane (str) – If the field to plot is a 3D one, this argument must be used to select to which the field is projected. The field mesh must be flat in this plane i.e. all its poinst must lie at the same level alongside the axis perpendicular to the specified plane.

    - axes (Axes) – Matplotlib axes to which the geometry is drawn. If None (the default), new axes are created.

    - figure (Figure) – Matplotlib destination figure. This parameter is ignored if axes are given. In None, the geometry is plotted to the current figure.

    - scale (float) – Scale by which the streamlines widths are multiplied.

    - color (str) – Color of the streamlines.

    - **kwargs – Keyword arguments passed to `streamplot`.

plask.plot_geometry(geometry, color=None, lw=1.0, plane=None, zorder=None, mirror=False, periods=True, fill=False, axes=None, figure=None, margin=None, get_color=None, alpha=1.0, extra=None, picker=None, edges=False, edge_alpha=0.25, edge_lw=None)

  Plot specified geometry.

  Parameters:

    - geometry (plask.geometry.Geometry) – Geometry to draw.

    - color (str) – Color of the edges of drawn elements.

    - lw (float) – Width of the edges of drawn elements.

    - plane (str) – Planes to draw. Should be a string with two letters specifying axis names of the drawn plane. This argument is required if 3D geometry is plotted and ignored for 2D geometries.

    - zorder (float) – Ordering index of the geometry plot in the graph. Elements with higher zorder are drawn on top of the ones with the lower one.

    - mirror (bool) – If True then the geometry is mirrored if its specification says so (i.e. some edges are set to mirror or the geometry is a cylindrical one).

    - periods (bool) – If True, all visible periods are plotted in the periodic geometries.

    - fill (bool) – If True, drawn geometry objects will be filled with colors that depends on their material. For Cartesian3D geometry this is not supported and then the fill parameter is ignored.

    - axes (Axes) – Matplotlib axes to which the geometry is drawn. If None (the default), new axes are created.

    - figure (Figure) – Matplotlib destination figure. This parameter is ignored if axes are given. In None, the geometry is plotted to the current figure.

    - margin (float of None) – The margins around the structure (as a fraction of the structure bounding box) to which the plot limits should be set. If None, the axes limits are not adjusted.

    - get_color (callable or dict) – Callable that gets color for material given as its parameter or dictionary from material names (strings) to colors. Material color should be given as a triple (float, float, float) of red, green, blue components, each in range [0, 1]. Any other format accepted by set_facecolor() method of matplotlib Artist should work as well.

    - alpha (float) – Opacity of the drawn geometry (1: fully opaque, 0: fully transparent)

    - extra (None|dict) – If this parameter is not None, a dictionary with optional extra patches for some geometry objects is returned in addition to axes. In such case this parameter value must be a dict with extra patches style (with keys like ‘edgeceolor’, ‘linewidth’, etc., see Matplotlib documentation for details).

    - picker (None|float|boolean|callable) – Matplotlib picker attribute for all artists appended to plot (see matplotlib doc.).

    - edges (bool) – If True, the geometry edges are plotted.

    - edge_alpha (float) – Opacity of edges if they are plotted.

    - edge_lw (None|float) – Linewidth for the edges. If None, it is zero for filled plots and equal to lw for wireframes.

  Returns:

    appended or given axes object

    dict (optional): dictionary mapping geometry objects to extra_patches.

  Return type:

    matplotlib.axes.Axes

  Limitations:

    Intersection is not drawn precisely (item is clipped to bounding box of the envelope).

    Filling is not supported when 3D geometry object or Cartesian3D geometry is drawn.

plask.plot_mesh(mesh, color='0.5', lw=1.0, plane=None, margin=False, axes=None, figure=None, zorder=1.5, alpha=1.0)

  Plot two-dimensional mesh.

  Parameters:

    - mesh (plask.mesh.Mesh) – Mesh to draw.

    - color (str) – Color of the drawn mesh lines.

    - lw (float) – Width of the drawn mesh lines.

    - plane (str) – Planes to draw. Should be a string with two letters specifying axis names of the drawn plane. This argument is required if 3D mesh is plotted and ignored for 2D meshes.

    - margin (float of None) – The margins around the structure (as a fraction of the structure bounding box) to which the plot limits should be set. If None, the axes limits are not adjusted.

    - axes (Axes) – Matplotlib axes to which the geometry is drawn. If None (the default), new axes are created.

    - figure (Figure) – Matplotlib destination figure. This parameter is ignored if axes are given. In None, the geometry is plotted to the current figure.

    - zorder (float) – Ordering index of the meshs plot in the graph. Elements with higher zorder are drawn on top of the ones with the lower one.

    - alpha (float) – Opacity of the drawn mesh (1: fully opaque, 0: fully transparent)

plask.plot_boundary(boundary, mesh, geometry, colors=None, color='0.75', plane=None, axes=None, figure=None, zorder=4, **kwargs)

  Plot boundary conditions.

  This functions is used to visualize boundary conditions. It plots the markers at mesh points, in which boundary conditions are specified. Optionally it can color the points according to the boundary condition value using a specified colormap.

  Parameters:

    - boundary (BoundaryConditions) – Boundary conditions to plot. Normally, this is some attribute of a solver.

    - mesh (plask.mesh.Mesh) – Mesh which points are selected as boundary conditions. Normally it should be the mesh configured for the solver whose boundary conditions are plotted.

    - geometry (plask.geometry.Geometry) – Geometry over, which the boundary conditions are defined. Normally it should be the geometry configured for the solver whose boundary conditions are plotted.

    - colors (str) – Sequence of colors of the boundary conditions points. The length ot this sequence must be equal to the number of distinct boundary conditions. If this is None, all points have the same color.

    - color (str) – Color of the boundary conditions points if `colors` is None.

    - plane (str) – If the field to plot is a 3D one, this argument must be used to select to which the field is projected. The field mesh must be flat in this plane i.e. all its poinst must lie at the same level alongside the axis perpendicular to the specified plane.

    - axes (Axes) – Matplotlib axes to which the geometry is drawn. If None (the default), new axes are created.

    - figure (Figure) – Matplotlib destination figure. This parameter is ignored if axes are given. In None, the geometry is plotted to the current figure.

    - zorder (float) – Ordering index of the geometry plot in the graph. Elements with higher zorder are drawn on top of the ones with the lower one.

    - **kwargs – Keyword arguments passed to `scatter`.

  Example

      >>> solver = electrical.Schockey2D()
      >>> # configure solver
      >>> plot_boundary(solver.voltage_boundary, solver.mesh, solver.geometry,
      ...               cmap='summer')