Beampy modules — beampy 0.0.1.4 documentation

# Beampy modules

List of all the modules used in Beampy as of Jan 26, 2020 for the version 0.0.1.4

Source codes

## beampy.bpm

beampy.bpm code.

The bpm module contain the Bpm class used to simulate the light propagation - within low refractive index variation and small angle (paraxial approximation) - using the Beam Propagation Method.

This module was done by Jonathan Peltier during a master university course from the PAIP master of the université de Lorraine, under the directive of Pr. Nicolas Fressengeas.

The bpm codes are mainly based on a compilation of MatLab codes initialy developed by Régis Grasser during his PhD thesis[2], and later modified at the FEMTO-ST institute of the Université de Franche-Comté and at the LMOPS laboratory [3] of the Université de Lorraine.

[1] K. Okamoto, in Fundamentals of Optical Waveguides, 2nd ed., edited by K. Okamoto (Academic, Burlington, 2006), pp. 329–397.

[2] “Generation et propagation de reseaux periodiques de solitons spatiaux dans un milieu de kerr massif” PhD thesis, université de Franche-Comté 1998.

[3] H. Oukraou et. al., Broadband photonic transport between waveguides by adiabatic elimination Phys. Rev. A, 97 023811 (2018).

class `beampy.bpm.` `Bpm`(width, no, delta_no, length_z, dist_z, nbr_z_disp, length_x, dist_x)

  Bases: `object`

  The Bpm class is used to simulate light propagation - within small refractive index variation guides and small angle of propagation (paraxial) - using the Beam Propagation Method.

  Parameters

    - width (float) – Guide width defined as the diameter (µm) at 1/e^2 intensity.

    - no (float) – Refractive index of the cladding.

    - delta_no (float) – Difference of refractive index between the core and the cladding.

    - length_z (float) – Size of the compute window over z (µm).

    - dist_z (float) – Step over z (µm)

    - nbr_z_disp (int) – Number of points to display over z.

    - length_x (float) – Size of the compute window over x (µm).

    - dist_x (float) – Step over x (µm)

  `absorption`(alpha, lost_beg, lost_end)

    Absorption into a guide or several guides.

    \(e^{-\alpha * dz}\)

    Parameters

      - alpha (float) – Absorption per µm.

      - lost_beg (array-like) – Left indices position of the selected guides over z.

      - lost_end (array-like) – Right indices position of the selected guides over z.

    Returns

      field – Amplitude values over x in µm after looses.

    Return type

      array

    Notes

    This methods uses the following variables defined in `Bpm`: nbr_lost, i, field, dist_z, nbr_x.

  `airy_light`(lobe_size, airy_zero, offset_light=0)

    Create an Airy beam using scipy.special.airy(x).

    Parameters

      - lobe_size (float) – Size of the first lobe (µm).

      - airy_zero (int) – Cut the beam at the asked zero of the Airy function. n lobes will be displayed.

      - offset_light (float, optional) – Light offset from center in µm. 0 by default.

    Returns

      - field (array) – Amplitude values over x (µm).

      - airy_zero (int) – Number of lobes. Corrected if higher than the window size.

    Notes

    This methods uses the following variables defined in `Bpm`: nbr_x, length_x, dist_x, x.

  `all_modes`(lo, offset_light=0)

    Compute all modes allowed by the guide and sum them into one field.

    Parameters

      - lo (float) – Wavelength of the beam in vaccum in µm.

      - offset_light (float, optional) – Light offset from center in µm. 0 by default.

    Returns

      - field (array) – Sum of all possibles fields in the guide.

      - h (array, float) – Transverse propagation constant over x in µm of all modes.

      - gamma (array, float) – Extinction coefficient over z in µm of all modes.

      - beta (array, float) – Longitudinal constant of propagation over z in µm of all modes.

    Notes

    This methods uses the following variables defined in `Bpm`: nbr_x and the :meth`mode_light` method.

  `bpm_compute`(chi3=1e-19, kerr=False, kerr_loop=1, variance_check=False, alpha=0, lost_beg=None, lost_end=None)

    Compute BPM principle : free_propag over dz/2, index modulation, free_propag over dz/2.

    Parameters

      - chi3 (float, optional) – Value of the effective third term of the electric susceptibility tensor. Equals to \(10^{-19} m^2/V^2\) by default.

      - kerr (bool, optional) – Activate the kerr effect. False by default.

      - kerr_loop (int, optional) – Number of corrective loops for the Kerr effect. 1 by default.

      - variance_check (bool) – Check if the kerr effect converge fast enought. False by default.

      - alpha (float, optional) – Absorption per µm. 0 by default.

      - lost_beg (array-like, optional) – Left indices position of the selected guides over z. None by default.

      - lost_end (array-like, optional) – Right indices position of the selected guides over z. None by default.

    Returns

      current_power – Power after the propagation over dz.

    Return type

      array

    Notes

    This method uses the `Bpm` class variables: nbr_lost, i, field, dist_z, dn, nl_mat, phase_mat, epnc.

    This method change the values of: field, dn, nl_mat, current_power.

  `check_modes`(lo)

    Return the last possible mode number. Could be merged with `all_modes()` but would increase the needed time to compute just to display a number.

    Parameters

      lo (float) – Wavelength of the beam in vaccum (µm).

    Returns

      m – Number of the last possible mode for a squared guide.

    Return type

      int

    Notes

    This methods uses the :meth`mode_light` method defined in `Bpm`.

  `create_curved_guides`(shape, curve, half_delay, distance_factor, offset_guide=0)

    Create two curved guides and one linear guide on the center (STIRAP).

    The central positions over x and z are defined as follow:

    Left guide: \(x_0-p_{min}-curve(z-length\_z/2-half\_delay)^2\)

    Right guide: \(x_0+p_{min}+curve(z-length\_z/2+half\_delay)^2\)

    Central guide: \(x_0\)

    Parameters

      - shape (method) – `square()` or `gauss()`

      - curve (float) – curvature factor in \(10^{-8} µm^{-2}\).

      - half_delay (float) – Half distance over z in µm bewteen the two external guides where they are the closest. In other words, the distance from the center and the minimum of one of the curved guides over z.

      - distance_factor (float) – Factor between the guide width and the minimal distance between the two guides =p_min/width. If distance_factor=1, the curved guides will touch the central guide (p_min=width).

      - offset_guide (float, optional) – Guide offset from the center (µm). 0 by default.

    Returns

      - peaks (array) – Central position of each guide as peaks[guide,z].

      - dn (array) – Difference of reefractive index as dn[z,x].

    Notes

    This methods uses the following variables defined in `Bpm`: length_z, nbr_z, width, nbr_x, x, dist_x, delta_no.

  `create_guides`(shape, nbr_p, p, offset_guide=0)

    Create an array of guides over x using peaks positions and for a given shape.

    Parameters

      - shape (method) – `squared_guide()`, `gauss_guide()` or any lambda function that takes one argument and return the relative refractive index for the input position.

      - nbr_p (int) – Number of guides.

      - p (float) – Distance between two guides center (µm).

      - offset_guide (float, optional) – Guide offset from the center (µm). 0 by default.

    Returns

      - peaks (array-like) – Central position of each guide [guide,z].

      - dn (array-like) – Difference of reefractive index [z,x].

    Notes

    This methods uses the following variables defined in `Bpm`: nbr_z, nbr_x, x, dist_x, delta_no.

  `create_x_z`()

    Create the x, z array and ajust the resolution variables.

    Returns

      - length_z (float) – Corrected value due to nbr_z being an int.

      - nbr_z (int) – Number of points computed over z.

      - nbr_z_disp (int) – Corrected value due to pas being an int.

      - length_x (float) – Corrected value due to nbr_x being an int.

      - nbr_x (int) – Number of point over x (µm).

      - x (array) – x values between [-length_x/2, length_x/2-dist_x] center on 0.

    Notes

    This method creates the following variables within the class `Bpm`:

    - pas : Interval of computed points between each displayed points.

  `gauss_guide`(gauss_pow)

    A lambda function than return a centered super-Gaussian shape.

    \(e^{-(x/w)^{2P}}\)

    The waist is defined as width/2 and correspond to the 1/e relative value.

    See `example_guides_x()` for more details.

    Parameters

      gauss_pow (int) – Index of the super-gaussian guide with 1 being a regural gaussian guide and 4 being the conventionnal super-gaussian guide used to describe realistic guides. See on en.wikipedia.org/wiki/Gaussian_function #Higher-order_Gaussian_or_super-Gaussian_function

    Notes

    This methods uses the width variable defined in `Bpm`.

  `gauss_light`(fwhm, offset_light=0)

    Create a gaussien beam in amplitude.

    \(E = e^{-((x-x_0)/w)^{2P}}\)

    The waist is defined as fwhm/sqrt(2*log(2)) and correspond to the 1/e field value and 1/\(e^2\) intensity value.

    Parameters

      - fwhm (float) – Full width at half maximum (for intensity not amplitude) (µm).

      - offset_light (float, optional) – Light offset from center in µm. 0 by default.

    Returns

      field – Amplitude values over x in µm.

    Return type

      array

    Notes

    This methods uses the x and dist_x variables defined in `Bpm`.

  `guide_position`(guide, size)

    Return the left and right position index over x of a given guide for each z.

    Parameters

      - guide (int) – Number of the guide.

      - size (float) – Width (µm).

    Returns

      - x_beg (array) – Left indices position of the selected guide over z.

      - x_end (array) – Right indices position of the selected guide over z.

    Notes

    This methods uses the following variables defined in `Bpm`: nbr_z, peaks, x, length_x.

  `init_field`(field, theta_ext, irrad, lo)

    Initialize phase, field and power variables.

    Parameters

      - field (array, array-like) – Amplitude values for each beams over x (µm) [beam,E] or E

      - theta_ext (float) – Exterior inclinaison angle (°).

      - irrad (array, array-like) – Irradiance or power for each beam (\(W/m^2\)).

      - lo (float) – Wavelenght (µm).

    Returns

      progress_pow – Intensity values over x (µm).

    Return type

      array

    Notes

    This method creates the following variables within the class `Bpm`:

    - epnc: Convertion factor used to set unit of the field and irradiance.

    - nl_mat: Refractive index modulation.

    - phase_mat: Free propagation in Fourier space over dz/2.

    - current_power: Intensity for z=0.

    - field: Field value with the unit.

    - ko: the free space vector (1/µm).

    - lo: Wavelenght (µm).

    This methods uses the following variables defined in `Bpm`: no, x, dist_x, nbr_x, nbr_z_disp.

  `kerr_effect`(chi3=1e-19, kerr_loop=1, variance_check=False, field_start=None, dn_start=None, phase_mat=None)

    Kerr effect: refractive index modulation by the light intensity. See: https://optiwave.com/optibpm-manuals/bpm-non-linear-bpm-algorithm/

    Parameters

      - chi3 (float, optional) – Value of the third term of the electric susceptibility tensor. Equals to \(10^{-19} m^2/V^2\) by default.

      - kerr_loop (int, optional) – Number of corrective loops for the Kerr effect. 1 by default.

      - variance_check (bool, optional) – Check if the kerr effect converge fast enought. False by default.

      - field_start (array, optional) – Field without kerr effect. If None were given, take the `main_compute()` field.

      - dn_start (array, optional) – Refractive index without kerr effect. If None were given, take the `main_compute()` dn.

      - phase_mat (array, optional) – Free propagation in Fourier space over dz/2. If None were given, take the `main_compute()` phase_mat.

    Returns

      - dn (array) – Refractive index with kerr effect.

      - nl_mat (array) – refractive index modulation with kerr effect.

      - field_x (array) – Field with the kerr effect at the self.i step.

      - cur_pow (array) – Beam power with the kerr effect after the dz propagation.

    Notes

    This methods uses the following variables defined in `Bpm`: i, epnc, no, ko, dist_z and the `variance()` method.

  `losses_position`(guide_lost, width_lost)

    Return the left and right position (x) index of a given area over z [x,z].

    Parameters

      - guide_lost (array) – Number of each guide where looses occurs.

      - width_lost (array) – Half width in µm for each guide.

    Returns

      - lost_beg (array-like) – Left indices position of the selected guides over z.

      - lost_end (array-like) – Right indices position of the selected guides over z.

    Notes

    This methods uses the nbr_z variables defined in `Bpm` and the `guide_position()` method. It also creates the nbr_lost variable shared with `Bpm`.

  `main_compute`(chi3=1e-19, kerr=False, kerr_loop=1, variance_check=False, alpha=0, lost_beg=None, lost_end=None)

    main method used to compute propagation.

    Parameters

      - chi3 (float, optional) – Value of the third term of the electric susceptibility tensor. Equals to \(10^{-19} m^2/V^2\) by default.

      - kerr (bool, optional) – Activate the kerr effect. False by default.

      - kerr_loop (int, optional) – Number of corrective loop for the Kerr effect. 1 by default.

      - variance_check (bool, optional) – Check if the kerr effect converge fast enought. False by default.

      - alpha (float, optional) – Absorption per µm. 0 by default

      - lost_beg (array-like, optional) – Left indices position of the selecteds guide over z. None by default.

      - lost_end (array-like, optional) – Right indices position of the selecteds guide over z. None by default.

    Returns

      progress_pow – Intensity values (\(W/m^2\)) over x (µm) and z (µm).

    Return type

      array

    Notes

    This methood uses the `Bpm` class variables: phase_mat, field, i, nbr_z, pas, current_power, dist_z, length_z, nbr_lost, dn, nl_mat, epnc and uses the `bpm_compute()`, `kerr_effect()`.

    This method change the values of the `Bpm` class variables: field and if kerr, dn and nl_mat.

  `mode_determ`(mode)

    Solve the transcendental equation tan=sqrt that give the modes allowed in a squared guide.

    Parameters

      mode (int) – Number of the searched mode.

    Returns

      - h_m (float) – Transverse propagation constant over x (µm).

      - gamma_m (float) – Extinction coefficient over x (µm).

      - beta_m (float) – Longitudinal constant of propagation over z (µm).

    Raises

      ValueError – if no mode exists.

    Notes

    This methods uses the following variables defined in `Bpm`: lo, width, no, delta_no, ko.

  `mode_light`(mode, lo, offset_light=0)

    Create light based on propagated mode inside a squared guide.

    Parameters

      - mode (int) – Number of the searched mode.

      - lo (float) – Wavelength of the beam in vaccum (µm).

      - offset_light (float, optional) – Light offset from center (µm). 0 by default.

    Returns

      - field (array) – Amplitude values over x (µm).

      - h_m (float) – Transverse propagation constant over x (µm).

      - gamma_m (float) – Extinction coefficient over x (µm).

      - beta_m (float) – Longitudinal constant of propagation over z (µm).

    Notes

    This methods uses the following variables defined in `Bpm`: nbr_x, width, x and the :meth`mode_determ` method.

    This method create the following variables in `Bpm`: lo, ko.

  `power_guide`(x_beg, x_end)

    return the approximative power over z in a given guide. A better method would be to deconvolve the beams.

    Parameters

      - x_beg (array) – Left indices position over z for a selected guide.

      - x_end (array) – Right indices position over z for a selected guide.

    Returns

      P – Power in the guide over z.

    Return type

      array

    Notes

    This methods uses the following variables defined in `Bpm`: nbr_z_disp, progress_pow.

  `squared_guide`()

    A lambda function than returns a centered rectangular shape.

    return 1 if \(x >= -width/2\) and \(x <= width/2\) else return 0.

    Notes

    This methods uses the width variable defined in `Bpm`.

  `squared_light`(fwhm, offset_light=0)

    Create a flat-top beam (squared).

    Parameters

      - fwhm (float) – Width in µm.

      - offset_light (float, optional) – Light offset from center in µm. 0 by default.

    Returns

      field – Amplitude values over x in µm.

    Return type

      array

    Notes

    This methods uses the following variables defined in `Bpm`: nbr_x, x.

  `variance`(initial, final)

    This method alerts the user when the kerr effect don’t converge fast enought. Raise a ValueError when the power standard deviation exceed \(10^{-7}\).

    Parameters

      - initial (array) – Power of the kerr effect looped n-1 time.

      - final (array) – Power of the kerr effect looped n time.

    Raises

      ValueError – when the power standard deviation exceed \(10^{-7}\).

`beampy.bpm.` `example_bpm`()

  Version allowing to compute BPM without the user interface. Used for quick test.

## beampy.interface

beampy.interface code.

class `beampy.interface.` `Ui_MainWindow`

  Bases: `object`

  `retranslateUi`(MainWindow)
  `setupUi`(MainWindow)

## beampy.user_interface

beampy.user_interface code.

The user_interface module is the main file of the beampy module. It contain the UserInterface class used to computed and displayed the bpm results onto the interface.

This module was at first developed by Marcel Soubkovsky for the implementation of the array of guides, of one gaussian beam and of the plotting methods. Then, continued by Jonathan Peltier.

class `beampy.user_interface.` `UserInterface`

  Bases: `PyQt5.QtWidgets.QMainWindow`, `beampy.interface.Ui_MainWindow`

  This class connect the `Bpm` class from the `bpm` module with the `setupUi()` method from the `interface` module.

  `addmpl`(tab='guide', pow_index=0)

    Add the selected plots on the guide, light or compute window.

    Parameters

      - tab (str, optional) – ‘guide’ or ‘light’. ‘guide’ by default.

      - pow_index (int, optional) – Add the first guide and light step if 0 or the last step if -1. Also display the propagation into (x,z) and guide power if -1 is choosen. 0 by default.

  `calculate_guide`(topology='array')

    Initialized the `Bpm` class and creates the guides.

    Parameters

      topology (str) – ‘array’ or ‘curved’.

    Notes

    Creats many variables, including :

    - peaks : Central position of each guide [guide,z].

    - dn : Difference of reefractive index [z,x].

    This method calls the following methods from `Bpm`:

    `create_x_z()`, `squared_guide()`, `gauss_guide()`, `create_guides()`, `create_curved_guides()`.

  `calculate_light`()

    Create the choosen beams.

    Notes

    Creates the progress_pow variable.

    This method calls the following methods from the `Bpm` class:

    `gauss_light()`, `squared_light()`, `all_modes()`, `mode_light()`, `airy_light()`, `init_field()`.

  `calculate_propagation`()

    Calculate the propagation based on the input light and guides shapes.

    Notes

    Creates the progress_pow variable.

    Calls the following methods from `Bpm`: `losses_position()`, meth`.main_compute`.

  `check_modes_display`()

    Display on the interface the last mode that can propagated into a squared guide.

  `connect_buttons`()

    Connect the interface buttons to their corresponding functions:

    `on_click_array()`, `on_click_curved()`, `on_click_light()`, `on_click_compute()`, `on_click_create_light()`, `on_click_delete_light()`, `save_light()`, `get_guide()`, `get_light()`, `get_compute()`, `show_estimate_time()`, `check_modes_display()`.

  `create_menu`()

    Create a menu to open, save a file, or exit the app.

    Notes

    This method connect the following methods and function to the menu buttons:

    `open_file_name()`, `save_quick()`, `save_file_name()`, `open_doc()`.

  `get_compute`()

    Set the saved values of the compute variables on the interface.

  `get_guide`()

    Set the saved values of the guide variables on the interface.

  `get_light`()

    Set the saved values of the light variables on the interface.

  `on_click_array`()

    Compute and displayed a guide array.

  `on_click_compute`()

    Compute the propagation using the guide and light informations.

  `on_click_create_light`()

    Create a new beam with the displayed variables.

  `on_click_curved`()

    Compute and displayed curved guides.

  `on_click_delete_light`()

    Delete the current displayed beam and displayed the next one.

  `on_click_light`()

    Compute the light and display it with guides.

  `open_file`(filename)

    Set guides, beams and computes variables from a choosen file.

    Parameters

      filename (str) – Name of the file.

  `open_file_name`()

    Open a dialog window to select the file to open, and call `open_file()` to open the file.

    Source: https://pythonspot.com/pyqt5-file-dialog/

    Notes

    This method has a try/except implemented to check if the openned file contains all the variables.

  `rmmpl`(tab, pow_index=0)

    Remove the selected plots

    Parameters

      - tab (str) – ‘guide’ or ‘light’.

      - pow_index (int, optional) – Remove the first light step if 0 or the last step if -1. 0 by default.

  `save_compute`()

    Save the interface variables into the compute variables.

  `save_file`(filename)

    Save guides, beams and computes variables into a choosen file.

    Parameters

      filename (str) – Name of the file.

  `save_file_name`()

    Open a dialog window to select the saved file name and call `save_file()` to save the file.

  `save_guide`()

    Save the interface variables into the guides variables.

  `save_light`(beam_selec=False)

    Save the interface variables into the lights variables.

    Parameters

      beam_selec (int, bool, optional) – Number of the beam to save into the variables. False by default to get the currently displayed beam.

  `save_quick`()

    Check if a file is already selected and if so, save into it. Else, call the `save_file_name()` to ask a filename.

  `show_estimate_time`()

    Display - on the interface - the estimate time needed to compute the propagation, based on linearized experimental values. The estimation takes into account the looses, Kerr, and control parameters.

`beampy.user_interface.` `open_app`()

  Function used to open the app. Can be called directly from beampy.

`beampy.user_interface.` `open_doc`()

  Function that open the local html documentation - describing the beampy modules - if exist, or the online version otherwise.