Merge branch 'b-field-units' into 'v3.1-stable'

###################################

# Set the clang-format version required by the CI for correct formatting:

SET(CLANG_FORMAT_VERSION "12")

SET(CLANG_FORMAT_VERSION "16")

# Set the clang-tidy version of the linter required by the CI:

SET(CLANG_TIDY_VERSION "12")

SET(CLANG_TIDY_VERSION "16")

# Set the source files to clang-format (FIXME: determine this better)

FILE(

    // Enable multithreading of this module if multithreading is enabled

    allow_multithreading();

    // Set default units for interpreting input field files in:

    config_.setDefault("file_units", "V/cm");

    // NOTE use voltage as a synonym for bias voltage

    config_.setAlias("bias_voltage", "voltage");

    // NOTE use field_depth as a synonym for depletion_depth

        LOG(TRACE) << "Fetching electric field from mesh file";

        // Get field from file

        auto field_data = field_parser_.getByFileName(config_.getPath("file_name", true), "V/cm");

        auto field_data =

            field_parser_.getByFileName(config_.getPath("file_name", true), config_.get<std::string>("file_units"));

        // Warn at field values larger than 1MV/cm / 10 MV/mm. Simple lookup per vector component, not total field magnitude

        auto max_field = *std::max_element(std::begin(*field_data.getData()), std::end(*field_data.getData()));

  available in the source code of this module, a converter tool for electric fields from adaptive TCAD meshes is provided

  with the framework. Fields of different sizes can be used and mapped onto the pixel matrix using the `field_scale`

  parameter. By default, the module reads the size of the field from the file. If the field size and pixel pitch do not match,

  a warning is printed.

  a warning is printed. The units in which the field itself is interpreted can be configured via the `file_units` parameter,

  by default the field values are interpreted as representing `V/cm`. This is also the unit used in the output files from the `mesh converter` tool.

- The **custom** field model allows to specify arbitrary analytic field functions for a single or all three vector components

  of the electric field. For this, the `field_functions` parameter configured with either one formula which is then used for

The `depletion_depth` parameter can be used to control the thickness of the depleted region inside the sensor.

This can be useful for devices such as HV-CMOS sensors, where the typical depletion depth but not necessarily the full

depletion voltage are know. It should be noted that `depletion_voltage` and `depletion_depth` are mutually exclusive

parameters and only one at a time can be specified. The alias `field_depth` can be used instead, as this parameter is the depth that the field will be created over. If the parameter is smaller than the field from an imported mesh, the field will be compressed in the z-direction.

parameters and only one at a time can be specified. The alias `field_depth` can be used instead, as this parameter is the

depth that the field will be created over. If the parameter is smaller than the field from an imported mesh, the field will

be compressed in the z-direction.

Furthermore the module can plot the electric field profile on an projection axis normal to the x,y or z-axis at a particular

plane in the sensor. Additional plots comprise the individual field vector components as well as the field magnitude and can

## Parameters

- `model` : Type of the electric field model, either **linear**, **constant**, **parabolic**, **custom** or **mesh**.

- `depletion_depth` : Thickness of the depleted region. Used for all electric fields. When using the depletion depth for the

  **linear** model, no depletion voltage can be specified. Defaults to the full sensor thickness. The alias `field_depth` can be used for improved readability when using the model **mesh** (as the depletion depth in an externally generated field may be smaller than the field depth).

  **linear** model, no depletion voltage can be specified. Defaults to the full sensor thickness. The alias `field_depth` can

  be used for improved readability when using the model **mesh** (as the depletion depth in an externally generated field may

  be smaller than the field depth).

### Parameters for models `linear` and `constant`

- `bias_voltage` : Voltage over the whole sensor thickness. Used to calculate the electric field for the models **constant**

### Parameters for model `mesh`

- `file_name` : Location of file containing the meshed electric field data.

- `file_units` : Field units in which the file content is to be interpreted in, this defaults to `V/cm`.

- `field_mapping`: Description of the mapping of the field onto the sensor or pixel cell. Possible values are `SENSOR` for

  sensor-wide mapping, `PIXEL_FULL`, indicating that the map spans the full 2D plane and the field is centered around the

  pixel center, `PIXEL_HALF_TOP` or `PIXEL_HALF_BOTTOM` indicating that the field only contains only one half-axis along `y`,

  of the 2D pixel plane. In addition, the `PIXEL_FULL_INVERSE` mode allows loading full-plane field maps which are not

  centered around a pixel cell but the corner between pixels.

- `field_scale`:  Scaling factor of the electric field in x- and y-direction. By default, the scaling factors are set to

  `{1, 1}` and the field is used with its physical extent stated in the field data file. To scale the field in the z-direction, the parameter `field_depth` can be used.

  `{1, 1}` and the field is used with its physical extent stated in the field data file. To scale the field in the

  z-direction, the parameter `field_depth` can be used.

- `field_offset`: Offset of the field in x- and y-direction. With this parameter and the mapping mode `SENSOR`, the field can

  be shifted e.g. by half a pixel pitch to accommodate for fields which have been simulated starting from the pixel center.

  The shift is applied in positive direction of the respective coordinate.