simcats 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

simcats/__init__.py

@@ -6,4 +6,4 @@ from ._simulation import Simulation
 from ._default_configs import default_configs
 
 __all__ = ["Simulation", "default_configs"]
-__version__ = "1.1.0"
+__version__ = "1.2.0"

simcats/support_functions/__init__.py

@@ -3,7 +3,7 @@ SimCATS subpackage with support functions that are not assigned to any specific
 """
 
 from simcats.support_functions._parameter_sampling import ParameterSamplingInterface, NormalSamplingRange, \
-    LogNormalSamplingRange, UniformSamplingRange
+    LogNormalSamplingRange, UniformSamplingRange, ExponentialSamplingRange
 from simcats.support_functions._fermi_filter1d import fermi_filter1d, fermi_dirac_derivative
 from simcats.support_functions._cumulative_distribution_functions import cauchy_cdf, multi_cauchy_cdf, sigmoid_cdf, \
     multi_sigmoid_cdf
@@ -12,5 +12,5 @@ from simcats.support_functions._rotate_points import rotate_points
 from simcats.support_functions._plotting import plot_csd
 
 __all__ = ["ParameterSamplingInterface", "NormalSamplingRange", "LogNormalSamplingRange", "UniformSamplingRange",
-           "fermi_filter1d", "fermi_dirac_derivative", "cauchy_cdf", "multi_cauchy_cdf", "sigmoid_cdf",
-           "multi_sigmoid_cdf", "signed_dist_points_line", "rotate_points", "plot_csd"]
+           "ExponentialSamplingRange", "fermi_filter1d", "fermi_dirac_derivative", "cauchy_cdf", "multi_cauchy_cdf",
+           "sigmoid_cdf", "multi_sigmoid_cdf", "signed_dist_points_line", "rotate_points", "plot_csd"]

simcats/support_functions/_parameter_sampling.py

@@ -47,6 +47,7 @@ class NormalSamplingRange(ParameterSamplingInterface):
         self,
         total_range: Tuple,
         std: float,
+        mean: Union[float, None] = None,
         sampling_range: Union[float, None] = None,
         rng: Union[np.random.Generator, None] = None,
     ) -> None:
@@ -60,6 +61,8 @@ class NormalSamplingRange(ParameterSamplingInterface):
                 range, a new sample is drawn until a sample inside the sampling_range/total_range was generated,
                 leading to a truncated normal distribution.
             std (float): The standard deviation of the sampled elements, which is used in the normal distribution.
+            mean (Union[float, None]): The mean to be used for the normal distribution. If None, the center of the
+                total range will be used. Defaults to None.
             sampling_range (Union[float, None]): The maximum range in which the parameter is allowed to change during
                 the simulation. The explicit range is set up during the initialization, narrowing down the
                 supplied total_range. Default is None, which leads to no narrowing of the given total_range.
@@ -86,13 +89,17 @@ class NormalSamplingRange(ParameterSamplingInterface):
                 )
                 self.__range = (sampled - 0.5 * sampling_range, sampled + 0.5 * sampling_range)
         self.__std = std
+        if mean is not None:
+            self.__mean = mean
+        else:
+            self.__mean = np.mean(self.__range)
         self.__last_sample = None
 
     def sample_parameter(self):
-        sampled = self.__rng.normal(loc=np.mean(self.__range), scale=self.__std)
+        sampled = self.__rng.normal(loc=self.__mean, scale=self.__std)
         # repeat sampling until the sampled value is in self.__range
         while sampled < self.__range[0] or sampled > self.__range[1]:
-            sampled = self.__rng.normal(loc=np.mean(self.__range), scale=self.__std)
+            sampled = self.__rng.normal(loc=self.__mean, scale=self.__std)
         self.__last_sample = sampled
         return sampled
 
@@ -102,7 +109,7 @@ class NormalSamplingRange(ParameterSamplingInterface):
     def __repr__(self) -> str:
         return (
             self.__class__.__name__
-            + f"(last_sample={self.last_sample()}, range={self.__range}, std={self.__std}, rng={self.__rng})"
+            + f"(last_sample={self.last_sample()}, range={self.__range}, mean={self.__mean}, std={self.__std}, rng={self.__rng})"
         )
 
 
@@ -231,3 +238,87 @@ class LogNormalSamplingRange(ParameterSamplingInterface):
             + f"(last_sample={self.last_sample()}, range={self.__range}, mean={self.__mean}, sigma={self.__sigma}"
             + f", rng={self.__rng})"
         )
+
+
+class ExponentialSamplingRange(ParameterSamplingInterface):
+    """Exponential distribution sampling range implementation of ParameterSamplingInterface."""
+
+    def __init__(
+            self,
+            total_range: Tuple,
+            scale: float,
+            sampling_range: Union[float, None] = None,
+            rng: Union[np.random.Generator, None] = None,
+    ) -> None:
+        """This class can be used to generate randomly sampled parameters from an exponential distribution within a given range.
+
+        The samples are calculated as follows:\n
+        min(sampling_range) + exponential_distribution_sample * (max(sampling_range) - min(Sampling_range))
+
+        To select the correct scale factor (1 / λ), take the following into consideration:\n
+        To have the p percent quantile at position q, the following must be valid:\n
+        q = ln( 1 / (1-p) ) / λ \n
+        with 1 / λ = scale \n
+        So in general the scale is calculated as: \n
+        scale = q / ln( 1 / (1-p) ) \n
+        For example: If it is desired to have 90% of the values in 50% of the sampling range, we get:\n
+        scale = 0.5 / ln( 1 / (1-0.9) ) = 0.21715
+
+        Further reading: https://en.wikipedia.org/wiki/Exponential_distribution#properties
+
+        Used for example for the distortions during the simulation of CSDs.
+
+        Args:
+            total_range (Tuple): The total range in which the parameters can be sampled. This can be narrowed down
+                randomly with the help of the parameter sampling_range. If the exponential distribution generates a
+                sample outside this range, a new sample is drawn until a sample inside the sampling_range/total_range
+                was generated, leading to a truncated exponential distribution.
+            scale (float): The scale of the exponential distribution. See __init__ docstring for more detailed
+                information.
+            sampling_range (Union[float, None]): The maximum range in which the parameter is allowed to change during
+                the simulation. The explicit range is set up during the initialization, narrowing down the
+                supplied total_range. Default is None, which leads to no narrowing of the given total_range.
+            rng (np.random.Generator): random number generator used for the sampling of random numbers. If None, the
+                default generator of numpy (np.random.default_rng()) is used. Default is None.
+        """
+        if rng:
+            self.__rng = rng
+        else:
+            self.__rng = np.random.default_rng()
+        if sampling_range is None:
+            self.__range = total_range
+        else:
+            if np.greater_equal(sampling_range, np.max(total_range) - np.min(total_range)):
+                warnings.warn(
+                    "The given reduced sampling range is equal or larger than the given total range. As "
+                    "default the given total sampling range is taken.",
+                    stacklevel=2,
+                )
+                self.__range = total_range
+            else:
+                sampled = self.__rng.uniform(
+                    np.min(total_range) + 0.5 * sampling_range, np.max(total_range) - 0.5 * sampling_range
+                )
+                if total_range[0] < total_range[1]:
+                    self.__range = (sampled - 0.5 * sampling_range, sampled + 0.5 * sampling_range)
+                else:
+                    self.__range = (sampled + 0.5 * sampling_range, sampled - 0.5 * sampling_range)
+        self.__scale = scale
+        self.__last_sample = None
+
+    def sample_parameter(self):
+        sampled = self.__range[0] + self.__rng.exponential(scale=self.__scale) * (self.__range[1] - self.__range[0])
+        # repeat sampling until the sampled value is in self.__range
+        while sampled < np.min(self.__range) or sampled > np.max(self.__range):
+            sampled = self.__range[0] + self.__rng.exponential(scale=self.__scale) * (self.__range[1] - self.__range[0])
+        self.__last_sample = sampled
+        return sampled
+
+    def last_sample(self):
+        return self.__last_sample
+
+    def __repr__(self) -> str:
+        return (
+                self.__class__.__name__
+                + f"(last_sample={self.last_sample()}, range={self.__range}, scale={self.__scale}, rng={self.__rng})"
+        )

{simcats-1.1.0.dist-info → simcats-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: simcats
-Version: 1.1.0
+Version: 1.2.0
 Summary: SimCATS is a python framework for simulating charge stability diagrams (CSDs) typically measured during the tuning process of qubits.
 Author-email: Fabian Hader <f.hader@fz-juelich.de>, Sarah Fleitmann <s.fleitmann@fz-juelich.de>, Fabian Fuchs <f.fuchs@fz-juelich.de>
 License: CC BY-NC-SA 4.0
@@ -31,6 +31,26 @@ Requires-Dist: opencv-python
 Requires-Dist: scipy
 Requires-Dist: sympy
 
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/f-hader/SimCATS/main/SimCATS_symbol.svg" alt="SimCATS logo">
+  <br>
+</h1>
+
+<div align="center">
+  <a href="https://github.com/f-hader/SimCATS/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg" alt="License: CC BY-NC-SA 4.0"/>
+  </a>
+  <a href="https://pypi.org/project/simcats/">
+    <img src="https://img.shields.io/pypi/v/simcats.svg" alt="PyPi Latest Release"/>
+  </a>
+  <a href="https://simcats.readthedocs.io/en/latest/">
+    <img src="https://img.shields.io/readthedocs/simcats" alt="Read the Docs"/>
+  </a>
+  <a href="https://doi.org/10.1109/TQE.2024.3445967">
+    <img src="https://img.shields.io/badge/DOI-10.1109/TQE.2024.3445967-007ec6.svg" alt="DOI Publication"/>
+  </a>
+</div>
+
 # SimCATS
 
 Simulation of CSDs for Automated Tuning Solutions (`SimCATS`) is a Python framework for simulating charge stability 
@@ -166,6 +186,20 @@ This subpackage contains support functions, which are used by the end user and b
 - `ParameterSamplingInterface` defines an interface for randomly sampled (fluctuated) strengths of distortions.
   - `NormalSamplingRange` and `UniformSamplingRange` are implementations of the `ParameterSamplingInterface`.
 
+## Citations
+
+```bibtex
+@article{hader2024simcats,
+  author={Hader, Fabian and Fleitmann, Sarah and Vogelbruch, Jan and Geck, Lotte and Waasen, Stefan van},
+  journal={IEEE Transactions on Quantum Engineering}, 
+  title={Simulation of Charge Stability Diagrams for Automated Tuning Solutions (SimCATS)}, 
+  year={2024},
+  volume={5},
+  pages={1-14},
+  doi={10.1109/TQE.2024.3445967}
+}
+```
+
 ## License, CLA, and Copyright
 
 [![CC BY-NC-SA 4.0][cc-by-nc-sa-shield]][cc-by-nc-sa]
@@ -181,4 +215,4 @@ This work is licensed under a
 
 Contributions must follow the Contributor License Agreement. For more information, see the CONTRIBUTING.md file at the top of the GitHub repository.
 
-Copyright © 2023 Forschungszentrum Jülich GmbH - Central Institute of Engineering, Electronics and Analytics (ZEA) - Electronic Systems (ZEA-2)
+Copyright © 2024 Forschungszentrum Jülich GmbH - Central Institute of Engineering, Electronics and Analytics (ZEA) - Electronic Systems (ZEA-2)

{simcats-1.1.0.dist-info → simcats-1.2.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-simcats/__init__.py,sha256=v8TOUudnx9Q6cNwoVjZkvmHv3VmZCTqEfR7D5sDbUA0,300
+simcats/__init__.py,sha256=pnTS1t8IQKm2SpadtblS8VKUFKm0OfBkiT7rQGzj8Ws,300
 simcats/_default_configs.py,sha256=wHWa4wyTVtZf9J37WdcMlvM7XeI_OZhl8NB7lrBi-yI,6980
 simcats/_simulation.py,sha256=xvKLnOzwc8uGGLfXvBZPaLYYPHBaXcwwtlYmJ3zTkUU,24795
 simcats/distortions/__init__.py,sha256=3oXqKm1rkznDKhWeitZxYJyb1wFMdan6CBfBw673J7A,1368
@@ -23,15 +23,15 @@ simcats/sensor/_gaussian_sensor_peak.py,sha256=7xrSfl505MygBJ7Nu3V3RJpNq8q-mjukV
 simcats/sensor/_generic_sensor.py,sha256=88E6xP3r5GZCBKaR7TKtqrWovR4XW-mm6YUwL96L_AQ,10441
 simcats/sensor/_lorentzian_sensor_peak.py,sha256=Rj3Tpk6dksZGfOAHhdSGQR-wJo3ehdmXnumXyGuaNC4,3952
 simcats/sensor/_sensor_interface.py,sha256=mn5L9WbAIMun_ou0AHgOV6XiBeykYPugndLAeufadTo,5064
-simcats/support_functions/__init__.py,sha256=cSJXeCLuquzZFoY_dLY4B2nTT08Ngpch1FMfYDzkiSg,1032
+simcats/support_functions/__init__.py,sha256=6aXPXtvcaL4bcOADy1yWhhyehT6BDs3Yt_3uOFbBE50,1086
 simcats/support_functions/_cumulative_distribution_functions.py,sha256=pE01RoSL2VwtkBP7xYivd-vcd6krSJrb4xb8MCfyRBA,3366
 simcats/support_functions/_fermi_filter1d.py,sha256=F4GrdLt0bOXidRdg0P-163Op-bxKvgHte3ENI39qYAk,3706
-simcats/support_functions/_parameter_sampling.py,sha256=0TYceyE3ejLtZZ-ofCJ3icTKFpUvHf1xZycVIbHWxfE,10555
+simcats/support_functions/_parameter_sampling.py,sha256=xEd4V0bUqpkE5DpZA0i1YNe8G86IZP1LB2dmkFTg3l0,15331
 simcats/support_functions/_plotting.py,sha256=xc050m4W6RZm8XdOdqruc-6IYyhzW9UFvNlJEgkJRi8,9070
 simcats/support_functions/_rotate_points.py,sha256=4tgzE4a4uykBVw2pSK55DzGe-5n9N38nsBYhfA38Qgs,778
 simcats/support_functions/_signed_dist_points_line.py,sha256=dMnDoBARY7C48xCHFp8mNFNCkPk7YUiaWaRqAsindsE,908
-simcats-1.1.0.dist-info/LICENSE,sha256=aZs_e2FTt6geKaC1hd9FpoxERpb5YHhxJ608urp4nig,21294
-simcats-1.1.0.dist-info/METADATA,sha256=u-ZTqGo-9AKHdgQTs7pv_zvqhklIXHlBMja7vK3x0hs,10680
-simcats-1.1.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-simcats-1.1.0.dist-info/top_level.txt,sha256=M-ExkkJ_NLsuuJiDo3iM2qPPPsEX29E2MQUmegBZ8Wk,8
-simcats-1.1.0.dist-info/RECORD,,
+simcats-1.2.0.dist-info/LICENSE,sha256=aZs_e2FTt6geKaC1hd9FpoxERpb5YHhxJ608urp4nig,21294
+simcats-1.2.0.dist-info/METADATA,sha256=QFMyj-AF9-K0_0u5mnPbCO1AXlB7l0gJqTDuIdT3ixg,11918
+simcats-1.2.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+simcats-1.2.0.dist-info/top_level.txt,sha256=M-ExkkJ_NLsuuJiDo3iM2qPPPsEX29E2MQUmegBZ8Wk,8
+simcats-1.2.0.dist-info/RECORD,,

{simcats-1.1.0.dist-info → simcats-1.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.42.0)
+Generator: setuptools (75.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any