device_builder.utils.sample_builder_interface

Interface to sample_builder module.

@private

Copyright © 2025 HQS Quantum Simulations GmbH. All Rights Reserved.

def uniform_distribution_to_alloy_sample( uniform_distribution: numpy.ndarray, positions: numpy.ndarray, alloy_distribution: device_builder.models.devices.ProfileDistribution) -> numpy.ndarray:

Convert uniform distribution to discretized sample for random alloy.

FIXME: This is actually a prototypical implementation for a much improved (in terms of speed) device sample generation. ... eventually this should be implemented in a generalized manner ... maybe moved to sample_builder module?

Arguments:
  • uniform_distribution (np.ndarray): Sample of uniform distribution in unit interval.
  • positions (np.ndarray): Positions of the atoms in the random alloy.
  • alloy_distribution (ProfileDistribution): Profile characterizing the random alloy.
Raises:
  • ValueError: If species for profile is not supported.
Returns:

np.ndarray: (Discretized) alloy sample.

def get_device_distribution( positions: numpy.ndarray, alloy_distribution: device_builder.models.devices.ProfileDistribution) -> numpy.ndarray:

Get distribution of a device.

This functions extracts the distribution of the device using the sample_builder module provided by the device_builder.

NOTE: this implicitly assumes that we are looking at a binary alloy, in fact, we only consider Silicon and Germanium...

Arguments:
  • positions (np.ndarray): Positions of the atoms in the random alloy.
  • alloy_distribution (ProfileDistribution): Profile characterizing the random alloy.
Returns:

np.ndarray: Array of probabilities for atoms (shape: (n_atoms, n_species).

def get_uniform_distribution_sample( device: device_builder.models.devices.RandomAlloyConfiguration, unit_cell_index: tuple[int, int, int]) -> numpy.ndarray:

Get uniformly distributed random sample.

Arguments:
  • device (RandomAlloyConfiguration): Configuration of the random alloy device.
  • unit_cell_index (tuple[int, int, int]): Shift in terms of unit cells for the simulation region.
Raises:
  • RuntimeError: If uniformly distributed sample could not be generated (indicates bug!).
Returns:

np.ndarray: Unifromly distributed random sample.

def get_start_stop_indices( index: int, unit_cell_index: int, simulation_size: int) -> tuple[tuple[int, int], tuple[int, int]]:

Get mapping indices from independent random samples to simulation region.

In order to account encode a spatial relation between statistically independent random samples, which allows to continuously transition between independent samples, we need to map parts of the simulation region. This functions helps to construct these mappings.

Arguments:
  • index (int): Index labelling the statistically independent random samples.
  • unit_cell_index (int): Shift (in unit cells) of the simulation region.
  • simulation_size (int): Size if the simulation region (in unit cells).
Returns:

tuple[tuple[int, int], tuple[int, int]]: Tuple of tuple[int, int]: Start and stop indices for the independent random sample (source). tuple[int, int]: Start and stop indices for the simulation sample (target).

def get_sample_indices_from_unit_cell_indices( unit_cell_index: tuple[int, ...], simulation_size: tuple[int, ...]) -> tuple[tuple[int, int], ...]:

Get simulation size index range for sample generation.

Arguments:
  • unit_cell_index (tuple[int, ...]): Shifts (in unit cells) of the simulation region.
  • simulation_size (tuple[int, ...]): Size of the simulation region (in unit cells).
Returns:

tuple[tuple[int, int], ...]: Index ranges.

def get_sample_index_from_unit_cell_index(unit_cell_index: int, simulation_size: int) -> tuple[int, int]:

Get simulation size index range for single dimension.

Arguments:
  • unit_cell_index (int): Shift (in unit cells) of the simulation region.
  • simulation_size (int): Size of the simulation region (in unit cells).
Returns:

tuple[int, int]: Index range for single dimension.