From 4041d67cb2a0706a2778773b7ddada5740f6c50d Mon Sep 17 00:00:00 2001 From: Oleksandr Pavlyk Date: Wed, 21 Feb 2024 16:14:53 -0600 Subject: [PATCH 01/18] Clean state and .nojekyll for gh-pages --- .nojekyll | 0 LICENSE.txt | 24 - README.md | 61 - conda-recipe/bld.bat | 5 - conda-recipe/build.sh | 5 - conda-recipe/meta.yaml | 48 - examples/README.md | 56 - examples/arg_parsing.py | 36 - examples/parallel_mc.py | 46 - examples/parallel_random_states.py | 17 - examples/stick_tetrahedron.py | 77 - examples/stick_triangle.py | 95 - examples/sticky_math.py | 166 - mkl_random/__init__.py | 42 - mkl_random/_version.py | 1 - mkl_random/mklrand.pyx | 5895 -------------------------- mkl_random/src/.gitignore | 1 - mkl_random/src/generate_mklrand_c.py | 42 - mkl_random/src/mkl_distributions.cpp | 2057 --------- mkl_random/src/mkl_distributions.h | 137 - mkl_random/src/mklrand_py_helper.h | 41 - mkl_random/src/numpy.pxd | 152 - mkl_random/src/randomkit.cpp | 440 -- mkl_random/src/randomkit.h | 134 - mkl_random/tests/__init__.py | 25 - mkl_random/tests/test_random.py | 1045 ----- mkl_random/tests/test_regression.py | 181 - setup.py | 160 - 28 files changed, 10989 deletions(-) create mode 100644 .nojekyll delete mode 100644 LICENSE.txt delete mode 100644 README.md delete mode 100644 conda-recipe/bld.bat delete mode 100644 conda-recipe/build.sh delete mode 100644 conda-recipe/meta.yaml delete mode 100644 examples/README.md delete mode 100644 examples/arg_parsing.py delete mode 100644 examples/parallel_mc.py delete mode 100644 examples/parallel_random_states.py delete mode 100644 examples/stick_tetrahedron.py delete mode 100644 examples/stick_triangle.py delete mode 100644 examples/sticky_math.py delete mode 100644 mkl_random/__init__.py delete mode 100644 mkl_random/_version.py delete mode 100644 mkl_random/mklrand.pyx delete mode 100644 mkl_random/src/.gitignore delete mode 100644 mkl_random/src/generate_mklrand_c.py delete mode 100644 mkl_random/src/mkl_distributions.cpp delete mode 100644 mkl_random/src/mkl_distributions.h delete mode 100644 mkl_random/src/mklrand_py_helper.h delete mode 100644 mkl_random/src/numpy.pxd delete mode 100644 mkl_random/src/randomkit.cpp delete mode 100644 mkl_random/src/randomkit.h delete mode 100644 mkl_random/tests/__init__.py delete mode 100644 mkl_random/tests/test_random.py delete mode 100644 mkl_random/tests/test_regression.py delete mode 100644 setup.py diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/LICENSE.txt b/LICENSE.txt deleted file mode 100644 index 85fa35f..0000000 --- a/LICENSE.txt +++ /dev/null @@ -1,24 +0,0 @@ -Copyright (c) 2017-2019, Intel Corporation - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - * Neither the name of Intel Corporation nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md deleted file mode 100644 index c903528..0000000 --- a/README.md +++ /dev/null @@ -1,61 +0,0 @@ -## ``mkl_random`` -- a NumPy-based Python interface to Intel (R) MKL Random Number Generation functionality -[![Build Status](https://travis-ci.com/IntelPython/mkl_random.svg?branch=master)](https://travis-ci.com/IntelPython/mkl_random) - -`mkl_random` has started as Intel (R) Distribution for Python optimizations for NumPy. - -Per NumPy's community suggestions, voiced in https://github.com/numpy/numpy/pull/8209, it is being released as a -stand-alone package. - -Prebuilt `mkl_random` can be installed into conda environment from Intel's channel on Anaconda cloud: - -``` - conda install -c intel mkl_random -``` - ---- - -To install mkl_random Pypi package please use following command: - -``` - python -m pip install --i https://pypi.anaconda.org/intel/simple -extra-index-url https://pypi.org/simple mkl_random -``` - -If command above installs NumPy package from the Pypi, please use following command to install Intel optimized NumPy wheel package from Anaconda Cloud: - -``` - python -m pip install --i https://pypi.anaconda.org/intel/simple -extra-index-url https://pypi.org/simple mkl_random numpy== -``` - -Where `` should be the latest version from https://anaconda.org/intel/numpy - ---- - -`mkl_random` is not fixed-seed backward compatible drop-in replacement for `numpy.random`, meaning that it implements sampling from the same distributions as `numpy.random`. - -For distributions directly supported in Intel (R) Math Kernel Library (MKL), `method` keyword is supported: - -``` - mkl_random.standard_normal(size=(10**5, 10**3), method='BoxMuller') -``` - -Additionally, `mkl_random` exposes different basic random number generation algorithms available in MKL. For example to use `SFMT19937` use - -``` - mkl_random.RandomState(77777, brng='SFMT19937') -``` - -For generator families, such that `MT2203` and Wichmann-Hill, a particular member of the family can be chosen by specifying ``brng=('WH', 3)``, etc. - -The list of supported by `mkl_random.RandomState` constructor `brng` keywords is as follows: - - * 'MT19937' - * 'SFMT19937' - * 'WH' or ('WH', id) - * 'MT2203' or ('MT2203', id) - * 'MCG31' - * 'R250' - * 'MRG32K3A' - * 'MCG59' - * 'PHILOX4X32X10' - * 'NONDETERM' - * 'ARS5' diff --git a/conda-recipe/bld.bat b/conda-recipe/bld.bat deleted file mode 100644 index 1b04207..0000000 --- a/conda-recipe/bld.bat +++ /dev/null @@ -1,5 +0,0 @@ -@rem Remember to source the compiler - -set MKLROOT=%CONDA_PREFIX% -%PYTHON% setup.py install -if errorlevel 1 exit 1 diff --git a/conda-recipe/build.sh b/conda-recipe/build.sh deleted file mode 100644 index 34241cc..0000000 --- a/conda-recipe/build.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/bash -x - -export CFLAGS="-I$PREFIX/include $CFLAGS" -export MKLROOT=$CONDA_PREFIX -$PYTHON setup.py install diff --git a/conda-recipe/meta.yaml b/conda-recipe/meta.yaml deleted file mode 100644 index 3a74593..0000000 --- a/conda-recipe/meta.yaml +++ /dev/null @@ -1,48 +0,0 @@ -{% set version = "1.2.5" %} -{% set buildnumber = 0 %} - -package: - name: mkl_random - version: {{ version }} - -source: - path: .. - -build: - number: {{buildnumber}} - ignore_run_exports: - - blas - -requirements: - build: - - {{ compiler('c') }} - - {{ compiler('cxx') }} - host: - - python - - setuptools - - mkl-devel - - cython - - numpy-base - - pip - run: - - python - - {{ pin_compatible('mkl', min_pin="x.x", max_pin="x") }} - - {{ pin_compatible('numpy', min_pin="x.x", max_pin="x") }} - -test: - commands: - - pytest --pyargs mkl_random - requires: - - pytest - - mkl-service - - numpy - imports: - - mkl_random - - mkl_random.mklrand - -about: - home: http://github.com/IntelPython/mkl_random - license: BSD-3-Clause - license_family: BSD - license_file: LICENSE.txt - summary: NumPy-based implementation of random number generation sampling using Intel (R) Math Kernel Library, mirroring numpy.random, but exposing all choices of sampling algorithms available in MKL. diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index 845b1d6..0000000 --- a/examples/README.md +++ /dev/null @@ -1,56 +0,0 @@ -# Parallel Monte-Carlo example - -Using `mkl_random` package, we use MT-2203 family of pseudo-random number generation algorithms, -we create workers, assign them RandomState objects with different members of the family of algorithms, -and use multiprocessing Pool to distribute chunks of MC work to them to process. - -Each worker gets `rs` and `n` arguments, `rs` representing RandomState object associated with the worker, -and `n` being the size of the problem. `rs` is used to generate samples of size `n`, perform Monte-Carlo -estimate(s) based on the sample and return. - -After run is complete, a generator is returns that contains results of each worker. - -This data is post-processed as necessary for the application. - -## Stick triangle problem - -Code is tested to estimate the probability that 3 segments, obtained by splitting a unit stick -in two randomly chosen places, can be sides of a triangle. This probability is known in closed form to be $\frac{1}{4}$. - -Run python script "stick_triangle.py" to estimate this probability using parallel Monte-Carlo algorithm: - -``` -> python stick_triangle.py -Parallel Monte-Carlo estimation of stick triangle probability -Parameters: n_workers=12, batch_size=262144, n_batches=10000, seed=77777 - -Monte-Carlo estimate of probability: 0.250000 -Population estimate of the estimator's standard deviation: 0.000834 -Expected standard deviation of the estimator: 0.000846 -Execution time: 64.043 seconds - -``` - -## Stick tetrahedron problem - -Code is used to estimate the probability that 6 segments, obtained by splitting a unit stick in -5 random chosen places, can be sides of a tetrahedron. - -The probability is not known in closed form. See -[math.stackexchange.com/questions/351913](https://math.stackexchange.com/questions/351913/probability-that-a-stick-randomly-broken-in-five-places-can-form-a-tetrahedron) for more details. - -``` -> python stick_tetrahedron.py -s 1274 -p 4 -n 8096 -Parallel Monte-Carlo estimation of stick tetrahedron probability -Input parameters: -s 1274 -b 65536 -n 8096 -p 4 -d 0 - -Monte-Carlo estimate of probability: 0.01257113 -Population estimate of the estimator's standard deviation: 0.00000488 -Expected standard deviation of the estimator: 0.00000484 -Total MC size: 530579456 - -Bayesian posterior beta distribution parameters: (6669984, 523909472) - -Execution time: 30.697 seconds - -``` diff --git a/examples/arg_parsing.py b/examples/arg_parsing.py deleted file mode 100644 index 754b7ae..0000000 --- a/examples/arg_parsing.py +++ /dev/null @@ -1,36 +0,0 @@ -import argparse - -__all__ = ['parse_arguments'] - -def pos_int(s): - v = int(s) - if v > 0: - return v - else: - raise argparse.ArgumentTypeError('%r is not a positive integer' % s) - - -def nonneg_int(s): - v = int(s) - if v >= 0: - return v - else: - raise argparse.ArgumentTypeError('%r is not a non-negative integer' % s) - - -def parse_arguments(): - argParser = argparse.ArgumentParser( - prog="stick_tetrahedron.py", - description="Monte-Carlo estimation of probability that 6 segments of a stick randomly broken in 5 places can form a tetrahedron.", - formatter_class=argparse.ArgumentDefaultsHelpFormatter) - - argParser.add_argument('-s', '--seed', default=7777, type=pos_int, help="Random seed to initialize algorithms from MT2203 family") - argParser.add_argument('-b', '--batch_size', default=65536, type=pos_int, help="Batch size for the Monte-Carlo run") - argParser.add_argument('-n', '--batch_count', default=2048, type=pos_int, help="Number of batches executed in parallel") - argParser.add_argument('-p', '--processes', default=-1, type=int, help="Number of processes used to execute batches") - argParser.add_argument('-d', '--id_offset', default=0, type=nonneg_int, help="Offset for the MT2203/WH algorithms id") - argParser.add_argument('-j', '--jump_size', default=0, type=nonneg_int, help="Jump size for skip-ahead") - - args = argParser.parse_args() - - return args diff --git a/examples/parallel_mc.py b/examples/parallel_mc.py deleted file mode 100644 index 04f11fd..0000000 --- a/examples/parallel_mc.py +++ /dev/null @@ -1,46 +0,0 @@ -import multiprocessing as mp -from functools import partial - -__all__ = ['parallel_mc_run'] - -def worker_compute(w_id): - "Worker function executed on the spawned slave process" - global _local_rs, _worker_mc_compute_func - return _worker_mc_compute_func(_local_rs) - - -def init_worker(w_rs, mc_compute_func=None, barrier=None): - """Assign process local random state variable `rs` the given value""" - assert not '_local_rs' in globals(), "Here comes trouble. Process is not expected to have global variable `_local_rs`" - - global _local_rs, _worker_mc_compute_func - _local_rs = w_rs - _worker_mc_compute_func = mc_compute_func - # wait to ensure that the assignment takes place for each worker - barrier.wait() - -def parallel_mc_run(random_states, n_workers, n_batches, mc_func): - """ - Given iterable `random_states` of length `n_workers`, the number of batches `n_batches`, - and the function `worker_compute` to execute, return iterator with results returned by - the supplied function. The function is expected to conform to signature f(worker_id), - and has access to worker-local global variable `rs`, containing worker's random states. - """ - # use of Barrier ensures that every worker gets one - - with mp.Manager() as manager: - b = manager.Barrier(n_workers) - - with mp.Pool(processes=n_workers) as pool: - # 1. map over every worker once to distribute RandomState instances - pool.map(partial(init_worker, mc_compute_func=mc_func, barrier=b), random_states, chunksize=1) - # 2. Perform computations on workers - r = pool.map(worker_compute, range(n_batches), chunksize=1) - - return r - - -def sequential_mc_run(random_states, n_workers, n_batches, mc_func): - for rs in random_states: - for _ in range(n_batches): - yield mc_func(rs) diff --git a/examples/parallel_random_states.py b/examples/parallel_random_states.py deleted file mode 100644 index cdcaf72..0000000 --- a/examples/parallel_random_states.py +++ /dev/null @@ -1,17 +0,0 @@ -import mkl_random as rnd - - -def build_MT2203_random_states(seed, id0, n_workers): - # Create instances of RandomState for each worker process from MT2203 family of generators - return (rnd.RandomState(seed, brng=('MT2203', id0 + idx)) for idx in range(n_workers)) - - -def build_SFMT19937_random_states(seed, jump_size, n_workers): - import copy - # Create instances of RandomState for each worker process from MT2203 family of generators - rs = rnd.RandomState(seed, brng='SFMT19937') - yield copy.copy(rs) - for _ in range(1, n_workers): - rs.skipahead(jump_size) - yield copy.copy(rs) - diff --git a/examples/stick_tetrahedron.py b/examples/stick_tetrahedron.py deleted file mode 100644 index c01cf6b..0000000 --- a/examples/stick_tetrahedron.py +++ /dev/null @@ -1,77 +0,0 @@ -import numpy as np -from parallel_mc import parallel_mc_run, sequential_mc_run -from parallel_random_states import build_MT2203_random_states -from sticky_math import mc_six_piece_stick_tetrahedron_prob -from arg_parsing import parse_arguments - -def mc_runner(rs, batch_size=None): - return mc_six_piece_stick_tetrahedron_prob(rs, batch_size) - -def aggregate_mc_counts(counts, n_batches, batch_size): - ps = counts / batch_size - # compute sample estimator's mean and standard deviation - p_est = ps.mean() - p_std = ps.std()/np.sqrt(batches) - - # compute parameters for Baysean posterior of the probability - event_count = 0 - nonevent_count = 0 - for ni in counts: - event_count += int(ni) - nonevent_count += int(batch_size - ni) - - assert event_count >= 0 - assert nonevent_count >= 0 - return (p_est, p_std, event_count, nonevent_count) - - -def print_result(p_est, p_std, mc_size): - dig = 3 - int(np.log10(p_std)) # only show 3 digits past width of confidence interval - frm_str = "{0:0." + str(dig) + "f}" - - print(("Monte-Carlo estimate of probability: " + frm_str).format(p_est)) - print(("Population estimate of the estimator's standard deviation: " + frm_str).format(p_std)) - print(("Expected standard deviation of the estimator: " + frm_str).format(np.sqrt(p_est * (1-p_est)/mc_size))) - print("Total MC size: {}".format(mc_size)) - - -if __name__ == '__main__': - import multiprocessing as mp - from itertools import repeat - from timeit import default_timer as timer - import sys - from functools import partial - - args = parse_arguments() - - seed = args.seed - n_workers = args.processes - if n_workers <= 0: - n_workers = mp.cpu_count() - - batch_size = args.batch_size - batches = args.batch_count - id0 = args.id_offset - print("Parallel Monte-Carlo estimation of stick tetrahedron probability") - print("Input parameters: -s {seed} -b {batchSize} -n {numBatches} -p {processes} -d {idOffset}".format( - seed=args.seed, batchSize=args.batch_size, numBatches=args.batch_count, processes=n_workers, idOffset=args.id_offset)) - print("") - - t0 = timer() - - rss = build_MT2203_random_states(seed, id0, n_workers) - - r = parallel_mc_run(rss, n_workers, batches, partial(mc_runner, batch_size=batch_size)) - # r = sequential_mc_run(rss, n_workers, batches, partial(mc_runner, batch_size=batch_size)) - - # retrieve values of estimates into numpy array - counts = np.fromiter(r, dtype=np.double) - p_est, p_std, event_count, nonevent_count = aggregate_mc_counts(counts, batches, batch_size) - - t1 = timer() - - print_result(p_est, p_std, batches * batch_size) - print("") - print("Bayesian posterior beta distribution parameters: ({0}, {1})".format(event_count, nonevent_count)) - print("") - print("Execution time: {0:0.3f} seconds".format(t1-t0)) diff --git a/examples/stick_triangle.py b/examples/stick_triangle.py deleted file mode 100644 index 865fa9a..0000000 --- a/examples/stick_triangle.py +++ /dev/null @@ -1,95 +0,0 @@ -import numpy as np -import mkl_random as rnd - -__doc__ = """ -Let's solve a classic problem of MC-estimating a probability that 3 segments of a unit stick randomly broken in 2 places can form a triangle. -Let $u_1$ and $u_2$ be standard uniform random variables, denoting positions where the stick has been broken. - -Let $w_1 = \min(u_1, u_2)$ and $w_2 = \max(u_1, u_2)$. Then, length of segments are $x_1 = w_1$, $x_2 = w_2-w_1$, $x_3 = 1-w_2$. -These lengths must satisfy triangle inequality. - -The closed form result is known to be $\frac{1}{4}$. - -""" - -def triangle_inequality(x1, x2, x3): - """Efficiently finds `np.less(x1,x2+x3)*np.less(x2,x1+x3)*np.less(x3,x1+x2)`""" - tmp_sum = x2 + x3 - res = np.less(x1, tmp_sum) # x1 < x2 + x3 - np.add(x1, x3, out=tmp_sum) - buf = np.less(x2, tmp_sum) # x2 < x1 + x3 - np.logical_and(res, buf, out=res) - np.add(x1, x2, out=tmp_sum) - np.less(x3, tmp_sum, out=buf) # x3 < x1 + x2 - np.logical_and(res, buf, out=res) - return res - - -def mc_dist(rs, n): - """Monte Carlo estimate of probability on sample of size `n`, using given random state object `rs`""" - ws = np.sort(rs.rand(2,n), axis=0) - x2 = np.empty(n, dtype=np.double) - x3 = np.empty(n, dtype=np.double) - - x1 = ws[0] - np.subtract(ws[1], ws[0], out=x2) - np.subtract(1, ws[1], out=x3) - mc_prob = triangle_inequality(x1, x2, x3).sum() / n - - return mc_prob - - -def init_worker(w_rs, barrier=None): - """Assign process local random state variable `rs` the given value""" - assert not 'rs' in globals(), "Here comes trouble. Process is not expected to have global variable `rs`" - - global rs - rs = w_rs - # wait to ensure that the assignment takes place for each worker - barrier.wait() - - -def worker_compute(w_id, batch_size=None): - return mc_dist(rs, batch_size) - - -if __name__ == '__main__': - import multiprocessing as mp - from itertools import repeat - from timeit import default_timer as timer - from functools import partial - - seed = 77777 - n_workers = 12 - batch_size = 1024 * 256 - batches = 10000 - print("Parallel Monte-Carlo estimation of stick triangle probability") - print(f"Parameters: n_workers={n_workers}, batch_size={batch_size}, n_batches={batches}, seed={seed}") - print("") - - t0 = timer() - # Create instances of RandomState for each worker process from MT2203 family of generators - rss = [ rnd.RandomState(seed, brng=('MT2203', idx)) for idx in range(n_workers) ] - with mp.Manager() as manager: - # use of Barrier ensures that every worker gets one - b = manager.Barrier(n_workers) - - with mp.Pool(processes=n_workers) as pool: - # map over every worker once to distribute RandomState instances - pool.map(partial(init_worker, barrier=b), rss, chunksize=1) - # Perform computations on workers - r = pool.map(partial(worker_compute, batch_size=batch_size), range(batches), chunksize=1) - - # retrieve values of estimates into numpy array - ps = np.fromiter(r, dtype=np.double) - # compute sample estimator's mean and standard deviation - p_est = ps.mean() - pop_std = ps.std() - t1 = timer() - - dig = 3 - int(np.log10(pop_std)) - frm_str = "{0:0." + str(dig) + "f}" - print(("Monte-Carlo estimate of probability: " + frm_str).format(p_est)) - print(("Population estimate of the estimator's standard deviation: " + frm_str).format(pop_std)) - print(("Expected standard deviation of the estimator: " + frm_str).format(np.sqrt(p_est * (1-p_est)/batch_size))) - print("Execution time: {0:0.3f} seconds".format(t1-t0)) diff --git a/examples/sticky_math.py b/examples/sticky_math.py deleted file mode 100644 index 6a92be5..0000000 --- a/examples/sticky_math.py +++ /dev/null @@ -1,166 +0,0 @@ -import numpy as np - -__doc__ = """ -https://math.stackexchange.com/questions/351913/probability-that-a-stick-randomly-broken-in-five-places-can-form-a-tetrahedron - -Choose 5 locations on a stick to break it into 6 pieces. What is the probability that these 6 pieces can be edge-lengths of a -tetrahedron (3D symplex). - -""" - -__all__ = ['mc_three_piece_stick_triangle_prob', 'mc_six_piece_stick_tetrahedron_prob'] - -def triangle_inequality_(x1, x2, x3): - """Efficiently finds `np.less(x1,x2+x3)*np.less(x2,x1+x3)*np.less(x3,x1+x2)`""" - tmp_sum = x2 + x3 - res = np.less(x1, tmp_sum) # x1 < x2 + x3 - np.add(x1, x3, out=tmp_sum) - buf = np.less(x2, tmp_sum) # x2 < x1 + x3 - np.logical_and(res, buf, out=res) - np.add(x1, x2, out=tmp_sum) - np.less(x3, tmp_sum, out=buf) # x3 < x1 + x2 - np.logical_and(res, buf, out=res) - return res - - -def triangle_inequality(x1, x2, x3, out=None): - """Efficiently finds `np.less(x1,x2+x3)*np.less(x2,x1+x3)*np.less(x3,x1+x2)`, - logically ending this on top of out array, if any""" - if out is None: - return triangle_inequality_(x1, x2, x3) - res = out - tmp_sum = x2 + x3 - buf = np.less(x1, tmp_sum) # x1 < x2 + x3 - np.logical_and(res, buf, out=res) - np.add(x1, x3, out=tmp_sum) - np.less(x2, tmp_sum, out=buf) # x2 < x1 + x3 - np.logical_and(res, buf, out=res) - np.add(x1, x2, out=tmp_sum) - np.less(x3, tmp_sum, out=buf) # x3 < x1 + x2 - np.logical_and(res, buf, out=res) - return res - - -def facial_tetrahedron(x, y, z, xb, yb, zb): - """ - Computes boolean mask for facial tetrahedron condition for six side-lengths - This condition is necessary, but not sufficient for 3 sticks to form a tetrahedon yet, - it needs to be supplemented with positivity of Cayley-Manger determinant. - """ - success_mask = triangle_inequality(x, y, zb) # x, y, zb - triangle_inequality(x, y, zb, out = success_mask) # x, yb, z - triangle_inequality(xb, y, z, out = success_mask) # xb, y, z - triangle_inequality(xb, yb, zb, out = success_mask) # xb, yb, zb - return success_mask - - -def cayley_menger_mat(x2, y2, z2, xb2, yb2, zb2): - """ - Menger's determinant. - - If positive, there exist 4 points in R^3, with pair-wise distances squared equal to given 6 arguments. - - K. Wirth, A.S. Dreiding, Edge lengths determining tetrahedrons, Elemente der Mathematic, vol. 64 (2009) pp. 160-170. - """ - one = np.ones_like(x2) - zero = np.zeros_like(x2) - mat = np.array([[zero, x2, y2, z2, one], - [x2, zero, zb2, yb2, one], - [y2, zb2, zero, xb2, one], - [z2, yb2, xb2, zero, one], - [one, one, one, one, zero] - ]).T - return mat - - -def cayley_menger_det_no_linalg(x2, y2, z2, xb2, yb2, zb2): - """ - D(S) = 2 * x2 * xb2 * (y2 + yb2 + z2 + zb2 - x2 - xb2) + - 2 * y2 * yb2 * (z2 + zb2 + x2 + xb2 - y2 - yb2) + - 2 * z2 * zb2 * (x2 + xb2 + y2 + yb2 - z2 - zb2) + - (x2 - xb2) * (y2 - yb2) * (z2 - zb2) - - (x2 + xb2) * (x2 + xb2) * (z2 + zb2) - """ - xs = x2 + xb2 - ys = y2 + yb2 - zs = z2 + zb2 - buf1 = ys + zs - buf1 -= xs - buf2 = x2 * xb2 - buf1 *= buf2 # buf1 has first term, halved - np.multiply(y2, yb2, out=buf2) - buf3 = xs + zs - buf3 -= ys - buf2 *= buf3 # buf2 has second term - buf1 += buf2 # buf1 is sum of two terms, halved - np.multiply(z2, zb2, out=buf3) - np.add(xs, ys, out=buf2) # reuse buf2 - buf2 -= zs - buf3 *= buf2 # buf3 has third term - buf1 += buf3 # buf1 is sum of 3 first terms, halved - buf1 *= 2 - np.subtract(x2, xb2, out=buf2) - np.subtract(y2, yb2, out=buf3) - buf2 *= buf3 - np.subtract(z2, zb2, out=buf3) - buf2 *= buf3 - buf1 += buf2 # buf1 is sum of 4 first terms - np.multiply(xs, ys, out=buf3) - buf3 *= zs - buf1 -= buf3 - return buf1 - - -def cayley_menger_cond(x2, y2, z2, xb2, yb2, zb2): - # return np.linalg.det(cayley_menger_mat(x2, y2, z2, xb2, yb2, zb2)) > 0 - return cayley_menger_det_no_linalg(x2, y2, z2, xb2, yb2, zb2) > 0 - - -def mc_six_piece_stick_tetrahedron_prob(rs, n): - """ - Monte-Carlo estimate of the probability that a unit stick, randomly broken in 5 places (making 6 pieces), - can form a tetrahedron. - - Using provided random state instance `rs` routine generates `n` samples, and outputs the number of - tetrahedral 6-tuples. - """ - u = rs.rand(6,n) - u[0, :] = 1 - np.log(u[1], out=u[1]) - u[1] /= 5 - np.exp(u[1], out=u[1]) # np.power(u[1], 1/5, out=u[1]) - np.sqrt(u[2], out=u[2]) - np.sqrt(u[2], out=u[2]) - np.cbrt(u[3], out=u[3]) - np.sqrt(u[4], out=u[4]) - np.cumprod(u, axis=0, out=u) - u[0] -= u[1] - u[1] -= u[2] - u[2] -= u[3] - u[3] -= u[4] - u[4] -= u[5] - - success_mask = facial_tetrahedron(u[0], u[1], u[2], u[3], u[4], u[5]) - np.square(u, out=u) # only squares enter Cayler-Manger determinant - cm_mask = cayley_menger_cond(u[0], u[1], u[2], u[3], u[4], u[5]) - np.logical_and(success_mask, cm_mask, out=success_mask) - - return success_mask.sum() - - -def mc_three_piece_stick_triangle_prob(rs, n): - """ - Monte-Carlo estimate of probability that a unit stick, randomly broken in 2 places (making 3 pieces), - corresponds to a triple of sides of a triangle. - - Using provided random state instance `rs` routine generates `n` samples, and outputs the number of - triangular 3-tuples.""" - ws = np.sort(rs.rand(2,n), axis=0) - x2 = np.empty(n, dtype=np.double) - x3 = np.empty(n, dtype=np.double) - - x1 = ws[0] - np.subtract(ws[1], ws[0], out=x2) - np.subtract(1, ws[1], out=x3) - - return triangle_inequality_(x1, x2, x3).sum() diff --git a/mkl_random/__init__.py b/mkl_random/__init__.py deleted file mode 100644 index a7af229..0000000 --- a/mkl_random/__init__.py +++ /dev/null @@ -1,42 +0,0 @@ -#!/usr/bin/env python -# Copyright (c) 2017-2019, Intel Corporation -# -# Redistribution and use in source and binary forms, with or without -# modification, are permitted provided that the following conditions are met: -# -# * Redistributions of source code must retain the above copyright notice, -# this list of conditions and the following disclaimer. -# * Redistributions in binary form must reproduce the above copyright -# notice, this list of conditions and the following disclaimer in the -# documentation and/or other materials provided with the distribution. -# * Neither the name of Intel Corporation nor the names of its contributors -# may be used to endorse or promote products derived from this software -# without specific prior written permission. -# -# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE -# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -from __future__ import division, absolute_import, print_function - -from .mklrand import * -from ._version import __version__ - -try: - from numpy.testing.nosetester import _numpy_tester - test = _numpy_tester().test - bench = _numpy_tester().bench - del _numpy_tester -except ModuleNotFoundError: - # Pytest testing - from numpy._pytesttester import PytestTester - test = PytestTester(__name__) - del PytestTester - diff --git a/mkl_random/_version.py b/mkl_random/_version.py deleted file mode 100644 index 09964d6..0000000 --- a/mkl_random/_version.py +++ /dev/null @@ -1 +0,0 @@ -__version__ = '1.2.5' diff --git a/mkl_random/mklrand.pyx b/mkl_random/mklrand.pyx deleted file mode 100644 index 93c7e26..0000000 --- a/mkl_random/mklrand.pyx +++ /dev/null @@ -1,5895 +0,0 @@ -#!/usr/bin/env python -# Copyright (c) 2017-2020, Intel Corporation -# -# Redistribution and use in source and binary forms, with or without -# modification, are permitted provided that the following conditions are met: -# -# * Redistributions of source code must retain the above copyright notice, -# this list of conditions and the following disclaimer. -# * Redistributions in binary form must reproduce the above copyright -# notice, this list of conditions and the following disclaimer in the -# documentation and/or other materials provided with the distribution. -# * Neither the name of Intel Corporation nor the names of its contributors -# may be used to endorse or promote products derived from this software -# without specific prior written permission. -# -# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE -# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -# cython: language_level=3 - -cdef extern from "Python.h": - void* PyMem_Malloc(size_t n) - void PyMem_Free(void* buf) - - double PyFloat_AsDouble(object ob) - long PyInt_AsLong(object ob) - - int PyErr_Occurred() - void PyErr_Clear() - - -include "numpy.pxd" -from libc.string cimport memset, memcpy - -cdef extern from "math.h": - double floor(double x) - -cdef extern from "numpy/npy_math.h": - int npy_isfinite(double x) - -cdef extern from "mklrand_py_helper.h": - object empty_py_bytes(npy_intp length, void **bytesVec) - char* py_bytes_DataPtr(object b) - int is_bytes_object(object b) - -cdef extern from "randomkit.h": - - ctypedef struct irk_state: - pass - - ctypedef enum irk_error: - RK_NOERR = 0 - RK_ENODEV = 1 - RK_ERR_MAX = 2 - - ctypedef enum irk_brng_t: - MT19937 = 0 - SFMT19937 = 1 - WH = 2 - MT2203 = 3 - MCG31 = 4 - R250 = 5 - MRG32K3A = 6 - MCG59 = 7 - PHILOX4X32X10 = 8 - NONDETERM = 9 - ARS5 = 10 - - void irk_fill(void *buffer, size_t size, irk_state *state) noexcept nogil - - void irk_dealloc_stream(irk_state *state) - void irk_seed_mkl(irk_state * state, unsigned int seed, irk_brng_t brng, unsigned int stream_id) - void irk_seed_mkl_array(irk_state * state, unsigned int * seed_vec, int seed_len, irk_brng_t brng, unsigned int stream_id) - irk_error irk_randomseed_mkl(irk_state * state, irk_brng_t brng, unsigned int stream_id) - int irk_get_stream_size(irk_state * state) noexcept nogil - void irk_get_state_mkl(irk_state * state, char * buf) - int irk_set_state_mkl(irk_state * state, char * buf) - int irk_get_brng_mkl(irk_state *state) noexcept nogil - int irk_get_brng_and_stream_mkl(irk_state *state, unsigned int * stream_id) noexcept nogil - int irk_leapfrog_stream_mkl(irk_state *state, int k, int nstreams) noexcept nogil - int irk_skipahead_stream_mkl(irk_state *state, long long int nskips) noexcept nogil - - -cdef extern from "mkl_distributions.h": - void irk_double_vec(irk_state *state, npy_intp len, double *res) noexcept nogil - void irk_uniform_vec(irk_state *state, npy_intp len, double *res, double dlow, double dhigh) noexcept nogil - - void irk_normal_vec_BM1(irk_state *state, npy_intp len, double *res, double mean, double sigma) noexcept nogil - void irk_normal_vec_BM2(irk_state *state, npy_intp len, double *res, double mean, double sigma) noexcept nogil - void irk_normal_vec_ICDF(irk_state *state, npy_intp len, double *res, double mean, double sigma) noexcept nogil - - void irk_standard_normal_vec_BM1(irk_state *state, npy_intp len, double *res) noexcept nogil - void irk_standard_normal_vec_BM2(irk_state *state, npy_intp len, double *res) noexcept nogil - void irk_standard_normal_vec_ICDF(irk_state *state, npy_intp len, double *res) noexcept nogil - - void irk_standard_exponential_vec(irk_state *state, npy_intp len, double *res) noexcept nogil - void irk_exponential_vec(irk_state *state, npy_intp len, double *res, double scale) noexcept nogil - - void irk_standard_cauchy_vec(irk_state *state, npy_intp len, double *res) noexcept nogil - void irk_standard_gamma_vec(irk_state *state, npy_intp len, double *res, double shape) noexcept nogil - void irk_gamma_vec(irk_state *state, npy_intp len, double *res, double shape, double scale) noexcept nogil - - void irk_beta_vec(irk_state *state, npy_intp len, double *res, double p, double q) noexcept nogil - - void irk_chisquare_vec(irk_state *state, npy_intp len, double *res, double df) noexcept nogil - void irk_standard_t_vec(irk_state *state, npy_intp len, double *res, double df) noexcept nogil - - void irk_rayleigh_vec(irk_state *state, npy_intp len, double *res, double sigma) noexcept nogil - void irk_pareto_vec(irk_state *state, npy_intp len, double *res, double alp) noexcept nogil - void irk_power_vec(irk_state *state, npy_intp len, double *res, double alp) noexcept nogil - void irk_weibull_vec(irk_state *state, npy_intp len, double *res, double alp) noexcept nogil - void irk_f_vec(irk_state *state, npy_intp len, double *res, double df_num, double df_den) noexcept nogil - void irk_noncentral_chisquare_vec(irk_state *state, npy_intp len, double *res, double df, double nonc) noexcept nogil - void irk_laplace_vec(irk_state *state, npy_intp len, double *res, double loc, double scale) noexcept nogil - void irk_gumbel_vec(irk_state *state, npy_intp len, double *res, double loc, double scale) noexcept nogil - void irk_logistic_vec(irk_state *state, npy_intp len, double *res, double loc, double scale) noexcept nogil - void irk_wald_vec(irk_state *state, npy_intp len, double *res, double mean, double scale) noexcept nogil - void irk_lognormal_vec_ICDF(irk_state *state, npy_intp len, double *res, double mean, double scale) noexcept nogil - void irk_lognormal_vec_BM(irk_state *state, npy_intp len, double *res, double mean, double scale) noexcept nogil - void irk_vonmises_vec(irk_state *state, npy_intp len, double *res, double mu, double kappa) noexcept nogil - - void irk_noncentral_f_vec(irk_state *state, npy_intp len, double *res, double df_num, double df_den, double nonc) noexcept nogil - void irk_triangular_vec(irk_state *state, npy_intp len, double *res, double left, double mode, double right) noexcept nogil - - void irk_geometric_vec(irk_state *state, npy_intp len, int *res, double p) noexcept nogil - void irk_negbinomial_vec(irk_state *state, npy_intp len, int *res, double a, double p) noexcept nogil - void irk_binomial_vec(irk_state *state, npy_intp len, int *res, int n, double p) noexcept nogil - void irk_multinomial_vec(irk_state *state, npy_intp len, int *res, int n, int d, double *pvec) noexcept nogil - void irk_hypergeometric_vec(irk_state *state, npy_intp len, int *res, int ls, int ss, int ms) noexcept nogil - - void irk_poisson_vec_PTPE(irk_state *state, npy_intp len, int *res, double lam) noexcept nogil - void irk_poisson_vec_POISNORM(irk_state *state, npy_intp len, int *res, double lam) noexcept nogil - void irk_poisson_vec_V(irk_state *state, npy_intp len, int *res, double *lam_vec) noexcept nogil - - void irk_zipf_long_vec(irk_state *state, npy_intp len, long *res, double alpha) noexcept nogil - void irk_logseries_vec(irk_state *state, npy_intp len, int *res, double theta) noexcept nogil - - # random integers madness - void irk_discrete_uniform_vec(irk_state *state, npy_intp len, int *res, int low, int high) noexcept nogil - void irk_discrete_uniform_long_vec(irk_state *state, npy_intp len, long *res, long low, long high) noexcept nogil - void irk_rand_bool_vec(irk_state *state, npy_intp len, npy_bool *res, npy_bool low, npy_bool high) noexcept nogil - void irk_rand_uint8_vec(irk_state *state, npy_intp len, npy_uint8 *res, npy_uint8 low, npy_uint8 high) noexcept nogil - void irk_rand_int8_vec(irk_state *state, npy_intp len, npy_int8 *res, npy_int8 low, npy_int8 high) noexcept nogil - void irk_rand_uint16_vec(irk_state *state, npy_intp len, npy_uint16 *res, npy_uint16 low, npy_uint16 high) noexcept nogil - void irk_rand_int16_vec(irk_state *state, npy_intp len, npy_int16 *res, npy_int16 low, npy_int16 high) noexcept nogil - void irk_rand_uint32_vec(irk_state *state, npy_intp len, npy_uint32 *res, npy_uint32 low, npy_uint32 high) noexcept nogil - void irk_rand_int32_vec(irk_state *state, npy_intp len, npy_int32 *res, npy_int32 low, npy_int32 high) noexcept nogil - void irk_rand_uint64_vec(irk_state *state, npy_intp len, npy_uint64 *res, npy_uint64 low, npy_uint64 high) noexcept nogil - void irk_rand_int64_vec(irk_state *state, npy_intp len, npy_int64 *res, npy_int64 low, npy_int64 high) noexcept nogil - - void irk_long_vec(irk_state *state, npy_intp len, long *res) noexcept nogil - - ctypedef enum ch_st_enum: - MATRIX = 0 - PACKED = 1 - DIAGONAL = 2 - - void irk_multinormal_vec_ICDF(irk_state *state, npy_intp len, double *res, int dim, double *mean_vec, double *ch, ch_st_enum storage_mode) noexcept nogil - void irk_multinormal_vec_BM1(irk_state *state, npy_intp len, double *res, int dim, double *mean_vec, double *ch, ch_st_enum storage_mode) noexcept nogil - void irk_multinormal_vec_BM2(irk_state *state, npy_intp len, double *res, int dim, double *mean_vec, double *ch, ch_st_enum storage_mode) noexcept nogil - - -ctypedef void (* irk_cont0_vec)(irk_state *state, npy_intp len, double *res) noexcept nogil -ctypedef void (* irk_cont1_vec)(irk_state *state, npy_intp len, double *res, double a) noexcept nogil -ctypedef void (* irk_cont2_vec)(irk_state *state, npy_intp len, double *res, double a, double b) noexcept nogil -ctypedef void (* irk_cont3_vec)(irk_state *state, npy_intp len, double *res, double a, double b, double c) noexcept nogil - -ctypedef void (* irk_disc0_vec)(irk_state *state, npy_intp len, int *res) noexcept nogil -ctypedef void (* irk_disc0_vec_long)(irk_state *state, npy_intp len, long *res) noexcept nogil -ctypedef void (* irk_discnp_vec)(irk_state *state, npy_intp len, int *res, int n, double a) noexcept nogil -ctypedef void (* irk_discdd_vec)(irk_state *state, npy_intp len, int *res, double n, double p) noexcept nogil -ctypedef void (* irk_discnmN_vec)(irk_state *state, npy_intp len, int *res, int n, int m, int N) noexcept nogil -ctypedef void (* irk_discd_vec)(irk_state *state, npy_intp len, int *res, double a) noexcept nogil -ctypedef void (* irk_discd_long_vec)(irk_state *state, npy_intp len, long *res, double a) noexcept nogil -ctypedef void (* irk_discdptr_vec)(irk_state *state, npy_intp len, int *res, double *a) noexcept nogil - - -cdef int r = _import_array() -if (r<0): - raise ImportError("Failed to import NumPy") - -cimport cython -import numpy as np -import operator -import warnings -try: - from threading import Lock -except ImportError: - from dummy_threading import Lock - -cdef object vec_cont0_array(irk_state *state, irk_cont0_vec func, object size, - object lock): - cdef double *array_data - cdef double res - cdef ndarray array "arrayObject" - cdef npy_intp length - - if size is None: - func(state, 1, &res) - return res - else: - array = np.empty(size, np.float64) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - with lock, nogil: - func(state, length, array_data) - - return array - -cdef object vec_cont1_array_sc(irk_state *state, irk_cont1_vec func, object size, double a, - object lock): - cdef double *array_data - cdef double res - cdef ndarray array "arrayObject" - cdef npy_intp length - - if size is None: - func(state, 1, &res, a) - return res - else: - array = np.empty(size, np.float64) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - with lock, nogil: - func(state, length, array_data, a) - - return array - - -cdef object vec_cont1_array(irk_state *state, irk_cont1_vec func, object size, - ndarray oa, object lock): - cdef double *array_data - cdef double *oa_data - cdef ndarray array "arrayObject" - cdef npy_intp i, n, imax, res_size - cdef flatiter itera - cdef broadcast multi - - if size is None: - array = PyArray_SimpleNew(PyArray_NDIM(oa), - PyArray_DIMS(oa) , NPY_DOUBLE) - imax = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - itera = PyArray_IterNew(oa) - with lock, nogil: - for i from 0 <= i < imax: - func(state, 1, array_data + i, ((itera.dataptr))[0]) - PyArray_ITER_NEXT(itera) - else: - array = np.empty(size, np.float64) - array_data = PyArray_DATA(array) - multi = PyArray_MultiIterNew(2, array, oa) - res_size = PyArray_SIZE(array); - if (multi.size != res_size): - raise ValueError("size is not compatible with inputs") - - multi = PyArray_MultiIterNew(1, oa) - imax = multi.size - n = res_size // imax - with lock, nogil: - for i from 0 <= i < imax: - oa_data = PyArray_MultiIter_DATA(multi, 0) - func(state, n, array_data + n*i, oa_data[0]) - PyArray_MultiIter_NEXT(multi) - array.shape = (multi.shape + array.shape)[:array.ndim] - multi_ndim = len(multi.shape) - array = array.transpose(tuple(range(multi_ndim, array.ndim)) + tuple(range(0, multi_ndim))) - - return array - -cdef object vec_cont2_array_sc(irk_state *state, irk_cont2_vec func, object size, double a, - double b, object lock): - cdef double *array_data - cdef double res - cdef ndarray array "arrayObject" - cdef npy_intp length - cdef npy_intp i - - if size is None: - func(state, 1, &res, a, b) - return res - else: - array = np.empty(size, np.float64) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - with lock, nogil: - func(state, length, array_data, a, b) - - return array - -cdef object vec_cont2_array(irk_state *state, irk_cont2_vec func, object size, - ndarray oa, ndarray ob, object lock): - cdef double *array_data - cdef double *oa_data - cdef double *ob_data - cdef ndarray array "arrayObject" - cdef npy_intp i, n, imax, res_size - cdef broadcast multi - - if size is None: - multi = PyArray_MultiIterNew(2, oa, ob) - array = PyArray_SimpleNew(multi.nd, multi.dimensions, NPY_DOUBLE) - array_data = PyArray_DATA(array) - with lock, nogil: - for i from 0 <= i < multi.size: - oa_data = PyArray_MultiIter_DATA(multi, 0) - ob_data = PyArray_MultiIter_DATA(multi, 1) - func(state, 1, &array_data[i], oa_data[0], ob_data[0]) - PyArray_MultiIter_NEXT(multi) - else: - array = np.empty(size, np.float64) - array_data = PyArray_DATA(array) - multi = PyArray_MultiIterNew(3, array, oa, ob) - res_size = PyArray_SIZE(array); - if (multi.size != res_size): - raise ValueError("size is not compatible with inputs") - - multi = PyArray_MultiIterNew(2, oa, ob) - imax = multi.size - n = res_size // imax - with lock, nogil: - for i from 0 <= i < imax: - oa_data = PyArray_MultiIter_DATA(multi, 0) - ob_data = PyArray_MultiIter_DATA(multi, 1) - func(state, n, array_data + n*i, oa_data[0], ob_data[0]) - PyArray_MultiIter_NEXT(multi) - array.shape = (multi.shape + array.shape)[:array.ndim] - multi_ndim = len(multi.shape) - array = array.transpose(tuple(range(multi_ndim, array.ndim)) + tuple(range(0, multi_ndim))) - - return array - - -cdef object vec_cont3_array_sc(irk_state *state, irk_cont3_vec func, object size, double a, - double b, double c, object lock): - cdef double *array_data - cdef double res - cdef ndarray array "arrayObject" - cdef npy_intp length - cdef npy_intp i - - if size is None: - func(state, 1, &res, a, b, c) - return res - else: - array = np.empty(size, np.float64) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - with lock, nogil: - func(state, length, array_data, a, b, c) - - return array - -cdef object vec_cont3_array(irk_state *state, irk_cont3_vec func, object size, - ndarray oa, ndarray ob, ndarray oc, object lock): - cdef double *array_data - cdef double *oa_data - cdef double *ob_data - cdef double *oc_data - cdef ndarray array "arrayObject" - cdef npy_intp i, res_size, n, imax - cdef broadcast multi - - if size is None: - multi = PyArray_MultiIterNew(3, oa, ob, oc) - array = PyArray_SimpleNew(multi.nd, multi.dimensions, NPY_DOUBLE) - array_data = PyArray_DATA(array) - with lock, nogil: - for i from 0 <= i < multi.size: - oa_data = PyArray_MultiIter_DATA(multi, 0) - ob_data = PyArray_MultiIter_DATA(multi, 1) - oc_data = PyArray_MultiIter_DATA(multi, 2) - func(state, 1, &array_data[i], oa_data[0], ob_data[0], oc_data[0]) - PyArray_MultiIter_NEXT(multi) - else: - array = np.empty(size, np.float64) - array_data = PyArray_DATA(array) - multi = PyArray_MultiIterNew(4, array, oa, - ob, oc) - res_size = PyArray_SIZE(array) - if (multi.size != res_size): - raise ValueError("size is not compatible with inputs") - - multi = PyArray_MultiIterNew(3, oa, ob, oc) - imax = multi.size - n = res_size // imax - with lock, nogil: - for i from 0 <= i < imax: - oa_data = PyArray_MultiIter_DATA(multi, 0) - ob_data = PyArray_MultiIter_DATA(multi, 1) - oc_data = PyArray_MultiIter_DATA(multi, 2) - func(state, n, array_data + n*i, oa_data[0], ob_data[0], oc_data[0]) - PyArray_MultiIter_NEXT(multi) - array.shape = (multi.shape + array.shape)[:array.ndim] - multi_ndim = len(multi.shape) - array = array.transpose(tuple(range(multi_ndim, array.ndim)) + tuple(range(0, multi_ndim))) - - return array - -cdef object vec_disc0_array(irk_state *state, irk_disc0_vec func, object size, - object lock): - cdef int *array_data - cdef int res - cdef ndarray array "arrayObject" - cdef npy_intp length - cdef npy_intp i - - if size is None: - func(state, 1, &res) - return res - else: - array = np.empty(size, np.int32) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - with lock, nogil: - func(state, length, array_data) - - return array - -cdef object vec_long_disc0_array( - irk_state *state, irk_disc0_vec_long func, - object size, object lock -): - cdef long *array_data - cdef long res - cdef ndarray array "arrayObject" - cdef npy_intp length - cdef npy_intp i - - if size is None: - func(state, 1, &res) - return res - else: - array = np.empty(size, np.uint) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - with lock, nogil: - func(state, length, array_data) - - return array - - -cdef object vec_discnp_array_sc( - irk_state *state, irk_discnp_vec func, object size, - int n, double p, object lock -): - cdef int *array_data - cdef int res - cdef ndarray array "arrayObject" - cdef npy_intp length - cdef npy_intp i - - if size is None: - func(state, 1, &res, n, p) - return res - else: - array = np.empty(size, np.int32) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - with lock, nogil: - func(state, length, array_data, n, p) - return array - - -cdef object vec_discnp_array(irk_state *state, irk_discnp_vec func, object size, - ndarray on, ndarray op, object lock): - cdef int *array_data - cdef ndarray array "arrayObject" - cdef npy_intp length - cdef npy_intp i, n, imax, res_size - cdef double *op_data - cdef int *on_data - cdef broadcast multi - - if size is None: - multi = PyArray_MultiIterNew(2, on, op) - array = PyArray_SimpleNew(multi.nd, multi.dimensions, NPY_INT) - array_data = PyArray_DATA(array) - with lock, nogil: - for i from 0 <= i < multi.size: - on_data = PyArray_MultiIter_DATA(multi, 0) - op_data = PyArray_MultiIter_DATA(multi, 1) - func(state, 1, &array_data[i], on_data[0], op_data[0]) - PyArray_MultiIter_NEXT(multi) - else: - array = np.empty(size, np.int32) - array_data = PyArray_DATA(array) - multi = PyArray_MultiIterNew(3, array, on, op) - res_size = PyArray_SIZE(array) - if (multi.size != res_size): - raise ValueError("size is not compatible with inputs") - - multi = PyArray_MultiIterNew(2, on, op) - imax = multi.size - n = res_size // imax - with lock, nogil: - for i from 0 <= i < imax: - on_data = PyArray_MultiIter_DATA(multi, 0) - op_data = PyArray_MultiIter_DATA(multi, 1) - func(state, n, array_data + n * i, on_data[0], op_data[0]) - PyArray_MultiIter_NEXT(multi) - array.shape = (multi.shape + array.shape)[:array.ndim] - multi_ndim = len(multi.shape) - array = array.transpose(tuple(range(multi_ndim, array.ndim)) + tuple(range(0, multi_ndim))) - - return array - - -cdef object vec_discdd_array_sc(irk_state *state, irk_discdd_vec func, object size, - double n, double p, object lock): - cdef int *array_data - cdef int res - cdef ndarray array "arrayObject" - cdef npy_intp length - cdef npy_intp i - - if size is None: - func(state, 1, &res, n, p) - return res - else: - array = np.empty(size, np.int32) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - with lock, nogil: - func(state, length, array_data, n, p) - - return array - - -cdef object vec_discdd_array(irk_state *state, irk_discdd_vec func, object size, - ndarray on, ndarray op, object lock): - cdef int *array_data - cdef ndarray array "arrayObject" - cdef npy_intp i, imax, n, res_size - cdef double *op_data - cdef double *on_data - cdef broadcast multi - - if size is None: - multi = PyArray_MultiIterNew(2, on, op) - array = PyArray_SimpleNew(multi.nd, multi.dimensions, NPY_INT) - array_data = PyArray_DATA(array) - with lock, nogil: - for i from 0 <= i < multi.size: - on_data = PyArray_MultiIter_DATA(multi, 0) - op_data = PyArray_MultiIter_DATA(multi, 1) - func(state, 1, &array_data[i], on_data[0], op_data[0]) - PyArray_MultiIter_NEXT(multi) - else: - array = np.empty(size, np.int32) - array_data = PyArray_DATA(array) - res_size = PyArray_SIZE(array) - multi = PyArray_MultiIterNew(3, array, on, op) - if (multi.size != res_size): - raise ValueError("size is not compatible with inputs") - - multi = PyArray_MultiIterNew(2, on, op) - imax = multi.size - n = res_size // imax - with lock, nogil: - for i from 0 <= i < imax: - on_data = PyArray_MultiIter_DATA(multi, 0) - op_data = PyArray_MultiIter_DATA(multi, 1) - func(state, n, array_data + n * i, on_data[0], op_data[0]) - PyArray_MultiIter_NEXT(multi) - array.shape = (multi.shape + array.shape)[:array.ndim] - multi_ndim = len(multi.shape) - array = array.transpose(tuple(range(multi_ndim, array.ndim)) + tuple(range(0, multi_ndim))) - - return array - - -cdef object vec_discnmN_array_sc(irk_state *state, irk_discnmN_vec func, object size, - int n, int m, int N, object lock): - cdef int *array_data - cdef int res - cdef ndarray array "arrayObject" - cdef npy_intp length - cdef npy_intp i - - if size is None: - func(state, 1, &res, n, m, N) - return res - else: - array = np.empty(size, np.int32) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - with lock, nogil: - func(state, length, array_data, n, m, N) - return array - - -cdef object vec_discnmN_array(irk_state *state, irk_discnmN_vec func, object size, - ndarray on, ndarray om, ndarray oN, object lock): - cdef int *array_data - cdef int *on_data - cdef int *om_data - cdef int *oN_data - cdef ndarray array "arrayObject" - cdef npy_intp i - cdef broadcast multi, multi2 - cdef npy_intp imax, n, res_size - - if size is None: - multi = PyArray_MultiIterNew(3, on, om, oN) - array = PyArray_SimpleNew(multi.nd, multi.dimensions, NPY_INT) - array_data = PyArray_DATA(array) - with lock, nogil: - for i from 0 <= i < multi.size: - on_data = PyArray_MultiIter_DATA(multi, 0) - om_data = PyArray_MultiIter_DATA(multi, 1) - oN_data = PyArray_MultiIter_DATA(multi, 2) - func(state, 1, array_data + i, on_data[0], om_data[0], oN_data[0]) - PyArray_MultiIter_NEXT(multi) - else: - array = np.empty(size, np.int32) - array_data = PyArray_DATA(array) - multi = PyArray_MultiIterNew(4, array, on, om, - oN) - res_size = PyArray_SIZE(array) - if (multi.size != res_size): - raise ValueError("size is not compatible with inputs") - - multi = PyArray_MultiIterNew(3, on, om, oN) - imax = multi.size - n = res_size // imax - with lock, nogil: - for i from 0 <= i < imax: - on_data = PyArray_MultiIter_DATA(multi, 0) - om_data = PyArray_MultiIter_DATA(multi, 1) - oN_data = PyArray_MultiIter_DATA(multi, 2) - func(state, n, array_data + n*i, on_data[0], om_data[0], oN_data[0]) - PyArray_MultiIter_NEXT(multi) - array.shape = (multi.shape + array.shape)[:array.ndim] - multi_ndim = len(multi.shape) - array = array.transpose(tuple(range(multi_ndim, array.ndim)) + tuple(range(0, multi_ndim))) - - return array - -cdef object vec_discd_array_sc(irk_state *state, irk_discd_vec func, object size, - double a, object lock): - cdef int *array_data - cdef int res - cdef ndarray array "arrayObject" - cdef npy_intp length - cdef npy_intp i - - if size is None: - func(state, 1, &res, a) - return res - else: - array = np.empty(size, np.int32) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - with lock, nogil: - func(state, length, array_data, a) - - return array - -cdef object vec_long_discd_array_sc(irk_state *state, irk_discd_long_vec func, object size, - double a, object lock): - cdef long *array_data - cdef long res - cdef ndarray array "arrayObject" - cdef npy_intp length - cdef npy_intp i - - if size is None: - func(state, 1, &res, a) - return res - else: - array = np.empty(size, int) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - with lock, nogil: - func(state, length, array_data, a) - - return array - -cdef object vec_discd_array(irk_state *state, irk_discd_vec func, object size, ndarray oa, - object lock): - cdef int *array_data - cdef double *oa_data - cdef ndarray array "arrayObject" - cdef npy_intp length, res_size - cdef npy_intp i, imax, n - cdef broadcast multi - cdef flatiter itera - - if size is None: - array = PyArray_SimpleNew(PyArray_NDIM(oa), - PyArray_DIMS(oa), NPY_INT) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - itera = PyArray_IterNew(oa) - with lock, nogil: - for i from 0 <= i < length: - func(state, 1, &array_data[i], ((itera.dataptr))[0]) - PyArray_ITER_NEXT(itera) - else: - array = np.empty(size, np.int32) - array_data = PyArray_DATA(array) - multi = PyArray_MultiIterNew(2, array, oa) - res_size = PyArray_SIZE(array) - if (multi.size != res_size): - raise ValueError("size is not compatible with inputs") - - imax = oa.size - n = res_size // imax - with lock, nogil: - for i from 0 <= i < imax: - oa_data = PyArray_MultiIter_DATA(multi, 1) - func(state, n, array_data + n*i, oa_data[0]) - PyArray_MultiIter_NEXTi(multi, 1) - array.shape = (oa.shape + array.shape)[:array.ndim] - array = array.transpose(tuple(range(oa.ndim, array.ndim)) + tuple(range(0, oa.ndim))) - return array - -cdef object vec_long_discd_array(irk_state *state, irk_discd_long_vec func, object size, ndarray oa, - object lock): - cdef long *array_data - cdef double *oa_data - cdef ndarray array "arrayObject" - cdef npy_intp length, res_size - cdef npy_intp i, imax, n - cdef broadcast multi - cdef flatiter itera - - if size is None: - array = PyArray_SimpleNew(PyArray_NDIM(oa), - PyArray_DIMS(oa), NPY_LONG) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - itera = PyArray_IterNew(oa) - with lock, nogil: - for i from 0 <= i < length: - func(state, 1, array_data + i, ((itera.dataptr))[0]) - PyArray_ITER_NEXT(itera) - else: - array = np.empty(size, int) - array_data = PyArray_DATA(array) - multi = PyArray_MultiIterNew(2, array, oa) - res_size = PyArray_SIZE(array) - if (multi.size != res_size): - raise ValueError("size is not compatible with inputs") - - imax = oa.size - n = res_size // imax - with lock, nogil: - for i from 0 <= i < imax: - oa_data = PyArray_MultiIter_DATA(multi, 1) - func(state, n, array_data + n*i, oa_data[0]) - PyArray_MultiIter_NEXTi(multi, 1) - array.shape = (oa.shape + array.shape)[:array.ndim] - array = array.transpose(tuple(range(oa.ndim, array.ndim)) + tuple(range(0, oa.ndim))) - return array - -cdef object vec_Poisson_array(irk_state *state, irk_discdptr_vec func1, irk_discd_vec func2, object size, ndarray olambda, - object lock): - cdef int *array_data - cdef double *oa_data - cdef ndarray array "arrayObject" - cdef npy_intp length, res_size - cdef npy_intp i, imax, n - cdef broadcast multi - cdef flatiter itera - - if size is None: - array = PyArray_SimpleNew(PyArray_NDIM(olambda), - PyArray_DIMS(olambda), NPY_INT) - length = PyArray_SIZE(array) - array_data = PyArray_DATA(array) - oa_data = PyArray_DATA(olambda) - with lock, nogil: - func1(state, length, array_data, oa_data) - else: - array = np.empty(size, np.int32) - array_data = PyArray_DATA(array) - multi = PyArray_MultiIterNew(2, array, olambda) - res_size = PyArray_SIZE(array) - if (multi.size != res_size): - raise ValueError("size is not compatible with inputs") - - imax = olambda.size - n = res_size // imax - if imax < n: - with lock, nogil: - for i from 0 <= i < imax: - oa_data = PyArray_MultiIter_DATA(multi, 1) - func2(state, n, array_data + n*i, oa_data[0]) - PyArray_MultiIter_NEXTi(multi, 1) - array.shape = (olambda.shape + array.shape)[:array.ndim] - array = array.transpose(tuple(range(olambda.ndim, array.ndim)) + tuple(range(0, olambda.ndim))) - else: - oa_data = PyArray_DATA(olambda); - with lock, nogil: - for i from 0 <= i < n: - func1(state, imax, array_data + imax*i, oa_data) - - return array - - -cdef double kahan_sum(double *darr, npy_intp n) nogil: - cdef double c, y, t, sum - cdef npy_intp i - sum = darr[0] - c = 0.0 - for i from 1 <= i < n: - y = darr[i] - c - t = sum + y - c = (t-sum) - y - sum = t - return sum - -# computes dim*(dim + 1)/2 -- number of elements in lower-triangular part of a square matrix of shape (dim, dim) -cdef inline int packed_cholesky_size(int dim): - cdef int dh, lsb - - dh = (dim >> 1) - lsb = (dim & 1) - return (lsb + dh) * (dim + (1 - lsb)) - -def _shape_from_size(size, d): - if size is None: - shape = (d,) - else: - try: - shape = (operator.index(size), d) - except TypeError: - shape = tuple(size) + (d,) - return shape - -# sampling methods enum -ICDF = 0 -BOXMULLER = 1 -BOXMULLER2 = 2 -POISNORM = 3 -PTPE = 4 - -_method_alias_dict_gaussian = {'ICDF': ICDF, 'Inversion': ICDF, - 'BoxMuller': BOXMULLER, 'Box-Muller': BOXMULLER, - 'BoxMuller2': BOXMULLER2, 'Box-Muller2': BOXMULLER2} - -_method_alias_dict_gaussian_short = {'ICDF': ICDF, 'Inversion': ICDF, - 'BoxMuller': BOXMULLER, 'Box-Muller': BOXMULLER} - -_method_alias_dict_poisson = {'PTPE' : PTPE, 'Poisson-Normal': POISNORM, 'POISNORM' : POISNORM} - -def choose_method(method, mlist, alias_dict = None): - if (method not in mlist): - if (alias_dict is None) or (not isinstance(alias_dict, dict)): - # issue warning - return mlist[0] - else: - if method not in alias_dict.keys(): - return mlist[0] - else: - return alias_dict[method] - else: - return method - -_brng_dict = { - 'MT19937' : MT19937, - 'SFMT19937' : SFMT19937, - 'WH' : WH, - 'MT2203': MT2203, - 'MCG31' : MCG31, - 'R250' : R250, - 'MRG32K3A' : MRG32K3A, - 'MCG59' : MCG59, - 'PHILOX4X32X10' : PHILOX4X32X10, - 'NONDETERM' : NONDETERM, - 'NONDETERMINISTIC' : NONDETERM, - 'NON_DETERMINISTIC' : NONDETERM, - 'ARS5' : ARS5 -} - -_brng_dict_stream_max = { - MT19937: 1, - SFMT19937: 1, - WH: 273, - MT2203: 6024, - MCG31: 1, - R250: 1, - MRG32K3A: 1, - MCG59: 1, - PHILOX4X32X10: 1, - NONDETERM: 1, - ARS5: 1, -} - -cdef irk_brng_t _default_fallback_brng_token_(brng): - cdef irk_brng_t brng_token - warnings.warn(("The basic random generator specification {given} is not recognized. " - "\"MT19937\" will be used instead").format(given=brng), - UserWarning) - brng_token = MT19937 - return brng_token - -cdef irk_brng_t _parse_brng_token_(brng): - cdef irk_brng_t brng_token - - if isinstance(brng, str): - tmp = _brng_dict.get(brng.upper(), None) - if tmp is None: - brng_token = _default_fallback_brng_token_(brng) - else: - brng_token = tmp - elif isinstance(brng, int): - brng_token = operator.index(brng) - else: - brng_token = _default_fallback_brng_token_(brng) - - return brng_token - -def _parse_brng_argument(brng): - cdef irk_brng_t brng_token - cdef unsigned int stream_id = 0 - - if isinstance(brng, (list, tuple)) and len(brng) == 2: - bt, s = brng; - brng_token = _parse_brng_token_(bt) - smax = _brng_dict_stream_max[brng_token] - if isinstance(s, int): - s = s % smax - if (s != brng[1]): - warnings.warn(("The generator index {actual} is not between 0 and {max}, " - "index {choice} will be used.").format(actual=brng[-1], max=smax-1, choice=s), - UserWarning) - stream_id = s - else: - brng_token = _parse_brng_token_(brng) - - return (brng_token, stream_id) - -def _brng_id_to_name(int brng_id): - cdef object nm - cdef object brng_name = None - for nm in _brng_dict: - if _brng_dict[nm] == brng_id: - brng_name = nm - - return brng_name - - -cdef class RandomState: - """ - RandomState(seed=None, brng='MT19937') - - Container for the Intel(R) MKL-powered (pseudo-)random number generators. - - `RandomState` exposes a number of methods for generating random numbers - drawn from a variety of probability distributions. In addition to the - distribution-specific arguments, each method takes a keyword argument - `size` that defaults to ``None``. If `size` is ``None``, then a single - value is generated and returned. If `size` is an integer, then a 1-D - array filled with generated values is returned. If `size` is a tuple, - then an array with that shape is filled and returned. - - *Compatibility Notice* - This version of numpy.random has been rewritten to use MKL's vector - statistics functionality, that provides efficient implementation of - the MT19937 and many other basic psuedo-random number generation - algorithms as well as efficient sampling from other common statistical - distributions. As a consequence this version is NOT seed-compatible with - the original numpy.random. - - Parameters - ---------- - seed : {None, int, array_like}, optional - Random seed initializing the pseudo-random number generator. - Can be an integer, an array (or other sequence) of integers of - any length, or ``None`` (the default). - If `seed` is ``None``, then `RandomState` will try to read data from - ``/dev/urandom`` (or the Windows analogue) if available or seed from - the clock otherwise. - brng : {'MT19937', 'SFMT19937', 'MT2203', 'R250', 'WH', 'MCG31', 'MCG59', - 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', 'ARS5'}, optional - Basic pseudo-random number generation algorithms, provided by - Intel MKL. The default choice is 'MT19937' - the Mersenne Twister. - - Notes - ----- - The Python stdlib module "random" also contains a Mersenne Twister - pseudo-random number generator with a number of methods that are similar - to the ones available in `RandomState`. `RandomState`, besides being - NumPy-aware, has the advantage that it provides a much larger number - of probability distributions to choose from. - - References - ----- - MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html - - """ - cdef irk_state *internal_state - cdef object lock - poisson_lam_max = np.iinfo('l').max - np.sqrt(np.iinfo('l').max)*10 - - def __init__(self, seed=None, brng='MT19937'): - self.internal_state = PyMem_Malloc(sizeof(irk_state)) - memset(self.internal_state, 0, sizeof(irk_state)) - - self.lock = Lock() - self.seed(seed, brng) - - def __dealloc__(self): - if self.internal_state != NULL: - irk_dealloc_stream(self.internal_state) - PyMem_Free(self.internal_state) - self.internal_state = NULL - - def seed(self, seed=None, brng=None): - """ - seed(seed=None, brng=None) - - Seed the generator. - - This method is called when `RandomState` is initialized. It can be - called again to re-seed the generator. For details, see `RandomState`. - - Parameters - ---------- - seed : int or array_like, optional - Seed for `RandomState`. - Must be convertible to 32 bit unsigned integers. - brng : {'MT19937', 'SFMT19937', 'MT2203', 'R250', 'WH', 'MCG31', - 'MCG59', 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', - 'ARS5', None}, optional - Basic pseudo-random number generation algorithms, provided by - Intel MKL. Use `brng==None` to keep the `brng` specified to construct - the class instance. - - See Also - -------- - RandomState - - References - -------- - MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html - - """ - cdef irk_error errcode - cdef irk_brng_t brng_token = MT19937 - cdef unsigned int stream_id - cdef ndarray obj "arrayObject_obj" - - if (brng): - brng_token, stream_id = _parse_brng_argument(brng); - else: - brng_token = irk_get_brng_and_stream_mkl(self.internal_state, &stream_id) - try: - if seed is None: - with self.lock: - errcode = irk_randomseed_mkl(self.internal_state, brng_token, stream_id) - else: - idx = operator.index(seed) - if idx > int(2**32 - 1) or idx < 0: - raise ValueError("Seed must be between 0 and 4294967295") - with self.lock: - irk_seed_mkl(self.internal_state, idx, brng_token, stream_id) - except TypeError: - obj = np.asarray(seed) - if not obj.dtype is dtype('uint64'): - obj = obj.astype(np.int64, casting='safe') - if ((obj > int(2**32 - 1)) | (obj < 0)).any(): - raise ValueError("Seed must be between 0 and 4294967295") - obj = obj.astype('uint32', casting='unsafe') - with self.lock: - irk_seed_mkl_array(self.internal_state, PyArray_DATA(obj), - PyArray_DIM(obj, 0), brng_token, stream_id) - - def get_state(self): - """ - get_state() - - Return a tuple representing the internal state of the generator. - - For more details, see `set_state`. - - Returns - ------- - out : tuple(str, bytes) - The returned tuple has the following items: - - 1. the string, defaulting to 'MT19937', specifying the - basic psedo-random number generation algorithm. - 2. a bytes object holding content of Intel MKL's stream for the - given BRNG. - - See Also - -------- - set_state - - Notes - ----- - `set_state` and `get_state` are not needed to work with any of the - random distributions in NumPy. If the internal state is manually altered, - the user should know exactly what he/she is doing. - - References - ----- - MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html - - """ - cdef int state_buffer_size - cdef int brng_id - cdef void *bytesPtr - - with self.lock: - state_buffer_size = irk_get_stream_size(self.internal_state) - bytestring = empty_py_bytes(state_buffer_size, &bytesPtr) - with self.lock: - brng_id = irk_get_brng_mkl(self.internal_state) - irk_get_state_mkl(self.internal_state, bytesPtr) - - brng_name = _brng_id_to_name(brng_id) - return (brng_name, bytestring) - - def set_state(self, state): - """ - set_state(state) - - Set the internal state of the generator from a tuple. - - For use if one has reason to manually (re-)set the internal state of the - chosen pseudo-random number generating algorithm. - - Parameters - ---------- - state : tuple(str, bytes) - The `state` tuple has the following items: - - 1. the string, defaulting to 'MT19937', specifying the - basic psedo-random number generation algorithm. - 2. a bytes object holding content of Intel MKL's stream for the - given BRNG. - - Returns - ------- - out : None - Returns 'None' on success. - - See Also - -------- - get_state - - Notes - ----- - `set_state` and `get_state` are not needed to work with any of the - random distributions in NumPy. If the internal state is manually altered, - the user should know exactly what he/she is doing. - - For backwards compatibility, the form (str, array of 624 uints, int) is - also accepted although in such a case keys are used to seed the generator, - and position index pos is ignored: ``state = ('MT19937', keys, pos)``. - - References - ---------- - MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html - - """ - cdef char *bytes_ptr - cdef int brng_id - cdef ndarray obj "arrayObject_obj" - - state_len = len(state) - if(state_len != 2): - if (state_len == 3 or state_len == 5): - algo_name, key, pos = state[:3] - if algo_name != 'MT19937': - raise ValueError("The legacy state input algorithm must be 'MT19937'") - try: - obj = PyArray_ContiguousFromObject(key, NPY_ULONG, 1, 1) - except TypeError: - # compatibility -- could be an older pickle - obj = PyArray_ContiguousFromObject(key, NPY_LONG, 1, 1) - self.seed(obj, brng = algo_name) - return - raise ValueError("The argument to set_state must be a list of 2 elements") - - algorithm_name = state[0] - if algorithm_name not in _brng_dict.keys(): - raise ValueError("basic number generator algorithm must be one of ['" + "',".join(_brng_dict.keys()) + "']") - - stream_buf = state[1] - if not is_bytes_object(stream_buf): - raise ValueError('state is expected to be bytes') - - bytes_ptr = py_bytes_DataPtr(stream_buf) - - with self.lock: - err = irk_set_state_mkl(self.internal_state, bytes_ptr) - if(err): - raise ValueError('The stream state buffer is corrupted') - brng_id = irk_get_brng_mkl(self.internal_state) - if (_brng_dict[algorithm_name] != brng_id): - raise ValueError('The algorithm name does not match content of the buffer') - - # Pickling support: - def __getstate__(self): - return self.get_state() - - def __setstate__(self, state): - self.set_state(state) - - def __reduce__(self): - global __RandomState_ctor - return (__RandomState_ctor, (), self.get_state()) - - def leapfrog(self, int k, int nstreams): - """ - leapfrog(k, nstreams) - - Initializes the current state generator using leap-frog method, - if supported for the basic random pseudo-random number generation - algorithm. - """ - cdef int err, brng_id - - err = irk_leapfrog_stream_mkl(self.internal_state, k, nstreams); - - if err == -1: - raise ValueError('The stream state buffer is corrupted') - elif err == 1: - with self.lock: - brng_id = irk_get_brng_mkl(self.internal_state) - raise ValueError("Leap-frog method of stream initialization is not supported for " + str(_brng_id_to_name(brng_id))) - - def skipahead(self, long long int nskips): - """ - skipahead(nskips) - - Initializes the current state generator using skip-ahead method, - if supported for the basic random pseudo-random number generation - algorithm. - """ - cdef int err, brng_id - - err = irk_skipahead_stream_mkl(self.internal_state, nskips); - - if err == -1: - raise ValueError('The stream state buffer is corrupted') - elif err == 1: - with self.lock: - brng_id = irk_get_brng_mkl(self.internal_state) - raise ValueError("Skip-ahead method of stream initialization is not supported for " + str(_brng_id_to_name(brng_id))) - - # Basic distributions: - def random_sample(self, size=None): - """ - random_sample(size=None) - - Return random floats in the half-open interval [0.0, 1.0). - - Results are from the "continuous uniform" distribution over the - stated interval. To sample :math:`Unif[a, b), b > a` multiply - the output of `random_sample` by `(b-a)` and add `a`:: - - (b - a) * random_sample() + a - - Parameters - ---------- - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - out : float or ndarray of floats - Array of random floats of shape `size` (unless ``size=None``, in which - case a single float is returned). - - Examples - -------- - >>> mkl_random.random_sample() - 0.47108547995356098 - >>> type(mkl_random.random_sample()) - - >>> mkl_random.random_sample((5,)) - array([ 0.30220482, 0.86820401, 0.1654503 , 0.11659149, 0.54323428]) - - Three-by-two array of random numbers from [-5, 0): - - >>> 5 * mkl_random.random_sample((3, 2)) - 5 - array([[-3.99149989, -0.52338984], - [-2.99091858, -0.79479508], - [-1.23204345, -1.75224494]]) - - """ - return vec_cont0_array(self.internal_state, irk_double_vec, size, self.lock) - - def tomaxint(self, size=None): - """ - tomaxint(size=None) - - Random integers between 0 and ``sys.maxint``, inclusive. - - Return a sample of uniformly distributed random integers in the interval - [0, ``sys.maxint``]. - - Parameters - ---------- - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - out : ndarray - Drawn samples, with shape `size`. - - See Also - -------- - randint : Uniform sampling over a given half-open interval of integers. - random_integers : Uniform sampling over a given closed interval of - integers. - - Examples - -------- - >>> RS = np.random_random_intel.RandomState() # need a RandomState object - >>> RS.tomaxint((2,2,2)) - array([[[1170048599, 1600360186], - [ 739731006, 1947757578]], - [[1871712945, 752307660], - [1601631370, 1479324245]]]) - >>> import sys - >>> sys.maxint - 2147483647 - >>> RS.tomaxint((2,2,2)) < sys.maxint - array([[[ True, True], - [ True, True]], - [[ True, True], - [ True, True]]], dtype=bool) - - """ - return vec_long_disc0_array(self.internal_state, irk_long_vec, size, self.lock) - - # Set up dictionary of integer types and relevant functions. - # - # The dictionary is keyed by dtype(...).name and the values - # are a tuple (low, high, function), where low and high are - # the bounds of the largest half open interval `[low, high)` - # and the function is the relevant function to call for - # that precision. - # - # The functions are all the same except for changed types in - # a few places. It would be easy to template them. - - def _choose_randint_type(self, dtype): - _randint_type = { - 'bool': (0, 2, self._rand_bool), - 'int8': (-2**7, 2**7, self._rand_int8), - 'int16': (-2**15, 2**15, self._rand_int16), - 'int32': (-2**31, 2**31, self._rand_int32), - 'int64': (-2**63, 2**63, self._rand_int64), - 'uint8': (0, 2**8, self._rand_uint8), - 'uint16': (0, 2**16, self._rand_uint16), - 'uint32': (0, 2**32, self._rand_uint32), - 'uint64': (0, 2**64, self._rand_uint64) - } - - key = np.dtype(dtype).name - if not key in _randint_type: - raise TypeError('Unsupported dtype "%s" for randint' % key) - return _randint_type[key] - - # generates typed random integer in [low, high] - def _rand_bool(self, npy_bool low, npy_bool high, size): - """ - _rand_bool(low, high, size) - - See `_rand_int32` for documentation, only the return type changes. - - """ - cdef npy_bool buf - cdef npy_bool *out - cdef ndarray array "arrayObject" - cdef npy_intp cnt - - if size is None: - irk_rand_bool_vec(self.internal_state, 1, &buf, low, high) - return np.bool_(buf) - else: - array = np.empty(size, np.bool_) - cnt = PyArray_SIZE(array) - out = PyArray_DATA(array) - with nogil: - irk_rand_bool_vec(self.internal_state, cnt, out, low, high) - return array - - - def _rand_int8(self, npy_int8 low, npy_int8 high, size): - """ - _rand_int8(low, high, size) - - See `_rand_int32` for documentation, only the return type changes. - - """ - cdef npy_int8 buf - cdef npy_int8 *out - cdef ndarray array "arrayObject" - cdef npy_intp cnt - - if size is None: - irk_rand_int8_vec(self.internal_state, 1, &buf, low, high) - return np.int8(buf) - else: - array = np.empty(size, np.int8) - cnt = PyArray_SIZE(array) - out = PyArray_DATA(array) - with nogil: - irk_rand_int8_vec(self.internal_state, cnt, out, low, high) - return array - - - def _rand_int16(self, npy_int16 low, npy_int16 high, size): - """ - _rand_int16(low, high, size) - - See `_rand_int32` for documentation, only the return type changes. - - """ - cdef npy_int16 buf - cdef npy_int16 *out - cdef ndarray array "arrayObject" - cdef npy_intp cnt - - if size is None: - irk_rand_int16_vec(self.internal_state, 1, &buf, low, high) - return np.int16(buf) - else: - array = np.empty(size, np.int16) - cnt = PyArray_SIZE(array) - out = PyArray_DATA(array) - with nogil: - irk_rand_int16_vec(self.internal_state, cnt, out, low, high) - return array - - - def _rand_int32(self, npy_int32 low, npy_int32 high, size): - """ - _rand_int32(self, low, high, size) - - Return random np.int32 integers between `low` and `high`, inclusive. - - Return random integers from the "discrete uniform" distribution in the - closed interval [`low`, `high`]. On entry the arguments are presumed - to have been validated for size and order for the np.int32 type. - - Parameters - ---------- - low : int - Lowest (signed) integer to be drawn from the distribution. - high : int - Highest (signed) integer to be drawn from the distribution. - size : int or tuple of ints - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - out : python scalar or ndarray of np.int32 - `size`-shaped array of random integers from the appropriate - distribution, or a single such random int if `size` not provided. - - """ - cdef npy_int32 buf - cdef npy_int32 *out - cdef ndarray array "arrayObject" - cdef npy_intp cnt - - if size is None: - irk_rand_int32_vec(self.internal_state, 1, &buf, low, high) - return np.int32(buf) - else: - array = np.empty(size, np.int32) - cnt = PyArray_SIZE(array) - out = PyArray_DATA(array) - with nogil: - irk_rand_int32_vec(self.internal_state, cnt, out, low, high) - return array - - - def _rand_int64(self, npy_int64 low, npy_int64 high, size): - """ - _rand_int64(low, high, size) - - See `_rand_int32` for documentation, only the return type changes. - - """ - cdef npy_int64 buf - cdef npy_int64 *out - cdef ndarray array "arrayObject" - cdef npy_intp cnt - - if size is None: - irk_rand_int64_vec(self.internal_state, 1, &buf, low, high) - return np.int64(buf) - else: - array = np.empty(size, np.int64) - cnt = PyArray_SIZE(array) - out = PyArray_DATA(array) - with nogil: - irk_rand_int64_vec(self.internal_state, cnt, out, low, high) - return array - - def _rand_uint8(self, npy_uint8 low, npy_uint8 high, size): - """ - _rand_uint8(low, high, size) - - See `_rand_int32` for documentation, only the return type changes. - - """ - cdef npy_uint8 buf - cdef npy_uint8 *out - cdef ndarray array "arrayObject" - cdef npy_intp cnt - - if size is None: - irk_rand_uint8_vec(self.internal_state, 1, &buf, low, high) - return np.uint8(buf) - else: - array = np.empty(size, np.uint8) - cnt = PyArray_SIZE(array) - out = PyArray_DATA(array) - with nogil: - irk_rand_uint8_vec(self.internal_state, cnt, out, low, high) - return array - - - def _rand_uint16(self, npy_uint16 low, npy_uint16 high, size): - """ - _rand_uint16(low, high, size) - - See `_rand_int32` for documentation, only the return type changes. - - """ - cdef npy_uint16 off, rng, buf - cdef npy_uint16 *out - cdef ndarray array "arrayObject" - cdef npy_intp cnt - - if size is None: - irk_rand_uint16_vec(self.internal_state, 1, &buf, low, high) - return np.uint16(buf) - else: - array = np.empty(size, np.uint16) - cnt = PyArray_SIZE(array) - out = PyArray_DATA(array) - with nogil: - irk_rand_uint16_vec(self.internal_state, cnt, out, low, high) - return array - - - def _rand_uint32(self, npy_uint32 low, npy_uint32 high, size): - """ - _rand_uint32(self, low, high, size) - - See `_rand_int32` for documentation, only the return type changes. - - """ - cdef npy_uint32 buf - cdef npy_uint32 *out - cdef ndarray array "arrayObject" - cdef npy_intp cnt - - if size is None: - irk_rand_uint32_vec(self.internal_state, 1, &buf, low, high) - return np.uint32(buf) - else: - array = np.empty(size, np.uint32) - cnt = PyArray_SIZE(array) - out = PyArray_DATA(array) - with nogil: - irk_rand_uint32_vec(self.internal_state, cnt, out, low, high) - return array - - - def _rand_uint64(self, npy_uint64 low, npy_uint64 high, size): - """ - _rand_uint64(low, high, size) - - See `_rand_int32` for documentation, only the return type changes. - - """ - cdef npy_uint64 buf - cdef npy_uint64 *out - cdef ndarray array "arrayObject" - cdef npy_intp cnt - - if size is None: - irk_rand_uint64_vec(self.internal_state, 1, &buf, low, high) - return np.uint64(buf) - else: - array = np.empty(size, np.uint64) - cnt = PyArray_SIZE(array) - out = PyArray_DATA(array) - with nogil: - irk_rand_uint64_vec(self.internal_state, cnt, out, low, high) - return array - - - def randint(self, low, high=None, size=None, dtype=int): - """ - randint(low, high=None, size=None, dtype=int) - - Return random integers from `low` (inclusive) to `high` (exclusive). - - Return random integers from the "discrete uniform" distribution of - the specified dtype in the "half-open" interval [`low`, `high`). If - `high` is None (the default), then results are from [0, `low`). - - Parameters - ---------- - low : int - Lowest (signed) integer to be drawn from the distribution (unless - ``high=None``, in which case this parameter is the *highest* such - integer). - high : int, optional - If provided, one above the largest (signed) integer to be drawn - from the distribution (see above for behavior if ``high=None``). - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - dtype : dtype, optional - Desired dtype of the result. All dtypes are determined by their - name, i.e., 'int64', 'int', etc, so byteorder is not available - and a specific precision may have different C types depending - on the platform. The default value is 'np.int'. - - .. versionadded:: 1.11.0 - - Returns - ------- - out : int or ndarray of ints - `size`-shaped array of random integers from the appropriate - distribution, or a single such random int if `size` not provided. - - See Also - -------- - random.random_integers : similar to `randint`, only for the closed - interval [`low`, `high`], and 1 is the lowest value if `high` is - omitted. In particular, this other one is the one to use to generate - uniformly distributed discrete non-integers. - - Examples - -------- - >>> mkl_random.randint(2, size=10) - array([1, 0, 0, 0, 1, 1, 0, 0, 1, 0]) - >>> mkl_random.randint(1, size=10) - array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0]) - - Generate a 2 x 4 array of ints between 0 and 4, inclusive: - - >>> mkl_random.randint(5, size=(2, 4)) - array([[4, 0, 2, 1], - [3, 2, 2, 0]]) - - """ - if high is None: - high = low - low = 0 - - lowbnd, highbnd, randfunc = self._choose_randint_type(dtype) - - if low < lowbnd: - raise ValueError("low is out of bounds for %s" % (np.dtype(dtype).name,)) - if high > highbnd: - raise ValueError("high is out of bounds for %s" % (np.dtype(dtype).name,)) - if low >= high: - raise ValueError("low >= high") - - with self.lock: - ret = randfunc(low, high - 1, size) - - if size is None: - if dtype in (bool, int, np.compat.long): - return dtype(ret) - - return ret - - - def randint_untyped(self, low, high=None, size=None): - """ - randint_untyped(low, high=None, size=None, dtype=int) - - Return random integers from `low` (inclusive) to `high` (exclusive). - - Return random integers from the "discrete uniform" distribution of - the specified dtype in the "half-open" interval [`low`, `high`). If - `high` is None (the default), then results are from [0, `low`). - - Parameters - ---------- - low : int - Lowest (signed) integer to be drawn from the distribution (unless - ``high=None``, in which case this parameter is the *highest* such - integer). - high : int, optional - If provided, one above the largest (signed) integer to be drawn - from the distribution (see above for behavior if ``high=None``). - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - out : int or ndarray of ints - `size`-shaped array of random integers from the appropriate - distribution, or a single such random int if `size` not provided. - - See Also - -------- - random.random_integers : similar to `randint`, only for the closed - interval [`low`, `high`], and 1 is the lowest value if `high` is - omitted. In particular, this other one is the one to use to generate - uniformly distributed discrete non-integers. - - Examples - -------- - >>> mkl_random.randint(2, size=10) - array([1, 0, 0, 0, 1, 1, 0, 0, 1, 0]) - >>> mkl_random.randint(1, size=10) - array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0]) - - Generate a 2 x 4 array of ints between 0 and 4, inclusive: - - >>> mkl_random.randint(5, size=(2, 4)) - array([[4, 0, 2, 1], - [3, 2, 2, 0]]) - - """ - cdef long lo, hi - cdef long *array_long_data - cdef int * array_int_data - cdef ndarray array "arrayObject" - cdef npy_intp length - cdef int rv_int - cdef long rv_long - - if high is None: - lo = 0 - hi = low - else: - lo = low - hi = high - - if lo >= hi : - raise ValueError("low >= high") - - if (( lo) == lo) and ((hi) == hi): - if size is None: - irk_discrete_uniform_vec(self.internal_state, 1, &rv_int, lo, hi) - return rv_int - else: - array = np.empty(size, np.int32) - length = PyArray_SIZE(array) - array_int_data = PyArray_DATA(array) - with self.lock, nogil: - irk_discrete_uniform_vec(self.internal_state, length, array_int_data, lo, hi) - return array - else: - if size is None: - irk_discrete_uniform_long_vec(self.internal_state, 1, &rv_long, lo, hi) - return rv_long - else: - array = np.empty(size, int) - length = PyArray_SIZE(array) - array_long_data = PyArray_DATA(array) - with self.lock, nogil: - irk_discrete_uniform_long_vec(self.internal_state, length, array_long_data, lo, hi) - return array - - def bytes(self, npy_intp length): - """ - bytes(length) - - Return random bytes. - - Parameters - ---------- - length : int - Number of random bytes. - - Returns - ------- - out : str - String of length `length`. - - Examples - -------- - >>> mkl_random.bytes(10) - ' eh\\x85\\x022SZ\\xbf\\xa4' #random - - """ - cdef void *bytes - bytestring = empty_py_bytes(length, &bytes) - with self.lock, nogil: - irk_fill(bytes, length, self.internal_state) - return bytestring - - - def choice(self, a, size=None, replace=True, p=None): - """ - choice(a, size=None, replace=True, p=None) - - Generates a random sample from a given 1-D array - - .. versionadded:: 1.7.0 - - Parameters - ----------- - a : 1-D array-like or int - If an ndarray, a random sample is generated from its elements. - If an int, the random sample is generated as if a was np.arange(n) - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - replace : boolean, optional - Whether the sample is with or without replacement - p : 1-D array-like, optional - The probabilities associated with each entry in a. - If not given the sample assumes a uniform distribution over all - entries in a. - - Returns - -------- - samples : 1-D ndarray, shape (size,) - The generated random samples - - Raises - ------- - ValueError - If a is an int and less than zero, if a or p are not 1-dimensional, - if a is an array-like of size 0, if p is not a vector of - probabilities, if a and p have different lengths, or if - replace=False and the sample size is greater than the population - size - - See Also - --------- - randint, shuffle, permutation - - Examples - --------- - Generate a uniform random sample from np.arange(5) of size 3: - - >>> mkl_random.choice(5, 3) - array([0, 3, 4]) - >>> #This is equivalent to mkl_random.randint(0,5,3) - - Generate a non-uniform random sample from np.arange(5) of size 3: - - >>> mkl_random.choice(5, 3, p=[0.1, 0, 0.3, 0.6, 0]) - array([3, 3, 0]) - - Generate a uniform random sample from np.arange(5) of size 3 without - replacement: - - >>> mkl_random.choice(5, 3, replace=False) - array([3,1,0]) - >>> #This is equivalent to mkl_random.permutation(np.arange(5))[:3] - - Generate a non-uniform random sample from np.arange(5) of size - 3 without replacement: - - >>> mkl_random.choice(5, 3, replace=False, p=[0.1, 0, 0.3, 0.6, 0]) - array([2, 3, 0]) - - Any of the above can be repeated with an arbitrary array-like - instead of just integers. For instance: - - >>> aa_milne_arr = ['pooh', 'rabbit', 'piglet', 'Christopher'] - >>> mkl_random.choice(aa_milne_arr, 5, p=[0.5, 0.1, 0.1, 0.3]) - array(['pooh', 'pooh', 'pooh', 'Christopher', 'piglet'], - dtype='|S11') - - """ - - # Format and Verify input - a = np.array(a, copy=False) - if a.ndim == 0: - try: - # __index__ must return an integer by python rules. - pop_size = operator.index(a.item()) - except TypeError: - raise ValueError("a must be 1-dimensional or an integer") - if pop_size <= 0: - raise ValueError("a must be greater than 0") - elif a.ndim != 1: - raise ValueError("a must be 1-dimensional") - else: - pop_size = a.shape[0] - if pop_size is 0: - raise ValueError("a must be non-empty") - - if p is not None: - d = len(p) - - atol = np.sqrt(np.finfo(np.float64).eps) - if isinstance(p, np.ndarray): - if np.issubdtype(p.dtype, np.floating): - atol = max(atol, np.sqrt(np.finfo(p.dtype).eps)) - - p = PyArray_ContiguousFromObject(p, NPY_DOUBLE, 1, 1) - pix = PyArray_DATA(p) - - if p.ndim != 1: - raise ValueError("p must be 1-dimensional") - if p.size != pop_size: - raise ValueError("a and p must have same size") - if np.logical_or.reduce(p < 0): - raise ValueError("probabilities are not non-negative") - if abs(kahan_sum(pix, d) - 1.) > atol: - raise ValueError("probabilities do not sum to 1") - - shape = size - if shape is not None: - size = np.prod(shape, dtype=np.intp) - else: - size = 1 - - # Actual sampling - if replace: - if p is not None: - cdf = p.cumsum() - cdf /= cdf[-1] - uniform_samples = self.random_sample(shape) - idx = cdf.searchsorted(uniform_samples, side='right') - idx = np.array(idx, copy=False) # searchsorted returns a scalar - else: - idx = self.randint(0, pop_size, size=shape) - else: - if size > pop_size: - raise ValueError("Cannot take a larger sample than " - "population when 'replace=False'") - - if p is not None: - if np.count_nonzero(p > 0) < size: - raise ValueError("Fewer non-zero entries in p than size") - n_uniq = 0 - p = p.copy() - found = np.zeros(tuple() if shape is None else shape, dtype=np.int64) - flat_found = found.ravel() - while n_uniq < size: - x = self.rand(size - n_uniq) - if n_uniq > 0: - p[flat_found[0:n_uniq]] = 0 - cdf = np.cumsum(p) - cdf /= cdf[-1] - new = cdf.searchsorted(x, side='right') - _, unique_indices = np.unique(new, return_index=True) - unique_indices.sort() - new = new.take(unique_indices) - flat_found[n_uniq:n_uniq + new.size] = new - n_uniq += new.size - idx = found - else: - idx = self.permutation(pop_size)[:size] - if shape is not None: - idx.shape = shape - - if shape is None and isinstance(idx, np.ndarray): - # In most cases a scalar will have been made an array - idx = idx.item(0) - - #Use samples as indices for a if a is array-like - if a.ndim == 0: - return idx - - if shape is not None and idx.ndim == 0: - # If size == () then the user requested a 0-d array as opposed to - # a scalar object when size is None. However a[idx] is always a - # scalar and not an array. So this makes sure the result is an - # array, taking into account that np.array(item) may not work - # for object arrays. - res = np.empty((), dtype=a.dtype) - res[()] = a[idx] - return res - - return a[idx] - - - def uniform(self, low=0.0, high=1.0, size=None): - """ - uniform(low=0.0, high=1.0, size=None) - - Draw samples from a uniform distribution. - - Samples are uniformly distributed over the half-open interval - ``[low, high)`` (includes low, but excludes high). In other words, - any value within the given interval is equally likely to be drawn - by `uniform`. - - Parameters - ---------- - low : float, optional - Lower boundary of the output interval. All values generated will be - greater than or equal to low. The default value is 0. - high : float - Upper boundary of the output interval. All values generated will be - less than high. The default value is 1.0. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - out : ndarray - Drawn samples, with shape `size`. - - See Also - -------- - randint : Discrete uniform distribution, yielding integers. - random_integers : Discrete uniform distribution over the closed - interval ``[low, high]``. - random_sample : Floats uniformly distributed over ``[0, 1)``. - random : Alias for `random_sample`. - rand : Convenience function that accepts dimensions as input, e.g., - ``rand(2,2)`` would generate a 2-by-2 array of floats, - uniformly distributed over ``[0, 1)``. - - Notes - ----- - The probability density function of the uniform distribution is - - .. math:: p(x) = \\frac{1}{b - a} - - anywhere within the interval ``[a, b)``, and zero elsewhere. - - Examples - -------- - Draw samples from the distribution: - - >>> s = mkl_random.uniform(-1,0,1000) - - All values are within the given interval: - - >>> np.all(s >= -1) - True - >>> np.all(s < 0) - True - - Display the histogram of the samples, along with the - probability density function: - - >>> import matplotlib.pyplot as plt - >>> count, bins, ignored = plt.hist(s, 15, normed=True) - >>> plt.plot(bins, np.ones_like(bins), linewidth=2, color='r') - >>> plt.show() - - """ - cdef ndarray olow, ohigh - cdef double flow, fhigh - cdef object temp - - flow = PyFloat_AsDouble(low) - fhigh = PyFloat_AsDouble(high) - if not npy_isfinite(flow) or not npy_isfinite(fhigh): - raise OverflowError('Range exceeds valid bounds') - if flow >= fhigh: - raise ValueError("low >= high") - - if not PyErr_Occurred(): - return vec_cont2_array_sc(self.internal_state, irk_uniform_vec, size, flow, - fhigh, self.lock) - - PyErr_Clear() - olow = PyArray_FROM_OTF(low, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - ohigh = PyArray_FROM_OTF(high, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - - if not np.all(np.isfinite(olow)) or not np.all(np.isfinite(ohigh)): - raise OverflowError('Range exceeds valid bounds') - - if np.any(olow >= ohigh): - raise ValueError("low >= high") - - return vec_cont2_array(self.internal_state, irk_uniform_vec, size, olow, ohigh, - self.lock) - - def rand(self, *args): - """ - rand(d0, d1, ..., dn) - - Random values in a given shape. - - Create an array of the given shape and propagate it with - random samples from a uniform distribution - over ``[0, 1)``. - - Parameters - ---------- - d0, d1, ..., dn : int, optional - The dimensions of the returned array, should all be positive. - If no argument is given a single Python float is returned. - - Returns - ------- - out : ndarray, shape ``(d0, d1, ..., dn)`` - Random values. - - See Also - -------- - random - - Notes - ----- - This is a convenience function. If you want an interface that - takes a shape-tuple as the first argument, refer to - mkl_random.random_sample . - - Examples - -------- - >>> mkl_random.rand(3,2) - array([[ 0.14022471, 0.96360618], #random - [ 0.37601032, 0.25528411], #random - [ 0.49313049, 0.94909878]]) #random - - """ - if len(args) == 0: - return self.random_sample() - else: - return self.random_sample(size=args) - - def randn(self, *args): - """ - randn(d0, d1, ..., dn) - - Return a sample (or samples) from the "standard normal" distribution. - - If positive, int_like or int-convertible arguments are provided, - `randn` generates an array of shape ``(d0, d1, ..., dn)``, filled - with random floats sampled from a univariate "normal" (Gaussian) - distribution of mean 0 and variance 1 (if any of the :math:`d_i` are - floats, they are first converted to integers by truncation). A single - float randomly sampled from the distribution is returned if no - argument is provided. - - This is a convenience function. If you want an interface that takes a - tuple as the first argument, use `numpy.random.standard_normal` instead. - - Parameters - ---------- - d0, d1, ..., dn : int, optional - The dimensions of the returned array, should be all positive. - If no argument is given a single Python float is returned. - - Returns - ------- - Z : ndarray or float - A ``(d0, d1, ..., dn)``-shaped array of floating-point samples from - the standard normal distribution, or a single such float if - no parameters were supplied. - - See Also - -------- - random.standard_normal : Similar, but takes a tuple as its argument. - - Notes - ----- - For random samples from :math:`N(\\mu, \\sigma^2)`, use: - - ``sigma * mkl_random.randn(...) + mu`` - - Examples - -------- - >>> mkl_random.randn() - 2.1923875335537315 #random - - Two-by-four array of samples from N(3, 6.25): - - >>> 2.5 * mkl_random.randn(2, 4) + 3 - array([[-4.49401501, 4.00950034, -1.81814867, 7.29718677], #random - [ 0.39924804, 4.68456316, 4.99394529, 4.84057254]]) #random - - """ - if len(args) == 0: - return self.standard_normal() - else: - return self.standard_normal(args) - - - def random_integers(self, low, high=None, size=None): - """ - random_integers(low, high=None, size=None) - - Random integers of type np.int between `low` and `high`, inclusive. - - Return random integers of type np.int from the "discrete uniform" - distribution in the closed interval [`low`, `high`]. If `high` is - None (the default), then results are from [1, `low`]. The np.int - type translates to the C long type used by Python 2 for "short" - integers and its precision is platform dependent. - - This function has been deprecated. Use randint instead. - - .. deprecated:: 1.11.0 - - Parameters - ---------- - low : int - Lowest (signed) integer to be drawn from the distribution (unless - ``high=None``, in which case this parameter is the *highest* such - integer). - high : int, optional - If provided, the largest (signed) integer to be drawn from the - distribution (see above for behavior if ``high=None``). - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - out : int or ndarray of ints - `size`-shaped array of random integers from the appropriate - distribution, or a single such random int if `size` not provided. - - See Also - -------- - random.randint : Similar to `random_integers`, only for the half-open - interval [`low`, `high`), and 0 is the lowest value if `high` is - omitted. - - Notes - ----- - To sample from N evenly spaced floating-point numbers between a and b, - use:: - - a + (b - a) * (mkl_random.random_integers(N) - 1) / (N - 1.) - - Examples - -------- - >>> mkl_random.random_integers(5) - 4 - >>> type(mkl_random.random_integers(5)) - - >>> mkl_random.random_integers(5, size=(3.,2.)) - array([[5, 4], - [3, 3], - [4, 5]]) - - Choose five random numbers from the set of five evenly-spaced - numbers between 0 and 2.5, inclusive (*i.e.*, from the set - :math:`{0, 5/8, 10/8, 15/8, 20/8}`): - - >>> 2.5 * (mkl_random.random_integers(5, size=(5,)) - 1) / 4. - array([ 0.625, 1.25 , 0.625, 0.625, 2.5 ]) - - Roll two six sided dice 1000 times and sum the results: - - >>> d1 = mkl_random.random_integers(1, 6, 1000) - >>> d2 = mkl_random.random_integers(1, 6, 1000) - >>> dsums = d1 + d2 - - Display results as a histogram: - - >>> import matplotlib.pyplot as plt - >>> count, bins, ignored = plt.hist(dsums, 11, normed=True) - >>> plt.show() - - """ - if high is None: - warnings.warn(("This function is deprecated. Please call " - "randint(1, {low} + 1) instead".format(low=low)), - DeprecationWarning) - high = low - low = 1 - - else: - warnings.warn(("This function is deprecated. Please call " - "randint({low}, {high} + 1) instead".format( - low=low, high=high)), DeprecationWarning) - - return self.randint(low, high + 1, size=size, dtype='l') - - # Complicated, continuous distributions: - def standard_normal(self, size=None, method=ICDF): - """ - standard_normal(size=None, method='ICDF') - - Draw samples from a standard Normal distribution (mean=0, stdev=1). - - Parameters - ---------- - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - method : 'ICDF, 'BoxMuller', 'BoxMuller2', optional - Sampling method used by Intel MKL. Can also be specified using - tokens mkl_random.ICDF, mkl_random.BOXMULLER, mkl_random.BOXMULLER2 - - Returns - ------- - out : float or ndarray - Drawn samples. - - Examples - -------- - >>> s = mkl_random.standard_normal(8000) - >>> s - array([ 0.6888893 , 0.78096262, -0.89086505, ..., 0.49876311, #random - -0.38672696, -0.4685006 ]) #random - >>> s.shape - (8000,) - >>> s = mkl_random.standard_normal(size=(3, 4, 2)) - >>> s.shape - (3, 4, 2) - - """ - method = choose_method(method, [ICDF, BOXMULLER, BOXMULLER2], _method_alias_dict_gaussian) - if method is ICDF: - return vec_cont0_array(self.internal_state, irk_standard_normal_vec_ICDF, size, self.lock) - elif method is BOXMULLER2: - return vec_cont0_array(self.internal_state, irk_standard_normal_vec_BM2, size, self.lock) - else: - return vec_cont0_array(self.internal_state, irk_standard_normal_vec_BM1, size, self.lock); - - def normal(self, loc=0.0, scale=1.0, size=None, method=ICDF): - """ - normal(loc=0.0, scale=1.0, size=None, method='ICDF') - - Draw random samples from a normal (Gaussian) distribution. - - The probability density function of the normal distribution, first - derived by De Moivre and 200 years later by both Gauss and Laplace - independently [2]_, is often called the bell curve because of - its characteristic shape (see the example below). - - The normal distributions occurs often in nature. For example, it - describes the commonly occurring distribution of samples influenced - by a large number of tiny, random disturbances, each with its own - unique distribution [2]_. - - Parameters - ---------- - loc : float - Mean ("centre") of the distribution. - scale : float - Standard deviation (spread or "width") of the distribution. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - method : 'ICDF, 'BoxMuller', 'BoxMuller2', optional - Sampling method used by Intel MKL. Can also be specified using - tokens mkl_random.ICDF, mkl_random.BOXMULLER, mkl_random.BOXMULLER2 - - See Also - -------- - scipy.stats.distributions.norm : probability density function, - distribution or cumulative density function, etc. - - Notes - ----- - The probability density for the Gaussian distribution is - - .. math:: p(x) = \\frac{1}{\\sqrt{ 2 \\pi \\sigma^2 }} - e^{ - \\frac{ (x - \\mu)^2 } {2 \\sigma^2} }, - - where :math:`\\mu` is the mean and :math:`\\sigma` the standard - deviation. The square of the standard deviation, :math:`\\sigma^2`, - is called the variance. - - The function has its peak at the mean, and its "spread" increases with - the standard deviation (the function reaches 0.607 times its maximum at - :math:`x + \\sigma` and :math:`x - \\sigma` [2]_). This implies that - `numpy.random.normal` is more likely to return samples lying close to - the mean, rather than those far away. - - References - ---------- - .. [1] Wikipedia, "Normal distribution", - http://en.wikipedia.org/wiki/Normal_distribution - .. [2] P. R. Peebles Jr., "Central Limit Theorem" in "Probability, - Random Variables and Random Signal Principles", 4th ed., 2001, - pp. 51, 51, 125. - - Examples - -------- - Draw samples from the distribution: - - >>> mu, sigma = 0, 0.1 # mean and standard deviation - >>> s = mkl_random.normal(mu, sigma, 1000) - - Verify the mean and the variance: - - >>> abs(mu - np.mean(s)) < 0.01 - True - - >>> abs(sigma - np.std(s, ddof=1)) < 0.01 - True - - Display the histogram of the samples, along with - the probability density function: - - >>> import matplotlib.pyplot as plt - >>> count, bins, ignored = plt.hist(s, 30, normed=True) - >>> plt.plot(bins, 1/(sigma * np.sqrt(2 * np.pi)) * - ... np.exp( - (bins - mu)**2 / (2 * sigma**2) ), - ... linewidth=2, color='r') - >>> plt.show() - - """ - cdef ndarray oloc, oscale - cdef double floc, fscale - - floc = PyFloat_AsDouble(loc) - fscale = PyFloat_AsDouble(scale) - if not PyErr_Occurred(): - if fscale <= 0: - raise ValueError("scale <= 0") - method = choose_method(method, [ICDF, BOXMULLER, BOXMULLER2], _method_alias_dict_gaussian) - if method is ICDF: - return vec_cont2_array_sc(self.internal_state, irk_normal_vec_ICDF, size, floc, fscale, self.lock) - elif method is BOXMULLER2: - return vec_cont2_array_sc(self.internal_state, irk_normal_vec_BM2, size, floc, fscale, self.lock) - else: - return vec_cont2_array_sc(self.internal_state, irk_normal_vec_BM1, size, floc, fscale, self.lock) - - PyErr_Clear() - - oloc = PyArray_FROM_OTF(loc, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - oscale = PyArray_FROM_OTF(scale, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(oscale, 0)): - raise ValueError("scale <= 0") - method = choose_method(method, [ICDF, BOXMULLER, BOXMULLER2], _method_alias_dict_gaussian) - if method is ICDF: - return vec_cont2_array(self.internal_state, irk_normal_vec_ICDF, size, oloc, oscale, self.lock) - elif method is BOXMULLER2: - return vec_cont2_array(self.internal_state, irk_normal_vec_BM2, size, oloc, oscale, self.lock) - else: - return vec_cont2_array(self.internal_state, irk_normal_vec_BM1, size, oloc, oscale, self.lock) - - def beta(self, a, b, size=None): - """ - beta(a, b, size=None) - - Draw samples from a Beta distribution. - - The Beta distribution is a special case of the Dirichlet distribution, - and is related to the Gamma distribution. It has the probability - distribution function - - .. math:: f(x; a,b) = \\frac{1}{B(\\alpha, \\beta)} x^{\\alpha - 1} - (1 - x)^{\\beta - 1}, - - where the normalisation, B, is the beta function, - - .. math:: B(\\alpha, \\beta) = \\int_0^1 t^{\\alpha - 1} - (1 - t)^{\\beta - 1} dt. - - It is often seen in Bayesian inference and order statistics. - - Parameters - ---------- - a : float - Alpha, non-negative. - b : float - Beta, non-negative. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - out : ndarray - Array of the given shape, containing values drawn from a - Beta distribution. - - """ - cdef ndarray oa, ob - cdef double fa, fb - - fa = PyFloat_AsDouble(a) - fb = PyFloat_AsDouble(b) - if not PyErr_Occurred(): - if fa <= 0: - raise ValueError("a <= 0") - if fb <= 0: - raise ValueError("b <= 0") - return vec_cont2_array_sc(self.internal_state, irk_beta_vec, size, fa, fb, - self.lock) - - PyErr_Clear() - - oa = PyArray_FROM_OTF(a, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - ob = PyArray_FROM_OTF(b, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(oa, 0)): - raise ValueError("a <= 0") - if np.any(np.less_equal(ob, 0)): - raise ValueError("b <= 0") - return vec_cont2_array(self.internal_state, irk_beta_vec, size, oa, ob, - self.lock) - - def exponential(self, scale=1.0, size=None): - """ - exponential(scale=1.0, size=None) - - Draw samples from an exponential distribution. - - Its probability density function is - - .. math:: f(x; \\frac{1}{\\beta}) = \\frac{1}{\\beta} \\exp(-\\frac{x}{\\beta}), - - for ``x > 0`` and 0 elsewhere. :math:`\\beta` is the scale parameter, - which is the inverse of the rate parameter :math:`\\lambda = 1/\\beta`. - The rate parameter is an alternative, widely used parameterization - of the exponential distribution [3]_. - - The exponential distribution is a continuous analogue of the - geometric distribution. It describes many common situations, such as - the size of raindrops measured over many rainstorms [1]_, or the time - between page requests to Wikipedia [2]_. - - Parameters - ---------- - scale : float - The scale parameter, :math:`\\beta = 1/\\lambda`. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - References - ---------- - .. [1] Peyton Z. Peebles Jr., "Probability, Random Variables and - Random Signal Principles", 4th ed, 2001, p. 57. - .. [2] "Poisson Process", Wikipedia, - http://en.wikipedia.org/wiki/Poisson_process - .. [3] "Exponential Distribution, Wikipedia, - http://en.wikipedia.org/wiki/Exponential_distribution - - """ - cdef ndarray oscale - cdef double fscale - - fscale = PyFloat_AsDouble(scale) - if not PyErr_Occurred(): - if fscale <= 0: - raise ValueError("scale <= 0") - return vec_cont1_array_sc(self.internal_state, irk_exponential_vec, size, - fscale, self.lock) - - PyErr_Clear() - - oscale = PyArray_FROM_OTF(scale, NPY_DOUBLE, - NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(oscale, 0.0)): - raise ValueError("scale <= 0") - return vec_cont1_array(self.internal_state, irk_exponential_vec, size, oscale, - self.lock) - - def standard_exponential(self, size=None): - """ - standard_exponential(size=None) - - Draw samples from the standard exponential distribution. - - `standard_exponential` is identical to the exponential distribution - with a scale parameter of 1. - - Parameters - ---------- - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - out : float or ndarray - Drawn samples. - - Examples - -------- - Output a 3x8000 array: - - >>> n = mkl_random.standard_exponential((3, 8000)) - - """ - return vec_cont0_array(self.internal_state, irk_standard_exponential_vec, size, - self.lock) - - def standard_gamma(self, shape, size=None): - """ - standard_gamma(shape, size=None) - - Draw samples from a standard Gamma distribution. - - Samples are drawn from a Gamma distribution with specified parameters, - shape (sometimes designated "k") and scale=1. - - Parameters - ---------- - shape : float - Parameter, should be > 0. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or scalar - The drawn samples. - - See Also - -------- - scipy.stats.distributions.gamma : probability density function, - distribution or cumulative density function, etc. - - Notes - ----- - The probability density for the Gamma distribution is - - .. math:: p(x) = x^{k-1}\\frac{e^{-x/\\theta}}{\\theta^k\\Gamma(k)}, - - where :math:`k` is the shape and :math:`\\theta` the scale, - and :math:`\\Gamma` is the Gamma function. - - The Gamma distribution is often used to model the times to failure of - electronic components, and arises naturally in processes for which the - waiting times between Poisson distributed events are relevant. - - References - ---------- - .. [1] Weisstein, Eric W. "Gamma Distribution." From MathWorld--A - Wolfram Web Resource. - http://mathworld.wolfram.com/GammaDistribution.html - .. [2] Wikipedia, "Gamma-distribution", - http://en.wikipedia.org/wiki/Gamma-distribution - - Examples - -------- - Draw samples from the distribution: - - >>> shape, scale = 2., 1. # mean and width - >>> s = mkl_random.standard_gamma(shape, 1000000) - - Display the histogram of the samples, along with - the probability density function: - - >>> import matplotlib.pyplot as plt - >>> import scipy.special as sps - >>> count, bins, ignored = plt.hist(s, 50, normed=True) - >>> y = bins**(shape-1) * ((np.exp(-bins/scale))/ \\ - ... (sps.gamma(shape) * scale**shape)) - >>> plt.plot(bins, y, linewidth=2, color='r') - >>> plt.show() - - """ - cdef ndarray oshape - cdef double fshape - - fshape = PyFloat_AsDouble(shape) - if not PyErr_Occurred(): - if fshape <= 0: - raise ValueError("shape <= 0") - return vec_cont1_array_sc(self.internal_state, irk_standard_gamma_vec, - size, fshape, self.lock) - - PyErr_Clear() - oshape = PyArray_FROM_OTF(shape, NPY_DOUBLE, - NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(oshape, 0.0)): - raise ValueError("shape <= 0") - return vec_cont1_array(self.internal_state, irk_standard_gamma_vec, size, - oshape, self.lock) - - def gamma(self, shape, scale=1.0, size=None): - """ - gamma(shape, scale=1.0, size=None) - - Draw samples from a Gamma distribution. - - Samples are drawn from a Gamma distribution with specified parameters, - `shape` (sometimes designated "k") and `scale` (sometimes designated - "theta"), where both parameters are > 0. - - Parameters - ---------- - shape : scalar > 0 - The shape of the gamma distribution. - scale : scalar > 0, optional - The scale of the gamma distribution. Default is equal to 1. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - out : ndarray, float - Returns one sample unless `size` parameter is specified. - - See Also - -------- - scipy.stats.distributions.gamma : probability density function, - distribution or cumulative density function, etc. - - Notes - ----- - The probability density for the Gamma distribution is - - .. math:: p(x) = x^{k-1}\\frac{e^{-x/\\theta}}{\\theta^k\\Gamma(k)}, - - where :math:`k` is the shape and :math:`\\theta` the scale, - and :math:`\\Gamma` is the Gamma function. - - The Gamma distribution is often used to model the times to failure of - electronic components, and arises naturally in processes for which the - waiting times between Poisson distributed events are relevant. - - References - ---------- - .. [1] Weisstein, Eric W. "Gamma Distribution." From MathWorld--A - Wolfram Web Resource. - http://mathworld.wolfram.com/GammaDistribution.html - .. [2] Wikipedia, "Gamma-distribution", - http://en.wikipedia.org/wiki/Gamma-distribution - - Examples - -------- - Draw samples from the distribution: - - >>> shape, scale = 2., 2. # mean and dispersion - >>> s = mkl_random.gamma(shape, scale, 1000) - - Display the histogram of the samples, along with - the probability density function: - - >>> import matplotlib.pyplot as plt - >>> import scipy.special as sps - >>> count, bins, ignored = plt.hist(s, 50, normed=True) - >>> y = bins**(shape-1)*(np.exp(-bins/scale) / - ... (sps.gamma(shape)*scale**shape)) - >>> plt.plot(bins, y, linewidth=2, color='r') - >>> plt.show() - - """ - cdef ndarray oshape, oscale - cdef double fshape, fscale - - fshape = PyFloat_AsDouble(shape) - fscale = PyFloat_AsDouble(scale) - if not PyErr_Occurred(): - if fshape <= 0: - raise ValueError("shape <= 0") - if fscale <= 0: - raise ValueError("scale <= 0") - return vec_cont2_array_sc(self.internal_state, irk_gamma_vec, size, fshape, - fscale, self.lock) - - PyErr_Clear() - oshape = PyArray_FROM_OTF(shape, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - oscale = PyArray_FROM_OTF(scale, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(oshape, 0.0)): - raise ValueError("shape <= 0") - if np.any(np.less_equal(oscale, 0.0)): - raise ValueError("scale <= 0") - return vec_cont2_array(self.internal_state, irk_gamma_vec, size, oshape, oscale, - self.lock) - - def f(self, dfnum, dfden, size=None): - """ - f(dfnum, dfden, size=None) - - Draw samples from an F distribution. - - Samples are drawn from an F distribution with specified parameters, - `dfnum` (degrees of freedom in numerator) and `dfden` (degrees of - freedom in denominator), where both parameters should be greater than - zero. - - The random variate of the F distribution (also known as the - Fisher distribution) is a continuous probability distribution - that arises in ANOVA tests, and is the ratio of two chi-square - variates. - - Parameters - ---------- - dfnum : float - Degrees of freedom in numerator. Should be greater than zero. - dfden : float - Degrees of freedom in denominator. Should be greater than zero. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or scalar - Samples from the Fisher distribution. - - See Also - -------- - scipy.stats.distributions.f : probability density function, - distribution or cumulative density function, etc. - - Notes - ----- - The F statistic is used to compare in-group variances to between-group - variances. Calculating the distribution depends on the sampling, and - so it is a function of the respective degrees of freedom in the - problem. The variable `dfnum` is the number of samples minus one, the - between-groups degrees of freedom, while `dfden` is the within-groups - degrees of freedom, the sum of the number of samples in each group - minus the number of groups. - - References - ---------- - .. [1] Glantz, Stanton A. "Primer of Biostatistics.", McGraw-Hill, - Fifth Edition, 2002. - .. [2] Wikipedia, "F-distribution", - http://en.wikipedia.org/wiki/F-distribution - - Examples - -------- - An example from Glantz[1], pp 47-40: - - Two groups, children of diabetics (25 people) and children from people - without diabetes (25 controls). Fasting blood glucose was measured, - case group had a mean value of 86.1, controls had a mean value of - 82.2. Standard deviations were 2.09 and 2.49 respectively. Are these - data consistent with the null hypothesis that the parents diabetic - status does not affect their children's blood glucose levels? - Calculating the F statistic from the data gives a value of 36.01. - - Draw samples from the distribution: - - >>> dfnum = 1. # between group degrees of freedom - >>> dfden = 48. # within groups degrees of freedom - >>> s = mkl_random.f(dfnum, dfden, 1000) - - The lower bound for the top 1% of the samples is : - - >>> sort(s)[-10] - 7.61988120985 - - So there is about a 1% chance that the F statistic will exceed 7.62, - the measured value is 36, so the null hypothesis is rejected at the 1% - level. - - """ - cdef ndarray odfnum, odfden - cdef double fdfnum, fdfden - - fdfnum = PyFloat_AsDouble(dfnum) - fdfden = PyFloat_AsDouble(dfden) - if not PyErr_Occurred(): - if fdfnum <= 0: - raise ValueError("shape <= 0") - if fdfden <= 0: - raise ValueError("scale <= 0") - return vec_cont2_array_sc(self.internal_state, irk_f_vec, size, fdfnum, - fdfden, self.lock) - - PyErr_Clear() - - odfnum = PyArray_FROM_OTF(dfnum, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - odfden = PyArray_FROM_OTF(dfden, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(odfnum, 0.0)): - raise ValueError("dfnum <= 0") - if np.any(np.less_equal(odfden, 0.0)): - raise ValueError("dfden <= 0") - return vec_cont2_array(self.internal_state, irk_f_vec, size, odfnum, odfden, - self.lock) - - def noncentral_f(self, dfnum, dfden, nonc, size=None): - """ - noncentral_f(dfnum, dfden, nonc, size=None) - - Draw samples from the noncentral F distribution. - - Samples are drawn from an F distribution with specified parameters, - `dfnum` (degrees of freedom in numerator) and `dfden` (degrees of - freedom in denominator), where both parameters > 1. - `nonc` is the non-centrality parameter. - - Parameters - ---------- - dfnum : int - Parameter, should be > 1. - dfden : int - Parameter, should be > 1. - nonc : float - Parameter, should be >= 0. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : scalar or ndarray - Drawn samples. - - Notes - ----- - When calculating the power of an experiment (power = probability of - rejecting the null hypothesis when a specific alternative is true) the - non-central F statistic becomes important. When the null hypothesis is - true, the F statistic follows a central F distribution. When the null - hypothesis is not true, then it follows a non-central F statistic. - - References - ---------- - .. [1] Weisstein, Eric W. "Noncentral F-Distribution." - From MathWorld--A Wolfram Web Resource. - http://mathworld.wolfram.com/NoncentralF-Distribution.html - .. [2] Wikipedia, "Noncentral F distribution", - http://en.wikipedia.org/wiki/Noncentral_F-distribution - - Examples - -------- - In a study, testing for a specific alternative to the null hypothesis - requires use of the Noncentral F distribution. We need to calculate the - area in the tail of the distribution that exceeds the value of the F - distribution for the null hypothesis. We'll plot the two probability - distributions for comparison. - - >>> dfnum = 3 # between group deg of freedom - >>> dfden = 20 # within groups degrees of freedom - >>> nonc = 3.0 - >>> nc_vals = mkl_random.noncentral_f(dfnum, dfden, nonc, 1000000) - >>> NF = np.histogram(nc_vals, bins=50, normed=True) - >>> c_vals = mkl_random.f(dfnum, dfden, 1000000) - >>> F = np.histogram(c_vals, bins=50, normed=True) - >>> plt.plot(F[1][1:], F[0]) - >>> plt.plot(NF[1][1:], NF[0]) - >>> plt.show() - - """ - cdef ndarray odfnum, odfden, ononc - cdef double fdfnum, fdfden, fnonc - - fdfnum = PyFloat_AsDouble(dfnum) - fdfden = PyFloat_AsDouble(dfden) - fnonc = PyFloat_AsDouble(nonc) - if not PyErr_Occurred(): - if fdfnum <= 1: - raise ValueError("dfnum <= 1") - if fdfden <= 0: - raise ValueError("dfden <= 0") - if fnonc < 0: - raise ValueError("nonc < 0") - return vec_cont3_array_sc(self.internal_state, irk_noncentral_f_vec, size, - fdfnum, fdfden, fnonc, self.lock) - - PyErr_Clear() - - odfnum = PyArray_FROM_OTF(dfnum, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - odfden = PyArray_FROM_OTF(dfden, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - ononc = PyArray_FROM_OTF(nonc, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - - if np.any(np.less_equal(odfnum, 1.0)): - raise ValueError("dfnum <= 1") - if np.any(np.less_equal(odfden, 0.0)): - raise ValueError("dfden <= 0") - if np.any(np.less(ononc, 0.0)): - raise ValueError("nonc < 0") - return vec_cont3_array(self.internal_state, irk_noncentral_f_vec, size, odfnum, - odfden, ononc, self.lock) - - def chisquare(self, df, size=None): - """ - chisquare(df, size=None) - - Draw samples from a chi-square distribution. - - When `df` independent random variables, each with standard normal - distributions (mean 0, variance 1), are squared and summed, the - resulting distribution is chi-square (see Notes). This distribution - is often used in hypothesis testing. - - Parameters - ---------- - df : int - Number of degrees of freedom. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - output : ndarray - Samples drawn from the distribution, packed in a `size`-shaped - array. - - Raises - ------ - ValueError - When `df` <= 0 or when an inappropriate `size` (e.g. ``size=-1``) - is given. - - Notes - ----- - The variable obtained by summing the squares of `df` independent, - standard normally distributed random variables: - - .. math:: Q = \\sum_{i=0}^{\\mathtt{df}} X^2_i - - is chi-square distributed, denoted - - .. math:: Q \\sim \\chi^2_k. - - The probability density function of the chi-squared distribution is - - .. math:: p(x) = \\frac{(1/2)^{k/2}}{\\Gamma(k/2)} - x^{k/2 - 1} e^{-x/2}, - - where :math:`\\Gamma` is the gamma function, - - .. math:: \\Gamma(x) = \\int_0^{-\\infty} t^{x - 1} e^{-t} dt. - - References - ---------- - .. [1] NIST "Engineering Statistics Handbook" - http://www.itl.nist.gov/div898/handbook/eda/section3/eda3666.htm - - Examples - -------- - >>> mkl_random.chisquare(2,4) - array([ 1.89920014, 9.00867716, 3.13710533, 5.62318272]) - - """ - cdef ndarray odf - cdef double fdf - - fdf = PyFloat_AsDouble(df) - if not PyErr_Occurred(): - if fdf <= 0: - raise ValueError("df <= 0") - return vec_cont1_array_sc(self.internal_state, irk_chisquare_vec, size, fdf, - self.lock) - - PyErr_Clear() - - odf = PyArray_FROM_OTF(df, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(odf, 0.0)): - raise ValueError("df <= 0") - return vec_cont1_array(self.internal_state, irk_chisquare_vec, size, odf, - self.lock) - - def noncentral_chisquare(self, df, nonc, size=None): - """ - noncentral_chisquare(df, nonc, size=None) - - Draw samples from a noncentral chi-square distribution. - - The noncentral :math:`\\chi^2` distribution is a generalisation of - the :math:`\\chi^2` distribution. - - Parameters - ---------- - df : int - Degrees of freedom, should be > 0 as of Numpy 1.10, - should be > 1 for earlier versions. - nonc : float - Non-centrality, should be non-negative. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Notes - ----- - The probability density function for the noncentral Chi-square - distribution is - - .. math:: P(x;df,nonc) = \\sum^{\\infty}_{i=0} - \\frac{e^{-nonc/2}(nonc/2)^{i}}{i!} - \\P_{Y_{df+2i}}(x), - - where :math:`Y_{q}` is the Chi-square with q degrees of freedom. - - In Delhi (2007), it is noted that the noncentral chi-square is - useful in bombing and coverage problems, the probability of - killing the point target given by the noncentral chi-squared - distribution. - - References - ---------- - .. [1] Delhi, M.S. Holla, "On a noncentral chi-square distribution in - the analysis of weapon systems effectiveness", Metrika, - Volume 15, Number 1 / December, 1970. - .. [2] Wikipedia, "Noncentral chi-square distribution" - http://en.wikipedia.org/wiki/Noncentral_chi-square_distribution - - Examples - -------- - Draw values from the distribution and plot the histogram - - >>> import matplotlib.pyplot as plt - >>> values = plt.hist(mkl_random.noncentral_chisquare(3, 20, 100000), - ... bins=200, normed=True) - >>> plt.show() - - Draw values from a noncentral chisquare with very small noncentrality, - and compare to a chisquare. - - >>> plt.figure() - >>> values = plt.hist(mkl_random.noncentral_chisquare(3, .0000001, 100000), - ... bins=np.arange(0., 25, .1), normed=True) - >>> values2 = plt.hist(mkl_random.chisquare(3, 100000), - ... bins=np.arange(0., 25, .1), normed=True) - >>> plt.plot(values[1][0:-1], values[0]-values2[0], 'ob') - >>> plt.show() - - Demonstrate how large values of non-centrality lead to a more symmetric - distribution. - - >>> plt.figure() - >>> values = plt.hist(mkl_random.noncentral_chisquare(3, 20, 100000), - ... bins=200, normed=True) - >>> plt.show() - - """ - cdef ndarray odf, ononc - cdef double fdf, fnonc - fdf = PyFloat_AsDouble(df) - fnonc = PyFloat_AsDouble(nonc) - if not PyErr_Occurred(): - if fdf <= 0: - raise ValueError("df <= 0") - if fnonc < 0: - raise ValueError("nonc < 0") - return vec_cont2_array_sc(self.internal_state, irk_noncentral_chisquare_vec, - size, fdf, fnonc, self.lock) - - PyErr_Clear() - - odf = PyArray_FROM_OTF(df, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - ononc = PyArray_FROM_OTF(nonc, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(odf, 0.0)): - raise ValueError("df <= 0") - if np.any(np.less(ononc, 0.0)): - raise ValueError("nonc < 0") - return vec_cont2_array(self.internal_state, irk_noncentral_chisquare_vec, size, - odf, ononc, self.lock) - - def standard_cauchy(self, size=None): - """ - standard_cauchy(size=None) - - Draw samples from a standard Cauchy distribution with mode = 0. - - Also known as the Lorentz distribution. - - Parameters - ---------- - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or scalar - The drawn samples. - - Notes - ----- - The probability density function for the full Cauchy distribution is - - .. math:: P(x; x_0, \\gamma) = \\frac{1}{\\pi \\gamma \\bigl[ 1+ - (\\frac{x-x_0}{\\gamma})^2 \\bigr] } - - and the Standard Cauchy distribution just sets :math:`x_0=0` and - :math:`\\gamma=1` - - The Cauchy distribution arises in the solution to the driven harmonic - oscillator problem, and also describes spectral line broadening. It - also describes the distribution of values at which a line tilted at - a random angle will cut the x axis. - - When studying hypothesis tests that assume normality, seeing how the - tests perform on data from a Cauchy distribution is a good indicator of - their sensitivity to a heavy-tailed distribution, since the Cauchy looks - very much like a Gaussian distribution, but with heavier tails. - - References - ---------- - .. [1] NIST/SEMATECH e-Handbook of Statistical Methods, "Cauchy - Distribution", - http://www.itl.nist.gov/div898/handbook/eda/section3/eda3663.htm - .. [2] Weisstein, Eric W. "Cauchy Distribution." From MathWorld--A - Wolfram Web Resource. - http://mathworld.wolfram.com/CauchyDistribution.html - .. [3] Wikipedia, "Cauchy distribution" - http://en.wikipedia.org/wiki/Cauchy_distribution - - Examples - -------- - Draw samples and plot the distribution: - - >>> s = mkl_random.standard_cauchy(1000000) - >>> s = s[(s>-25) & (s<25)] # truncate distribution so it plots well - >>> plt.hist(s, bins=100) - >>> plt.show() - - """ - return vec_cont0_array(self.internal_state, irk_standard_cauchy_vec, size, - self.lock) - - def standard_t(self, df, size=None): - """ - standard_t(df, size=None) - - Draw samples from a standard Student's t distribution with `df` degrees - of freedom. - - A special case of the hyperbolic distribution. As `df` gets - large, the result resembles that of the standard normal - distribution (`standard_normal`). - - Parameters - ---------- - df : int - Degrees of freedom, should be > 0. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or scalar - Drawn samples. - - Notes - ----- - The probability density function for the t distribution is - - .. math:: P(x, df) = \\frac{\\Gamma(\\frac{df+1}{2})}{\\sqrt{\\pi df} - \\Gamma(\\frac{df}{2})}\\Bigl( 1+\\frac{x^2}{df} \\Bigr)^{-(df+1)/2} - - The t test is based on an assumption that the data come from a - Normal distribution. The t test provides a way to test whether - the sample mean (that is the mean calculated from the data) is - a good estimate of the true mean. - - The derivation of the t-distribution was first published in - 1908 by William Gisset while working for the Guinness Brewery - in Dublin. Due to proprietary issues, he had to publish under - a pseudonym, and so he used the name Student. - - References - ---------- - .. [1] Dalgaard, Peter, "Introductory Statistics With R", - Springer, 2002. - .. [2] Wikipedia, "Student's t-distribution" - http://en.wikipedia.org/wiki/Student's_t-distribution - - Examples - -------- - From Dalgaard page 83 [1]_, suppose the daily energy intake for 11 - women in Kj is: - - >>> intake = np.array([5260., 5470, 5640, 6180, 6390, 6515, 6805, 7515, \\ - ... 7515, 8230, 8770]) - - Does their energy intake deviate systematically from the recommended - value of 7725 kJ? - - We have 10 degrees of freedom, so is the sample mean within 95% of the - recommended value? - - >>> s = mkl_random.standard_t(10, size=100000) - >>> np.mean(intake) - 6753.636363636364 - >>> intake.std(ddof=1) - 1142.1232221373727 - - Calculate the t statistic, setting the ddof parameter to the unbiased - value so the divisor in the standard deviation will be degrees of - freedom, N-1. - - >>> t = (np.mean(intake)-7725)/(intake.std(ddof=1)/np.sqrt(len(intake))) - >>> import matplotlib.pyplot as plt - >>> h = plt.hist(s, bins=100, normed=True) - - For a one-sided t-test, how far out in the distribution does the t - statistic appear? - - >>> np.sum(s PyArray_FROM_OTF(df, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(odf, 0.0)): - raise ValueError("df <= 0") - return vec_cont1_array(self.internal_state, irk_standard_t_vec, size, odf, - self.lock) - - def vonmises(self, mu, kappa, size=None): - """ - vonmises(mu, kappa, size=None) - - Draw samples from a von Mises distribution. - - Samples are drawn from a von Mises distribution with specified mode - (mu) and dispersion (kappa), on the interval [-pi, pi]. - - The von Mises distribution (also known as the circular normal - distribution) is a continuous probability distribution on the unit - circle. It may be thought of as the circular analogue of the normal - distribution. - - Parameters - ---------- - mu : float - Mode ("center") of the distribution. - kappa : float - Dispersion of the distribution, has to be >=0. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : scalar or ndarray - The returned samples, which are in the interval [-pi, pi]. - - See Also - -------- - scipy.stats.distributions.vonmises : probability density function, - distribution, or cumulative density function, etc. - - Notes - ----- - The probability density for the von Mises distribution is - - .. math:: p(x) = \\frac{e^{\\kappa cos(x-\\mu)}}{2\\pi I_0(\\kappa)}, - - where :math:`\\mu` is the mode and :math:`\\kappa` the dispersion, - and :math:`I_0(\\kappa)` is the modified Bessel function of order 0. - - The von Mises is named for Richard Edler von Mises, who was born in - Austria-Hungary, in what is now the Ukraine. He fled to the United - States in 1939 and became a professor at Harvard. He worked in - probability theory, aerodynamics, fluid mechanics, and philosophy of - science. - - References - ---------- - .. [1] Abramowitz, M. and Stegun, I. A. (Eds.). "Handbook of - Mathematical Functions with Formulas, Graphs, and Mathematical - Tables, 9th printing," New York: Dover, 1972. - .. [2] von Mises, R., "Mathematical Theory of Probability - and Statistics", New York: Academic Press, 1964. - - Examples - -------- - Draw samples from the distribution: - - >>> mu, kappa = 0.0, 4.0 # mean and dispersion - >>> s = mkl_random.vonmises(mu, kappa, 1000) - - Display the histogram of the samples, along with - the probability density function: - - >>> import matplotlib.pyplot as plt - >>> from scipy.special import i0 - >>> plt.hist(s, 50, normed=True) - >>> x = np.linspace(-np.pi, np.pi, num=51) - >>> y = np.exp(kappa*np.cos(x-mu))/(2*np.pi*i0(kappa)) - >>> plt.plot(x, y, linewidth=2, color='r') - >>> plt.show() - - """ - cdef ndarray omu, okappa - cdef double fmu, fkappa - - fmu = PyFloat_AsDouble(mu) - fkappa = PyFloat_AsDouble(kappa) - if not PyErr_Occurred(): - if fkappa < 0: - raise ValueError("kappa < 0") - return vec_cont2_array_sc(self.internal_state, irk_vonmises_vec, size, fmu, - fkappa, self.lock) - - PyErr_Clear() - - omu = PyArray_FROM_OTF(mu, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - okappa = PyArray_FROM_OTF(kappa, NPY_DOUBLE, - NPY_ARRAY_ALIGNED) - if np.any(np.less(okappa, 0.0)): - raise ValueError("kappa < 0") - return vec_cont2_array(self.internal_state, irk_vonmises_vec, size, omu, okappa, - self.lock) - - def pareto(self, a, size=None): - """ - pareto(a, size=None) - - Draw samples from a Pareto II or Lomax distribution with - specified shape. - - The Lomax or Pareto II distribution is a shifted Pareto - distribution. The classical Pareto distribution can be - obtained from the Lomax distribution by adding 1 and - multiplying by the scale parameter ``m`` (see Notes). The - smallest value of the Lomax distribution is zero while for the - classical Pareto distribution it is ``mu``, where the standard - Pareto distribution has location ``mu = 1``. Lomax can also - be considered as a simplified version of the Generalized - Pareto distribution (available in SciPy), with the scale set - to one and the location set to zero. - - The Pareto distribution must be greater than zero, and is - unbounded above. It is also known as the "80-20 rule". In - this distribution, 80 percent of the weights are in the lowest - 20 percent of the range, while the other 20 percent fill the - remaining 80 percent of the range. - - Parameters - ---------- - shape : float, > 0. - Shape of the distribution. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - See Also - -------- - scipy.stats.distributions.lomax.pdf : probability density function, - distribution or cumulative density function, etc. - scipy.stats.distributions.genpareto.pdf : probability density function, - distribution or cumulative density function, etc. - - Notes - ----- - The probability density for the Pareto distribution is - - .. math:: p(x) = \\frac{a m^a}{(1+x)^{a+1}} - - where :math:`a` is the shape and :math:`m` the scale. - - The Pareto distribution, named after the Italian economist - Vilfredo Pareto, is a power law probability distribution - useful in many real world problems. Outside the field of - economics it is generally referred to as the Bradford - distribution. Pareto developed the distribution to describe - the distribution of wealth in an economy. It has also found - use in insurance, web page access statistics, oil field sizes, - and many other problems, including the download frequency for - projects in Sourceforge [1]_. It is one of the so-called - "fat-tailed" distributions. - - - References - ---------- - .. [1] Francis Hunt and Paul Johnson, On the Pareto Distribution of - Sourceforge projects. - .. [2] Pareto, V. (1896). Course of Political Economy. Lausanne. - .. [3] Reiss, R.D., Thomas, M.(2001), Statistical Analysis of Extreme - Values, Birkhauser Verlag, Basel, pp 23-30. - .. [4] Wikipedia, "Pareto distribution", - http://en.wikipedia.org/wiki/Pareto_distribution - - Examples - -------- - Draw samples from the distribution: - - >>> a, m = 3., 2. # shape and mode - >>> s = (mkl_random.pareto(a, 1000) + 1) * m - - Display the histogram of the samples, along with the probability - density function: - - >>> import matplotlib.pyplot as plt - >>> count, bins, _ = plt.hist(s, 100, normed=True) - >>> fit = a*m**a / bins**(a+1) - >>> plt.plot(bins, max(count)*fit/max(fit), linewidth=2, color='r') - >>> plt.show() - - """ - cdef ndarray oa - cdef double fa - - fa = PyFloat_AsDouble(a) - if not PyErr_Occurred(): - if fa <= 0: - raise ValueError("a <= 0") - return vec_cont1_array_sc(self.internal_state, irk_pareto_vec, size, fa, - self.lock) - - PyErr_Clear() - - oa = PyArray_FROM_OTF(a, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(oa, 0.0)): - raise ValueError("a <= 0") - return vec_cont1_array(self.internal_state, irk_pareto_vec, size, oa, self.lock) - - def weibull(self, a, size=None): - """ - weibull(a, size=None) - - Draw samples from a Weibull distribution. - - Draw samples from a 1-parameter Weibull distribution with the given - shape parameter `a`. - - .. math:: X = (-ln(U))^{1/a} - - Here, U is drawn from the uniform distribution over (0,1]. - - The more common 2-parameter Weibull, including a scale parameter - :math:`\\lambda` is just :math:`X = \\lambda(-ln(U))^{1/a}`. - - Parameters - ---------- - a : float - Shape of the distribution. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray - - See Also - -------- - scipy.stats.distributions.weibull_max - scipy.stats.distributions.weibull_min - scipy.stats.distributions.genextreme - gumbel - - Notes - ----- - The Weibull (or Type III asymptotic extreme value distribution - for smallest values, SEV Type III, or Rosin-Rammler - distribution) is one of a class of Generalized Extreme Value - (GEV) distributions used in modeling extreme value problems. - This class includes the Gumbel and Frechet distributions. - - The probability density for the Weibull distribution is - - .. math:: p(x) = \\frac{a} - {\\lambda}(\\frac{x}{\\lambda})^{a-1}e^{-(x/\\lambda)^a}, - - where :math:`a` is the shape and :math:`\\lambda` the scale. - - The function has its peak (the mode) at - :math:`\\lambda(\\frac{a-1}{a})^{1/a}`. - - When ``a = 1``, the Weibull distribution reduces to the exponential - distribution. - - References - ---------- - .. [1] Waloddi Weibull, Royal Technical University, Stockholm, - 1939 "A Statistical Theory Of The Strength Of Materials", - Ingeniorsvetenskapsakademiens Handlingar Nr 151, 1939, - Generalstabens Litografiska Anstalts Forlag, Stockholm. - .. [2] Waloddi Weibull, "A Statistical Distribution Function of - Wide Applicability", Journal Of Applied Mechanics ASME Paper - 1951. - .. [3] Wikipedia, "Weibull distribution", - http://en.wikipedia.org/wiki/Weibull_distribution - - Examples - -------- - Draw samples from the distribution: - - >>> a = 5. # shape - >>> s = mkl_random.weibull(a, 1000) - - Display the histogram of the samples, along with - the probability density function: - - >>> import matplotlib.pyplot as plt - >>> x = np.arange(1,100.)/50. - >>> def weib(x,n,a): - ... return (a / n) * (x / n)**(a - 1) * np.exp(-(x / n)**a) - - >>> count, bins, ignored = plt.hist(mkl_random.weibull(5.,1000)) - >>> x = np.arange(1,100.)/50. - >>> scale = count.max()/weib(x, 1., 5.).max() - >>> plt.plot(x, weib(x, 1., 5.)*scale) - >>> plt.show() - - """ - cdef ndarray oa - cdef double fa - - fa = PyFloat_AsDouble(a) - if not PyErr_Occurred(): - if fa <= 0: - raise ValueError("a <= 0") - return vec_cont1_array_sc(self.internal_state, irk_weibull_vec, size, fa, - self.lock) - - PyErr_Clear() - - oa = PyArray_FROM_OTF(a, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(oa, 0.0)): - raise ValueError("a <= 0") - return vec_cont1_array(self.internal_state, irk_weibull_vec, size, oa, - self.lock) - - def power(self, a, size=None): - """ - power(a, size=None) - - Draws samples in [0, 1] from a power distribution with positive - exponent a - 1. - - Also known as the power function distribution. - - Parameters - ---------- - a : float - parameter, > 0 - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or scalar - The returned samples lie in [0, 1]. - - Raises - ------ - ValueError - If a < 1. - - Notes - ----- - The probability density function is - - .. math:: P(x; a) = ax^{a-1}, 0 \\le x \\le 1, a>0. - - The power function distribution is just the inverse of the Pareto - distribution. It may also be seen as a special case of the Beta - distribution. - - It is used, for example, in modeling the over-reporting of insurance - claims. - - References - ---------- - .. [1] Christian Kleiber, Samuel Kotz, "Statistical size distributions - in economics and actuarial sciences", Wiley, 2003. - .. [2] Heckert, N. A. and Filliben, James J. "NIST Handbook 148: - Dataplot Reference Manual, Volume 2: Let Subcommands and Library - Functions", National Institute of Standards and Technology - Handbook Series, June 2003. - http://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/powpdf.pdf - - Examples - -------- - Draw samples from the distribution: - - >>> a = 5. # shape - >>> samples = 1000 - >>> s = mkl_random.power(a, samples) - - Display the histogram of the samples, along with - the probability density function: - - >>> import matplotlib.pyplot as plt - >>> count, bins, ignored = plt.hist(s, bins=30) - >>> x = np.linspace(0, 1, 100) - >>> y = a*x**(a-1.) - >>> normed_y = samples*np.diff(bins)[0]*y - >>> plt.plot(x, normed_y) - >>> plt.show() - - Compare the power function distribution to the inverse of the Pareto. - - >>> from scipy import stats - >>> rvs = mkl_random.power(5, 1000000) - >>> rvsp = mkl_random.pareto(5, 1000000) - >>> xx = np.linspace(0,1,100) - >>> powpdf = stats.powerlaw.pdf(xx,5) - - >>> plt.figure() - >>> plt.hist(rvs, bins=50, normed=True) - >>> plt.plot(xx,powpdf,'r-') - >>> plt.title('mkl_random.power(5)') - - >>> plt.figure() - >>> plt.hist(1./(1.+rvsp), bins=50, normed=True) - >>> plt.plot(xx,powpdf,'r-') - >>> plt.title('inverse of 1 + mkl_random.pareto(5)') - - >>> plt.figure() - >>> plt.hist(1./(1.+rvsp), bins=50, normed=True) - >>> plt.plot(xx,powpdf,'r-') - >>> plt.title('inverse of stats.pareto(5)') - - """ - cdef ndarray oa - cdef double fa - - fa = PyFloat_AsDouble(a) - if not PyErr_Occurred(): - if fa <= 0: - raise ValueError("a <= 0") - return vec_cont1_array_sc(self.internal_state, irk_power_vec, size, fa, - self.lock) - - PyErr_Clear() - - oa = PyArray_FROM_OTF(a, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(oa, 0.0)): - raise ValueError("a <= 0") - return vec_cont1_array(self.internal_state, irk_power_vec, size, oa, self.lock) - - def laplace(self, loc=0.0, scale=1.0, size=None): - """ - laplace(loc=0.0, scale=1.0, size=None) - - Draw samples from the Laplace or double exponential distribution with - specified location (or mean) and scale (decay). - - The Laplace distribution is similar to the Gaussian/normal distribution, - but is sharper at the peak and has fatter tails. It represents the - difference between two independent, identically distributed exponential - random variables. - - Parameters - ---------- - loc : float, optional - The position, :math:`\\mu`, of the distribution peak. - scale : float, optional - :math:`\\lambda`, the exponential decay. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or float - - Notes - ----- - It has the probability density function - - .. math:: f(x; \\mu, \\lambda) = \\frac{1}{2\\lambda} - \\exp\\left(-\\frac{|x - \\mu|}{\\lambda}\\right). - - The first law of Laplace, from 1774, states that the frequency - of an error can be expressed as an exponential function of the - absolute magnitude of the error, which leads to the Laplace - distribution. For many problems in economics and health - sciences, this distribution seems to model the data better - than the standard Gaussian distribution. - - References - ---------- - .. [1] Abramowitz, M. and Stegun, I. A. (Eds.). "Handbook of - Mathematical Functions with Formulas, Graphs, and Mathematical - Tables, 9th printing," New York: Dover, 1972. - .. [2] Kotz, Samuel, et. al. "The Laplace Distribution and - Generalizations, " Birkhauser, 2001. - .. [3] Weisstein, Eric W. "Laplace Distribution." - From MathWorld--A Wolfram Web Resource. - http://mathworld.wolfram.com/LaplaceDistribution.html - .. [4] Wikipedia, "Laplace Distribution", - http://en.wikipedia.org/wiki/Laplace_distribution - - Examples - -------- - Draw samples from the distribution - - >>> loc, scale = 0., 1. - >>> s = mkl_random.laplace(loc, scale, 1000) - - Display the histogram of the samples, along with - the probability density function: - - >>> import matplotlib.pyplot as plt - >>> count, bins, ignored = plt.hist(s, 30, normed=True) - >>> x = np.arange(-8., 8., .01) - >>> pdf = np.exp(-abs(x-loc)/scale)/(2.*scale) - >>> plt.plot(x, pdf) - - Plot Gaussian for comparison: - - >>> g = (1/(scale * np.sqrt(2 * np.pi)) * - ... np.exp(-(x - loc)**2 / (2 * scale**2))) - >>> plt.plot(x,g) - - """ - cdef ndarray oloc, oscale - cdef double floc, fscale - - floc = PyFloat_AsDouble(loc) - fscale = PyFloat_AsDouble(scale) - if not PyErr_Occurred(): - if fscale <= 0: - raise ValueError("scale <= 0") - return vec_cont2_array_sc(self.internal_state, irk_laplace_vec, size, floc, - fscale, self.lock) - - PyErr_Clear() - oloc = PyArray_FROM_OTF(loc, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - oscale = PyArray_FROM_OTF(scale, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(oscale, 0.0)): - raise ValueError("scale <= 0") - return vec_cont2_array(self.internal_state, irk_laplace_vec, size, oloc, oscale, - self.lock) - - def gumbel(self, loc=0.0, scale=1.0, size=None): - """ - gumbel(loc=0.0, scale=1.0, size=None) - - Draw samples from a Gumbel distribution. - - Draw samples from a Gumbel distribution with specified location and - scale. For more information on the Gumbel distribution, see - Notes and References below. - - Parameters - ---------- - loc : float - The location of the mode of the distribution. - scale : float - The scale parameter of the distribution. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or scalar - - See Also - -------- - scipy.stats.gumbel_l - scipy.stats.gumbel_r - scipy.stats.genextreme - weibull - - Notes - ----- - The Gumbel (or Smallest Extreme Value (SEV) or the Smallest Extreme - Value Type I) distribution is one of a class of Generalized Extreme - Value (GEV) distributions used in modeling extreme value problems. - The Gumbel is a special case of the Extreme Value Type I distribution - for maximums from distributions with "exponential-like" tails. - - The probability density for the Gumbel distribution is - - .. math:: p(x) = \\frac{e^{-(x - \\mu)/ \\beta}}{\\beta} e^{ -e^{-(x - \\mu)/ - \\beta}}, - - where :math:`\\mu` is the mode, a location parameter, and - :math:`\\beta` is the scale parameter. - - The Gumbel (named for German mathematician Emil Julius Gumbel) was used - very early in the hydrology literature, for modeling the occurrence of - flood events. It is also used for modeling maximum wind speed and - rainfall rates. It is a "fat-tailed" distribution - the probability of - an event in the tail of the distribution is larger than if one used a - Gaussian, hence the surprisingly frequent occurrence of 100-year - floods. Floods were initially modeled as a Gaussian process, which - underestimated the frequency of extreme events. - - It is one of a class of extreme value distributions, the Generalized - Extreme Value (GEV) distributions, which also includes the Weibull and - Frechet. - - The function has a mean of :math:`\\mu + 0.57721\\beta` and a variance - of :math:`\\frac{\\pi^2}{6}\\beta^2`. - - References - ---------- - .. [1] Gumbel, E. J., "Statistics of Extremes," - New York: Columbia University Press, 1958. - .. [2] Reiss, R.-D. and Thomas, M., "Statistical Analysis of Extreme - Values from Insurance, Finance, Hydrology and Other Fields," - Basel: Birkhauser Verlag, 2001. - - Examples - -------- - Draw samples from the distribution: - - >>> mu, beta = 0, 0.1 # location and scale - >>> s = mkl_random.gumbel(mu, beta, 1000) - - Display the histogram of the samples, along with - the probability density function: - - >>> import matplotlib.pyplot as plt - >>> count, bins, ignored = plt.hist(s, 30, normed=True) - >>> plt.plot(bins, (1/beta)*np.exp(-(bins - mu)/beta) - ... * np.exp( -np.exp( -(bins - mu) /beta) ), - ... linewidth=2, color='r') - >>> plt.show() - - Show how an extreme value distribution can arise from a Gaussian process - and compare to a Gaussian: - - >>> means = [] - >>> maxima = [] - >>> for i in range(0,1000) : - ... a = mkl_random.normal(mu, beta, 1000) - ... means.append(a.mean()) - ... maxima.append(a.max()) - >>> count, bins, ignored = plt.hist(maxima, 30, normed=True) - >>> beta = np.std(maxima) * np.sqrt(6) / np.pi - >>> mu = np.mean(maxima) - 0.57721*beta - >>> plt.plot(bins, (1/beta)*np.exp(-(bins - mu)/beta) - ... * np.exp(-np.exp(-(bins - mu)/beta)), - ... linewidth=2, color='r') - >>> plt.plot(bins, 1/(beta * np.sqrt(2 * np.pi)) - ... * np.exp(-(bins - mu)**2 / (2 * beta**2)), - ... linewidth=2, color='g') - >>> plt.show() - - """ - cdef ndarray oloc, oscale - cdef double floc, fscale - - floc = PyFloat_AsDouble(loc) - fscale = PyFloat_AsDouble(scale) - if not PyErr_Occurred(): - if fscale <= 0: - raise ValueError("scale <= 0") - return vec_cont2_array_sc(self.internal_state, irk_gumbel_vec, size, floc, - fscale, self.lock) - - PyErr_Clear() - oloc = PyArray_FROM_OTF(loc, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - oscale = PyArray_FROM_OTF(scale, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(oscale, 0.0)): - raise ValueError("scale <= 0") - return vec_cont2_array(self.internal_state, irk_gumbel_vec, size, oloc, oscale, - self.lock) - - def logistic(self, loc=0.0, scale=1.0, size=None): - """ - logistic(loc=0.0, scale=1.0, size=None) - - Draw samples from a logistic distribution. - - Samples are drawn from a logistic distribution with specified - parameters, loc (location or mean, also median), and scale (>0). - - Parameters - ---------- - loc : float - - scale : float > 0. - - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or scalar - where the values are all integers in [0, n]. - - See Also - -------- - scipy.stats.distributions.logistic : probability density function, - distribution or cumulative density function, etc. - - Notes - ----- - The probability density for the Logistic distribution is - - .. math:: P(x) = P(x) = \\frac{e^{-(x-\\mu)/s}}{s(1+e^{-(x-\\mu)/s})^2}, - - where :math:`\\mu` = location and :math:`s` = scale. - - The Logistic distribution is used in Extreme Value problems where it - can act as a mixture of Gumbel distributions, in Epidemiology, and by - the World Chess Federation (FIDE) where it is used in the Elo ranking - system, assuming the performance of each player is a logistically - distributed random variable. - - References - ---------- - .. [1] Reiss, R.-D. and Thomas M. (2001), "Statistical Analysis of - Extreme Values, from Insurance, Finance, Hydrology and Other - Fields," Birkhauser Verlag, Basel, pp 132-133. - .. [2] Weisstein, Eric W. "Logistic Distribution." From - MathWorld--A Wolfram Web Resource. - http://mathworld.wolfram.com/LogisticDistribution.html - .. [3] Wikipedia, "Logistic-distribution", - http://en.wikipedia.org/wiki/Logistic_distribution - - Examples - -------- - Draw samples from the distribution: - - >>> loc, scale = 10, 1 - >>> s = mkl_random.logistic(loc, scale, 10000) - >>> count, bins, ignored = plt.hist(s, bins=50) - - # plot against distribution - - >>> def logist(x, loc, scale): - ... return exp((loc-x)/scale)/(scale*(1+exp((loc-x)/scale))**2) - >>> plt.plot(bins, logist(bins, loc, scale)*count.max()/\\ - ... logist(bins, loc, scale).max()) - >>> plt.show() - - """ - cdef ndarray oloc, oscale - cdef double floc, fscale - - floc = PyFloat_AsDouble(loc) - fscale = PyFloat_AsDouble(scale) - if not PyErr_Occurred(): - if fscale <= 0: - raise ValueError("scale <= 0") - return vec_cont2_array_sc(self.internal_state, irk_logistic_vec, size, floc, - fscale, self.lock) - - PyErr_Clear() - oloc = PyArray_FROM_OTF(loc, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - oscale = PyArray_FROM_OTF(scale, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(oscale, 0.0)): - raise ValueError("scale <= 0") - return vec_cont2_array(self.internal_state, irk_logistic_vec, size, oloc, - oscale, self.lock) - - def lognormal(self, mean=0.0, sigma=1.0, size=None, method=ICDF): - """ - lognormal(mean=0.0, sigma=1.0, size=None, method='ICDF') - - Draw samples from a log-normal distribution. - - Draw samples from a log-normal distribution with specified mean, - standard deviation, and array shape. Note that the mean and standard - deviation are not the values for the distribution itself, but of the - underlying normal distribution it is derived from. - - Parameters - ---------- - mean : float - Mean value of the underlying normal distribution - sigma : float, > 0. - Standard deviation of the underlying normal distribution - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - method : 'ICDF, 'BoxMuller', optional - Sampling method used by Intel MKL. Can also be specified using - tokens mkl_random.ICDF, mkl_random.BOXMULLER - - Returns - ------- - samples : ndarray or float - The desired samples. An array of the same shape as `size` if given, - if `size` is None a float is returned. - - See Also - -------- - scipy.stats.lognorm : probability density function, distribution, - cumulative density function, etc. - - Notes - ----- - A variable `x` has a log-normal distribution if `log(x)` is normally - distributed. The probability density function for the log-normal - distribution is: - - .. math:: p(x) = \\frac{1}{\\sigma x \\sqrt{2\\pi}} - e^{(-\\frac{(ln(x)-\\mu)^2}{2\\sigma^2})} - - where :math:`\\mu` is the mean and :math:`\\sigma` is the standard - deviation of the normally distributed logarithm of the variable. - A log-normal distribution results if a random variable is the *product* - of a large number of independent, identically-distributed variables in - the same way that a normal distribution results if the variable is the - *sum* of a large number of independent, identically-distributed - variables. - - References - ---------- - .. [1] Limpert, E., Stahel, W. A., and Abbt, M., "Log-normal - Distributions across the Sciences: Keys and Clues," - BioScience, Vol. 51, No. 5, May, 2001. - http://stat.ethz.ch/~stahel/lognormal/bioscience.pdf - .. [2] Reiss, R.D. and Thomas, M., "Statistical Analysis of Extreme - Values," Basel: Birkhauser Verlag, 2001, pp. 31-32. - - Examples - -------- - Draw samples from the distribution: - - >>> mu, sigma = 3., 1. # mean and standard deviation - >>> s = mkl_random.lognormal(mu, sigma, 1000) - - Display the histogram of the samples, along with - the probability density function: - - >>> import matplotlib.pyplot as plt - >>> count, bins, ignored = plt.hist(s, 100, normed=True, align='mid') - - >>> x = np.linspace(min(bins), max(bins), 10000) - >>> pdf = (np.exp(-(np.log(x) - mu)**2 / (2 * sigma**2)) - ... / (x * sigma * np.sqrt(2 * np.pi))) - - >>> plt.plot(x, pdf, linewidth=2, color='r') - >>> plt.axis('tight') - >>> plt.show() - - Demonstrate that taking the products of random samples from a uniform - distribution can be fit well by a log-normal probability density - function. - - >>> # Generate a thousand samples: each is the product of 100 random - >>> # values, drawn from a normal distribution. - >>> b = [] - >>> for i in range(1000): - ... a = 10. + mkl_random.random(100) - ... b.append(np.product(a)) - - >>> b = np.array(b) / np.min(b) # scale values to be positive - >>> count, bins, ignored = plt.hist(b, 100, normed=True, align='mid') - >>> sigma = np.std(np.log(b)) - >>> mu = np.mean(np.log(b)) - - >>> x = np.linspace(min(bins), max(bins), 10000) - >>> pdf = (np.exp(-(np.log(x) - mu)**2 / (2 * sigma**2)) - ... / (x * sigma * np.sqrt(2 * np.pi))) - - >>> plt.plot(x, pdf, color='r', linewidth=2) - >>> plt.show() - - """ - cdef ndarray omean, osigma - cdef double fmean, fsigma - - fmean = PyFloat_AsDouble(mean) - fsigma = PyFloat_AsDouble(sigma) - - if not PyErr_Occurred(): - if fsigma <= 0: - raise ValueError("sigma <= 0") - method = choose_method(method, [ICDF, BOXMULLER], _method_alias_dict_gaussian_short) - if method is ICDF: - return vec_cont2_array_sc(self.internal_state, irk_lognormal_vec_ICDF, size, - fmean, fsigma, self.lock) - else: - return vec_cont2_array_sc(self.internal_state, irk_lognormal_vec_BM, size, - fmean, fsigma, self.lock) - - PyErr_Clear() - - omean = PyArray_FROM_OTF(mean, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - osigma = PyArray_FROM_OTF(sigma, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(osigma, 0.0)): - raise ValueError("sigma <= 0.0") - - method = choose_method(method, [ICDF, BOXMULLER], _method_alias_dict_gaussian_short) - if method is ICDF: - return vec_cont2_array(self.internal_state, irk_lognormal_vec_ICDF, size, - omean, osigma, self.lock) - else: - return vec_cont2_array(self.internal_state, irk_lognormal_vec_BM, size, - omean, osigma, self.lock) - - - def rayleigh(self, scale=1.0, size=None): - """ - rayleigh(scale=1.0, size=None) - - Draw samples from a Rayleigh distribution. - - The :math:`\\chi` and Weibull distributions are generalizations of the - Rayleigh. - - Parameters - ---------- - scale : scalar - Scale, also equals the mode. Should be >= 0. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Notes - ----- - The probability density function for the Rayleigh distribution is - - .. math:: P(x;scale) = \\frac{x}{scale^2}e^{\\frac{-x^2}{2 \\cdotp scale^2}} - - The Rayleigh distribution would arise, for example, if the East - and North components of the wind velocity had identical zero-mean - Gaussian distributions. Then the wind speed would have a Rayleigh - distribution. - - References - ---------- - .. [1] Brighton Webs Ltd., "Rayleigh Distribution," - http://www.brighton-webs.co.uk/distributions/rayleigh.asp - .. [2] Wikipedia, "Rayleigh distribution" - http://en.wikipedia.org/wiki/Rayleigh_distribution - - Examples - -------- - Draw values from the distribution and plot the histogram - - >>> values = hist(mkl_random.rayleigh(3, 100000), bins=200, normed=True) - - Wave heights tend to follow a Rayleigh distribution. If the mean wave - height is 1 meter, what fraction of waves are likely to be larger than 3 - meters? - - >>> meanvalue = 1 - >>> modevalue = np.sqrt(2 / np.pi) * meanvalue - >>> s = mkl_random.rayleigh(modevalue, 1000000) - - The percentage of waves larger than 3 meters is: - - >>> 100.*sum(s>3)/1000000. - 0.087300000000000003 - - """ - cdef ndarray oscale - cdef double fscale - - fscale = PyFloat_AsDouble(scale) - - if not PyErr_Occurred(): - if fscale <= 0: - raise ValueError("scale <= 0") - return vec_cont1_array_sc(self.internal_state, irk_rayleigh_vec, size, - fscale, self.lock) - - PyErr_Clear() - - oscale = PyArray_FROM_OTF(scale, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(oscale, 0.0)): - raise ValueError("scale <= 0.0") - return vec_cont1_array(self.internal_state, irk_rayleigh_vec, size, oscale, - self.lock) - - def wald(self, mean, scale, size=None): - """ - wald(mean, scale, size=None) - - Draw samples from a Wald, or inverse Gaussian, distribution. - - As the scale approaches infinity, the distribution becomes more like a - Gaussian. Some references claim that the Wald is an inverse Gaussian - with mean equal to 1, but this is by no means universal. - - The inverse Gaussian distribution was first studied in relationship to - Brownian motion. In 1956 M.C.K. Tweedie used the name inverse Gaussian - because there is an inverse relationship between the time to cover a - unit distance and distance covered in unit time. - - Parameters - ---------- - mean : scalar - Distribution mean, should be > 0. - scale : scalar - Scale parameter, should be >= 0. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or scalar - Drawn sample, all greater than zero. - - Notes - ----- - The probability density function for the Wald distribution is - - .. math:: P(x;mean,scale) = \\sqrt{\\frac{scale}{2\\pi x^3}}e^ - \\frac{-scale(x-mean)^2}{2\\cdotp mean^2x} - - As noted above the inverse Gaussian distribution first arise - from attempts to model Brownian motion. It is also a - competitor to the Weibull for use in reliability modeling and - modeling stock returns and interest rate processes. - - References - ---------- - .. [1] Brighton Webs Ltd., Wald Distribution, - http://www.brighton-webs.co.uk/distributions/wald.asp - .. [2] Chhikara, Raj S., and Folks, J. Leroy, "The Inverse Gaussian - Distribution: Theory : Methodology, and Applications", CRC Press, - 1988. - .. [3] Wikipedia, "Wald distribution" - http://en.wikipedia.org/wiki/Wald_distribution - - Examples - -------- - Draw values from the distribution and plot the histogram: - - >>> import matplotlib.pyplot as plt - >>> h = plt.hist(mkl_random.wald(3, 2, 100000), bins=200, normed=True) - >>> plt.show() - - """ - cdef ndarray omean, oscale - cdef double fmean, fscale - - fmean = PyFloat_AsDouble(mean) - fscale = PyFloat_AsDouble(scale) - if not PyErr_Occurred(): - if fmean <= 0: - raise ValueError("mean <= 0") - if fscale <= 0: - raise ValueError("scale <= 0") - return vec_cont2_array_sc(self.internal_state, irk_wald_vec, size, fmean, - fscale, self.lock) - - PyErr_Clear() - omean = PyArray_FROM_OTF(mean, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - oscale = PyArray_FROM_OTF(scale, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(omean,0.0)): - raise ValueError("mean <= 0.0") - elif np.any(np.less_equal(oscale,0.0)): - raise ValueError("scale <= 0.0") - return vec_cont2_array(self.internal_state, irk_wald_vec, size, omean, oscale, - self.lock) - - def triangular(self, left, mode, right, size=None): - """ - triangular(left, mode, right, size=None) - - Draw samples from the triangular distribution. - - The triangular distribution is a continuous probability - distribution with lower limit left, peak at mode, and upper - limit right. Unlike the other distributions, these parameters - directly define the shape of the pdf. - - Parameters - ---------- - left : scalar - Lower limit. - mode : scalar - The value where the peak of the distribution occurs. - The value should fulfill the condition ``left <= mode <= right``. - right : scalar - Upper limit, should be larger than `left`. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or scalar - The returned samples all lie in the interval [left, right]. - - Notes - ----- - The probability density function for the triangular distribution is - - .. math:: P(x;l, m, r) = \\begin{cases} - \\frac{2(x-l)}{(r-l)(m-l)}& \\text{for $l \\leq x \\leq m$},\\\\ - \\frac{2(r-x)}{(r-l)(r-m)}& \\text{for $m \\leq x \\leq r$},\\\\ - 0& \\text{otherwise}. - \\end{cases} - - The triangular distribution is often used in ill-defined - problems where the underlying distribution is not known, but - some knowledge of the limits and mode exists. Often it is used - in simulations. - - References - ---------- - .. [1] Wikipedia, "Triangular distribution" - http://en.wikipedia.org/wiki/Triangular_distribution - - Examples - -------- - Draw values from the distribution and plot the histogram: - - >>> import matplotlib.pyplot as plt - >>> h = plt.hist(mkl_random.triangular(-3, 0, 8, 100000), bins=200, - ... normed=True) - >>> plt.show() - - """ - cdef ndarray oleft, omode, oright - cdef double fleft, fmode, fright - - fleft = PyFloat_AsDouble(left) - fright = PyFloat_AsDouble(right) - fmode = PyFloat_AsDouble(mode) - if not PyErr_Occurred(): - if fleft > fmode: - raise ValueError("left > mode") - if fmode > fright: - raise ValueError("mode > right") - if fleft == fright: - raise ValueError("left == right") - return vec_cont3_array_sc(self.internal_state, irk_triangular_vec, size, - fleft, fmode, fright, self.lock) - - PyErr_Clear() - oleft = PyArray_FROM_OTF(left, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - omode = PyArray_FROM_OTF(mode, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - oright = PyArray_FROM_OTF(right, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - - if np.any(np.greater(oleft, omode)): - raise ValueError("left > mode") - if np.any(np.greater(omode, oright)): - raise ValueError("mode > right") - if np.any(np.equal(oleft, oright)): - raise ValueError("left == right") - return vec_cont3_array(self.internal_state, irk_triangular_vec, size, oleft, - omode, oright, self.lock) - - # Complicated, discrete distributions: - def binomial(self, n, p, size=None): - """ - binomial(n, p, size=None) - - Draw samples from a binomial distribution. - - Samples are drawn from a binomial distribution with specified - parameters, n trials and p probability of success where - n an integer >= 0 and p is in the interval [0,1]. (n may be - input as a float, but it is truncated to an integer in use) - - Parameters - ---------- - n : float (but truncated to an integer) - parameter, >= 0. - p : float - parameter, >= 0 and <=1. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or scalar - where the values are all integers in [0, n]. - - See Also - -------- - scipy.stats.distributions.binom : probability density function, - distribution or cumulative density function, etc. - - Notes - ----- - The probability density for the binomial distribution is - - .. math:: P(N) = \\binom{n}{N}p^N(1-p)^{n-N}, - - where :math:`n` is the number of trials, :math:`p` is the probability - of success, and :math:`N` is the number of successes. - - When estimating the standard error of a proportion in a population by - using a random sample, the normal distribution works well unless the - product p*n <=5, where p = population proportion estimate, and n = - number of samples, in which case the binomial distribution is used - instead. For example, a sample of 15 people shows 4 who are left - handed, and 11 who are right handed. Then p = 4/15 = 27%. 0.27*15 = 4, - so the binomial distribution should be used in this case. - - References - ---------- - .. [1] Dalgaard, Peter, "Introductory Statistics with R", - Springer-Verlag, 2002. - .. [2] Glantz, Stanton A. "Primer of Biostatistics.", McGraw-Hill, - Fifth Edition, 2002. - .. [3] Lentner, Marvin, "Elementary Applied Statistics", Bogden - and Quigley, 1972. - .. [4] Weisstein, Eric W. "Binomial Distribution." From MathWorld--A - Wolfram Web Resource. - http://mathworld.wolfram.com/BinomialDistribution.html - .. [5] Wikipedia, "Binomial-distribution", - http://en.wikipedia.org/wiki/Binomial_distribution - - Examples - -------- - Draw samples from the distribution: - - >>> n, p = 10, .5 # number of trials, probability of each trial - >>> s = mkl_random.binomial(n, p, 1000) - # result of flipping a coin 10 times, tested 1000 times. - - A real world example. A company drills 9 wild-cat oil exploration - wells, each with an estimated probability of success of 0.1. All nine - wells fail. What is the probability of that happening? - - Let's do 20,000 trials of the model, and count the number that - generate zero positive results. - - >>> sum(mkl_random.binomial(9, 0.1, 20000) == 0)/20000. - # answer = 0.38885, or 38%. - - """ - cdef ndarray on, op - cdef long ln - cdef double fp - - fp = PyFloat_AsDouble(p) - ln = PyInt_AsLong(n) - if not PyErr_Occurred(): - if ln < 0: - raise ValueError("n < 0") - if fp < 0: - raise ValueError("p < 0") - elif fp > 1: - raise ValueError("p > 1") - elif np.isnan(fp): - raise ValueError("p is nan") - if n > int(2**31-1): - raise ValueError("n > 2147483647") - else: - return vec_discnp_array_sc(self.internal_state, irk_binomial_vec, size, ln, - fp, self.lock) - - - PyErr_Clear() - - on = PyArray_FROM_OTF(n, NPY_LONG, NPY_ARRAY_IN_ARRAY) - op = PyArray_FROM_OTF(p, NPY_DOUBLE, NPY_ARRAY_IN_ARRAY) - if np.any(np.less(n, 0)): - raise ValueError("n < 0") - if np.any(np.less(op, 0)): - raise ValueError("p < 0") - if np.any(np.greater(op, 1)): - raise ValueError("p > 1") - if np.any(np.greater(n, int(2**31-1))): - raise ValueError("n > 2147483647") - - on = on.astype(np.int32, casting='unsafe') - return vec_discnp_array(self.internal_state, irk_binomial_vec, size, on, op, - self.lock) - - def negative_binomial(self, n, p, size=None): - """ - negative_binomial(n, p, size=None) - - Draw samples from a negative binomial distribution. - - Samples are drawn from a negative binomial distribution with specified - parameters, `n` trials and `p` probability of success where `n` is an - integer > 0 and `p` is in the interval [0, 1]. - - Parameters - ---------- - n : int - Parameter, > 0. - p : float - Parameter, >= 0 and <=1. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : int or ndarray of ints - Drawn samples. - - Notes - ----- - The probability density for the negative binomial distribution is - - .. math:: P(N;n,p) = \\binom{N+n-1}{n-1}p^{n}(1-p)^{N}, - - where :math:`n-1` is the number of successes, :math:`p` is the - probability of success, and :math:`N+n-1` is the number of trials. - The negative binomial distribution gives the probability of n-1 - successes and N failures in N+n-1 trials, and success on the (N+n)th - trial. - - If one throws a die repeatedly until the third time a "1" appears, - then the probability distribution of the number of non-"1"s that - appear before the third "1" is a negative binomial distribution. - - References - ---------- - .. [1] Weisstein, Eric W. "Negative Binomial Distribution." From - MathWorld--A Wolfram Web Resource. - http://mathworld.wolfram.com/NegativeBinomialDistribution.html - .. [2] Wikipedia, "Negative binomial distribution", - http://en.wikipedia.org/wiki/Negative_binomial_distribution - - Examples - -------- - Draw samples from the distribution: - - A real world example. A company drills wild-cat oil - exploration wells, each with an estimated probability of - success of 0.1. What is the probability of having one success - for each successive well, that is what is the probability of a - single success after drilling 5 wells, after 6 wells, etc.? - - >>> s = mkl_random.negative_binomial(1, 0.1, 100000) - >>> for i in range(1, 11): - ... probability = sum(s 1: - raise ValueError("p > 1") - return vec_discdd_array_sc(self.internal_state, irk_negbinomial_vec, - size, fn, fp, self.lock) - - PyErr_Clear() - - on = PyArray_FROM_OTF(n, NPY_DOUBLE, NPY_ARRAY_IN_ARRAY) - op = PyArray_FROM_OTF(p, NPY_DOUBLE, NPY_ARRAY_IN_ARRAY) - if np.any(np.less_equal(n, 0)): - raise ValueError("n <= 0") - if np.any(np.less(p, 0)): - raise ValueError("p < 0") - if np.any(np.greater(p, 1)): - raise ValueError("p > 1") - return vec_discdd_array(self.internal_state, irk_negbinomial_vec, size, - on, op, self.lock) - - def poisson(self, lam=1.0, size=None, method=POISNORM): - """ - poisson(lam=1.0, size=None, method='POISNORM') - - Draw samples from a Poisson distribution. - - The Poisson distribution is the limit of the binomial distribution - for large N. - - Parameters - ---------- - lam : float or sequence of float - Expectation of interval, should be >= 0. A sequence of expectation - intervals must be broadcastable over the requested size. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - method : 'POISNORM, 'PTPE', optional - Sampling method used by Intel MKL. Can also be specified using - tokens mkl_random.POISNORM, mkl_random.PTPE - - Returns - ------- - samples : ndarray or scalar - The drawn samples, of shape *size*, if it was provided. - - Notes - ----- - The Poisson distribution - - .. math:: f(k; \\lambda)=\\frac{\\lambda^k e^{-\\lambda}}{k!} - - For events with an expected separation :math:`\\lambda` the Poisson - distribution :math:`f(k; \\lambda)` describes the probability of - :math:`k` events occurring within the observed - interval :math:`\\lambda`. - - Because the output is limited to the range of the C long type, a - ValueError is raised when `lam` is within 10 sigma of the maximum - representable value. - - References - ---------- - .. [1] Weisstein, Eric W. "Poisson Distribution." - From MathWorld--A Wolfram Web Resource. - http://mathworld.wolfram.com/PoissonDistribution.html - .. [2] Wikipedia, "Poisson distribution", - http://en.wikipedia.org/wiki/Poisson_distribution - - Examples - -------- - Draw samples from the distribution: - - >>> import numpy as np - >>> s = mkl_random.poisson(5, 10000) - - Display histogram of the sample: - - >>> import matplotlib.pyplot as plt - >>> count, bins, ignored = plt.hist(s, 14, normed=True) - >>> plt.show() - - Draw each 100 values for lambda 100 and 500: - - >>> s = mkl_random.poisson(lam=(100., 500.), size=(100, 2)) - - """ - cdef ndarray olam - cdef double flam - flam = PyFloat_AsDouble(lam) - if not PyErr_Occurred(): - if lam < 0: - raise ValueError("lam < 0") - if lam > self.poisson_lam_max: - raise ValueError("lam value too large") - method = choose_method(method, [POISNORM, PTPE], _method_alias_dict_poisson); - if method is POISNORM: - return vec_discd_array_sc(self.internal_state, irk_poisson_vec_POISNORM, size, flam, self.lock) - else: - return vec_discd_array_sc(self.internal_state, irk_poisson_vec_PTPE, size, flam, self.lock) - - PyErr_Clear() - - olam = PyArray_FROM_OTF(lam, NPY_DOUBLE, NPY_ARRAY_IN_ARRAY) - if np.any(np.less(olam, 0)): - raise ValueError("lam < 0") - if np.any(np.greater(olam, self.poisson_lam_max)): - raise ValueError("lam value too large.") - method = choose_method(method, [POISNORM, PTPE], _method_alias_dict_poisson); - if method is POISNORM: - return vec_Poisson_array(self.internal_state, irk_poisson_vec_V, irk_poisson_vec_POISNORM, size, olam, self.lock) - else: - return vec_discd_array(self.internal_state, irk_poisson_vec_PTPE, size, olam, self.lock) - - - def zipf(self, a, size=None): - """ - zipf(a, size=None) - - Draw samples from a Zipf distribution. - - Samples are drawn from a Zipf distribution with specified parameter - `a` > 1. - - The Zipf distribution (also known as the zeta distribution) is a - continuous probability distribution that satisfies Zipf's law: the - frequency of an item is inversely proportional to its rank in a - frequency table. - - Parameters - ---------- - a : float > 1 - Distribution parameter. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : scalar or ndarray - The returned samples are greater than or equal to one. - - See Also - -------- - scipy.stats.distributions.zipf : probability density function, - distribution, or cumulative density function, etc. - - Notes - ----- - The probability density for the Zipf distribution is - - .. math:: p(x) = \\frac{x^{-a}}{\\zeta(a)}, - - where :math:`\\zeta` is the Riemann Zeta function. - - It is named for the American linguist George Kingsley Zipf, who noted - that the frequency of any word in a sample of a language is inversely - proportional to its rank in the frequency table. - - References - ---------- - .. [1] Zipf, G. K., "Selected Studies of the Principle of Relative - Frequency in Language," Cambridge, MA: Harvard Univ. Press, - 1932. - - Examples - -------- - Draw samples from the distribution: - - >>> a = 2. # parameter - >>> s = mkl_random.zipf(a, 1000) - - Display the histogram of the samples, along with - the probability density function: - - >>> import matplotlib.pyplot as plt - >>> import scipy.special as sps - Truncate s values at 50 so plot is interesting - >>> count, bins, ignored = plt.hist(s[s<50], 50, normed=True) - >>> x = np.arange(1., 50.) - >>> y = x**(-a)/sps.zetac(a) - >>> plt.plot(x, y/max(y), linewidth=2, color='r') - >>> plt.show() - - """ - cdef ndarray oa - cdef double fa - - fa = PyFloat_AsDouble(a) - if not PyErr_Occurred(): - if fa <= 1.0: - raise ValueError("a <= 1.0") - return vec_long_discd_array_sc(self.internal_state, irk_zipf_long_vec, size, fa, - self.lock) - - PyErr_Clear() - - oa = PyArray_FROM_OTF(a, NPY_DOUBLE, NPY_ARRAY_IN_ARRAY) - if np.any(np.less_equal(oa, 1.0)): - raise ValueError("a <= 1.0") - return vec_long_discd_array(self.internal_state, irk_zipf_long_vec, size, oa, self.lock) - - def geometric(self, p, size=None): - """ - geometric(p, size=None) - - Draw samples from the geometric distribution. - - Bernoulli trials are experiments with one of two outcomes: - success or failure (an example of such an experiment is flipping - a coin). The geometric distribution models the number of trials - that must be run in order to achieve success. It is therefore - supported on the positive integers, ``k = 1, 2, ...``. - - The probability mass function of the geometric distribution is - - .. math:: f(k) = (1 - p)^{k - 1} p - - where `p` is the probability of success of an individual trial. - - Parameters - ---------- - p : float - The probability of success of an individual trial. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - out : ndarray - Samples from the geometric distribution, shaped according to - `size`. - - Examples - -------- - Draw ten thousand values from the geometric distribution, - with the probability of an individual success equal to 0.35: - - >>> z = mkl_random.geometric(p=0.35, size=10000) - - How many trials succeeded after a single run? - - >>> (z == 1).sum() / 10000. - 0.34889999999999999 #random - - """ - cdef ndarray op - cdef double fp - - fp = PyFloat_AsDouble(p) - if not PyErr_Occurred(): - if fp <= 0.0: - raise ValueError("p <= 0.0") - if fp > 1.0: - raise ValueError("p > 1.0") - return vec_discd_array_sc(self.internal_state, irk_geometric_vec, size, fp, - self.lock) - - PyErr_Clear() - - - op = PyArray_FROM_OTF(p, NPY_DOUBLE, NPY_ARRAY_IN_ARRAY) - if np.any(np.less_equal(op, 0.0)): - raise ValueError("p < 0.0") - if np.any(np.greater(op, 1.0)): - raise ValueError("p > 1.0") - return vec_discd_array(self.internal_state, irk_geometric_vec, size, op, - self.lock) - - def hypergeometric(self, ngood, nbad, nsample, size=None): - """ - hypergeometric(ngood, nbad, nsample, size=None) - - Draw samples from a Hypergeometric distribution. - - Samples are drawn from a hypergeometric distribution with specified - parameters, ngood (ways to make a good selection), nbad (ways to make - a bad selection), and nsample = number of items sampled, which is less - than or equal to the sum ngood + nbad. - - Parameters - ---------- - ngood : int or array_like - Number of ways to make a good selection. Must be nonnegative. - nbad : int or array_like - Number of ways to make a bad selection. Must be nonnegative. - nsample : int or array_like - Number of items sampled. Must be at least 1 and at most - ``ngood + nbad``. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(d1, d2, d3)``, then - ``d1 * d2 * d3`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or scalar - The values are all integers in [0, n]. - - See Also - -------- - scipy.stats.distributions.hypergeom : probability density function, - distribution or cumulative density function, etc. - - Notes - ----- - The probability density for the Hypergeometric distribution is - - .. math:: P(x) = \\frac{\\binom{m}{x}\\binom{N-m}{n-x}}{\\binom{N}{n}}, - - where :math:`0 \\le x \\le m` and :math:`n+m-N \\le x \\le n` - - for P(x) the probability of x successes, m = ngood, N = ngood + nbad, and - n = number of samples. - - Consider an urn with black and white marbles in it, ngood of them - black and nbad are white. If you draw nsample balls without - replacement, then the hypergeometric distribution describes the - distribution of black balls in the drawn sample. - - Note that this distribution is very similar to the binomial - distribution, except that in this case, samples are drawn without - replacement, whereas in the Binomial case samples are drawn with - replacement (or the sample space is infinite). As the sample space - becomes large, this distribution approaches the binomial. - - References - ---------- - .. [1] Lentner, Marvin, "Elementary Applied Statistics", Bogden - and Quigley, 1972. - .. [2] Weisstein, Eric W. "Hypergeometric Distribution." From - MathWorld--A Wolfram Web Resource. - http://mathworld.wolfram.com/HypergeometricDistribution.html - .. [3] Wikipedia, "Hypergeometric-distribution", - http://en.wikipedia.org/wiki/Hypergeometric_distribution - - Examples - -------- - Draw samples from the distribution: - - >>> ngood, nbad, nsamp = 100, 2, 10 - # number of good, number of bad, and number of samples - >>> s = mkl_random.hypergeometric(ngood, nbad, nsamp, 1000) - >>> hist(s) - # note that it is very unlikely to grab both bad items - - Suppose you have an urn with 15 white and 15 black marbles. - If you pull 15 marbles at random, how likely is it that - 12 or more of them are one color? - - >>> s = mkl_random.hypergeometric(15, 15, 15, 100000) - >>> sum(s>=12)/100000. + sum(s<=3)/100000. - # answer = 0.003 ... pretty unlikely! - - """ - cdef ndarray ongood, onbad, onsample, otot - cdef long lngood, lnbad, lnsample, lntot - - lngood = PyInt_AsLong(ngood) - lnbad = PyInt_AsLong(nbad) - lnsample = PyInt_AsLong(nsample) - if not PyErr_Occurred(): - if lngood < 0: - raise ValueError("ngood < 0") - if lnbad < 0: - raise ValueError("nbad < 0") - if lnsample < 1: - raise ValueError("nsample < 1") - if (( lngood) != lngood) or (( lnbad) != lnbad) or (( lnsample) != lnsample): - raise ValueError("All parameters should not exceed 2147483647") - lntot = lngood + lnbad - if lntot < lnsample: - raise ValueError("ngood + nbad < nsample") - return vec_discnmN_array_sc(self.internal_state, irk_hypergeometric_vec, - size, lntot, lnsample, lngood, self.lock) - - PyErr_Clear() - - ongood = PyArray_FROM_OTF(ngood, NPY_LONG, NPY_ARRAY_IN_ARRAY) - onbad = PyArray_FROM_OTF(nbad, NPY_LONG, NPY_ARRAY_IN_ARRAY) - onsample = PyArray_FROM_OTF(nsample, NPY_LONG, NPY_ARRAY_IN_ARRAY) - if np.any(np.less(ongood, 0)): - raise ValueError("ngood < 0") - if np.any(np.less(onbad, 0)): - raise ValueError("nbad < 0") - if np.any(np.less(onsample, 1)): - raise ValueError("nsample < 1") - otot = np.asarray(np.add(ongood, onbad)); - if np.any(np.less_equal(otot, 0)): - raise ValueError("Number of balls in each urn should not exceed 2147483647") - if np.any(np.less(otot,onsample)): - raise ValueError("ngood + nbad < nsample") - - otot = otot.astype(np.int32, casting='unsafe') - onsample = onsample.astype(np.int32, casting='unsafe') - ongood = ongood.astype(np.int32, casting='unsafe') - return vec_discnmN_array(self.internal_state, irk_hypergeometric_vec, size, - otot, onsample, ongood, self.lock) - - def logseries(self, p, size=None): - """ - logseries(p, size=None) - - Draw samples from a logarithmic series distribution. - - Samples are drawn from a log series distribution with specified - shape parameter, 0 < ``p`` < 1. - - Parameters - ---------- - loc : float - - scale : float > 0. - - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray or scalar - where the values are all integers in [0, n]. - - See Also - -------- - scipy.stats.distributions.logser : probability density function, - distribution or cumulative density function, etc. - - Notes - ----- - The probability density for the Log Series distribution is - - .. math:: P(k) = \\frac{-p^k}{k \\ln(1-p)}, - - where p = probability. - - The log series distribution is frequently used to represent species - richness and occurrence, first proposed by Fisher, Corbet, and - Williams in 1943 [2]. It may also be used to model the numbers of - occupants seen in cars [3]. - - References - ---------- - .. [1] Buzas, Martin A.; Culver, Stephen J., Understanding regional - species diversity through the log series distribution of - occurrences: BIODIVERSITY RESEARCH Diversity & Distributions, - Volume 5, Number 5, September 1999 , pp. 187-195(9). - .. [2] Fisher, R.A,, A.S. Corbet, and C.B. Williams. 1943. The - relation between the number of species and the number of - individuals in a random sample of an animal population. - Journal of Animal Ecology, 12:42-58. - .. [3] D. J. Hand, F. Daly, D. Lunn, E. Ostrowski, A Handbook of Small - Data Sets, CRC Press, 1994. - .. [4] Wikipedia, "Logarithmic-distribution", - http://en.wikipedia.org/wiki/Logarithmic-distribution - - Examples - -------- - Draw samples from the distribution: - - >>> a = .6 - >>> s = mkl_random.logseries(a, 10000) - >>> count, bins, ignored = plt.hist(s) - - # plot against distribution - - >>> def logseries(k, p): - ... return -p**k/(k*log(1-p)) - >>> plt.plot(bins, logseries(bins, a)*count.max()/ - logseries(bins, a).max(), 'r') - >>> plt.show() - - """ - cdef ndarray op - cdef double fp - - fp = PyFloat_AsDouble(p) - if not PyErr_Occurred(): - if fp <= 0.0: - raise ValueError("p <= 0.0") - if fp >= 1.0: - raise ValueError("p >= 1.0") - return vec_discd_array_sc(self.internal_state, irk_logseries_vec, size, fp, - self.lock) - - PyErr_Clear() - - op = PyArray_FROM_OTF(p, NPY_DOUBLE, NPY_ARRAY_ALIGNED) - if np.any(np.less_equal(op, 0.0)): - raise ValueError("p <= 0.0") - if np.any(np.greater_equal(op, 1.0)): - raise ValueError("p >= 1.0") - return vec_discd_array(self.internal_state, irk_logseries_vec, size, op, - self.lock) - - # Multivariate distributions: - def multivariate_normal(self, mean, cov, size=None): - """ - multivariate_normal(mean, cov[, size]) - - Draw random samples from a multivariate normal distribution. - - The multivariate normal, multinormal or Gaussian distribution is a - generalization of the one-dimensional normal distribution to higher - dimensions. Such a distribution is specified by its mean and - covariance matrix. These parameters are analogous to the mean - (average or "center") and variance (standard deviation, or "width," - squared) of the one-dimensional normal distribution. - - Parameters - ---------- - mean : 1-D array_like, of length N - Mean of the N-dimensional distribution. - cov : 2-D array_like, of shape (N, N) - Covariance matrix of the distribution. It must be symmetric and - positive-semidefinite for proper sampling. - size : int or tuple of ints, optional - Given a shape of, for example, ``(m,n,k)``, ``m*n*k`` samples are - generated, and packed in an `m`-by-`n`-by-`k` arrangement. Because - each sample is `N`-dimensional, the output shape is ``(m,n,k,N)``. - If no shape is specified, a single (`N`-D) sample is returned. - - Returns - ------- - out : ndarray - The drawn samples, of shape *size*, if that was provided. If not, - the shape is ``(N,)``. - - In other words, each entry ``out[i,j,...,:]`` is an N-dimensional - value drawn from the distribution. - - Notes - ----- - The mean is a coordinate in N-dimensional space, which represents the - location where samples are most likely to be generated. This is - analogous to the peak of the bell curve for the one-dimensional or - univariate normal distribution. - - Covariance indicates the level to which two variables vary together. - From the multivariate normal distribution, we draw N-dimensional - samples, :math:`X = [x_1, x_2, ... x_N]`. The covariance matrix - element :math:`C_{ij}` is the covariance of :math:`x_i` and :math:`x_j`. - The element :math:`C_{ii}` is the variance of :math:`x_i` (i.e. its - "spread"). - - Instead of specifying the full covariance matrix, popular - approximations include: - - - Spherical covariance (*cov* is a multiple of the identity matrix) - - Diagonal covariance (*cov* has non-negative elements, and only on - the diagonal) - - This geometrical property can be seen in two dimensions by plotting - generated data-points: - - >>> mean = [0, 0] - >>> cov = [[1, 0], [0, 100]] # diagonal covariance - - Diagonal covariance means that points are oriented along x or y-axis: - - >>> import matplotlib.pyplot as plt - >>> x, y = mkl_random.multivariate_normal(mean, cov, 5000).T - >>> plt.plot(x, y, 'x') - >>> plt.axis('equal') - >>> plt.show() - - Note that the covariance matrix must be positive semidefinite (a.k.a. - nonnegative-definite). Otherwise, the behavior of this method is - undefined and backwards compatibility is not guaranteed. - - References - ---------- - .. [1] Papoulis, A., "Probability, Random Variables, and Stochastic - Processes," 3rd ed., New York: McGraw-Hill, 1991. - .. [2] Duda, R. O., Hart, P. E., and Stork, D. G., "Pattern - Classification," 2nd ed., New York: Wiley, 2001. - - Examples - -------- - >>> mean = (1, 2) - >>> cov = [[1, 0], [0, 1]] - >>> x = mkl_random.multivariate_normal(mean, cov, (3, 3)) - >>> x.shape - (3, 3, 2) - - The following is probably true, given that 0.6 is roughly twice the - standard deviation: - - >>> list((x[0,0,:] - mean) < 0.6) - [True, True] - - """ - from numpy.linalg import svd - - # Check preconditions on arguments - mean = np.array(mean) - cov = np.array(cov) - if size is None: - shape = [] - elif isinstance(size, (int, long, np.integer)): - shape = [size] - else: - shape = size - - if len(mean.shape) != 1: - raise ValueError("mean must be 1 dimensional") - if (len(cov.shape) != 2) or (cov.shape[0] != cov.shape[1]): - raise ValueError("cov must be 2 dimensional and square") - if mean.shape[0] != cov.shape[0]: - raise ValueError("mean and cov must have same length") - - # Compute shape of output and create a matrix of independent - # standard normally distributed random numbers. The matrix has rows - # with the same length as mean and as many rows are necessary to - # form a matrix of shape final_shape. - final_shape = list(shape[:]) - final_shape.append(mean.shape[0]) - x = self.standard_normal(final_shape).reshape(-1, mean.shape[0]) - - # Transform matrix of standard normals into matrix where each row - # contains multivariate normals with the desired covariance. - # Compute A such that dot(transpose(A),A) == cov. - # Then the matrix products of the rows of x and A has the desired - # covariance. Note that sqrt(s)*v where (u,s,v) is the singular value - # decomposition of cov is such an A. - # - # Also check that cov is positive-semidefinite. If so, the u.T and v - # matrices should be equal up to roundoff error if cov is - # symmetrical and the singular value of the corresponding row is - # not zero. We continue to use the SVD rather than Cholesky in - # order to preserve current outputs. Note that symmetry has not - # been checked. - (u, s, v) = svd(cov) - neg = (np.sum(u.T * v, axis=1) < 0) & (s > 0) - if np.any(neg): - s[neg] = 0. - warnings.warn("covariance is not positive-semidefinite.", - RuntimeWarning) - - x = np.dot(x, np.sqrt(s)[:, None] * v) - x += mean - x.shape = tuple(final_shape) - return x - - def multinormal_cholesky(self, mean, ch, size=None, method=ICDF): - """ - multivariate_normal(mean, ch, size=None, method='ICDF') - - Draw random samples from a multivariate normal distribution. - - The multivariate normal, multinormal or Gaussian distribution is a - generalization of the one-dimensional normal distribution to higher - dimensions. Such a distribution is specified by its mean and - covariance matrix, specified by its lower triangular Cholesky factor. - These parameters are analogous to the mean - (average or "center") and standard deviation, or "width," - of the one-dimensional normal distribution. - - Parameters - ---------- - mean : 1-D array_like, of length N - Mean of the N-dimensional distribution. - ch : 2-D array_like, of shape (N, N) - Cholesky factor of the covariance matrix of the distribution. Only lower-triangular - part of the matrix is actually used. - size : int or tuple of ints, optional - Given a shape of, for example, ``(m,n,k)``, ``m*n*k`` samples are - generated, and packed in an `m`-by-`n`-by-`k` arrangement. Because - each sample is `N`-dimensional, the output shape is ``(m,n,k,N)``. - If no shape is specified, a single (`N`-D) sample is returned. - method : 'ICDF, 'BoxMuller', 'BoxMuller2', optional - Sampling method used by Intel MKL. Can also be specified using - tokens mkl_random.ICDF, mkl_random.BOXMULLER, mkl_random.BOXMULLER2 - - Returns - ------- - out : ndarray - The drawn samples, of shape *size*, if that was provided. If not, - the shape is ``(N,)``. - - In other words, each entry ``out[i,j,...,:]`` is an N-dimensional - value drawn from the distribution. - - Notes - ----- - The mean is a coordinate in N-dimensional space, which represents the - location where samples are most likely to be generated. This is - analogous to the peak of the bell curve for the one-dimensional or - univariate normal distribution. - - Covariance indicates the level to which two variables vary together. - From the multivariate normal distribution, we draw N-dimensional - samples, :math:`X = [x_1, x_2, ... x_N]`. The covariance matrix - element :math:`C_{ij}` is the covariance of :math:`x_i` and :math:`x_j`. - The element :math:`C_{ii}` is the variance of :math:`x_i` (i.e. its - "spread"). - - Instead of specifying the full covariance matrix, popular - approximations include: - - - Spherical covariance (*cov* is a multiple of the identity matrix) - - Diagonal covariance (*cov* has non-negative elements, and only on - the diagonal) - - This geometrical property can be seen in two dimensions by plotting - generated data-points: - - >>> mean = [0, 0] - >>> cov = [[1, 0], [0, 100]] # diagonal covariance - - Diagonal covariance means that points are oriented along x or y-axis: - - >>> import matplotlib.pyplot as plt - >>> x, y = mkl_random.multivariate_normal(mean, cov, 5000).T - >>> plt.plot(x, y, 'x') - >>> plt.axis('equal') - >>> plt.show() - - Note that the covariance matrix must be positive semidefinite (a.k.a. - nonnegative-definite). Otherwise, the behavior of this method is - undefined and backwards compatibility is not guaranteed. - - References - ---------- - .. [1] Papoulis, A., "Probability, Random Variables, and Stochastic - Processes," 3rd ed., New York: McGraw-Hill, 1991. - .. [2] Duda, R. O., Hart, P. E., and Stork, D. G., "Pattern - Classification," 2nd ed., New York: Wiley, 2001. - - Examples - -------- - >>> mean = (1, 2) - >>> cov = [[1, 0], [0, 1]] - >>> x = mkl_random.multivariate_normal(mean, cov, (3, 3)) - >>> x.shape - (3, 3, 2) - - The following is probably true, given that 0.6 is roughly twice the - standard deviation: - - >>> list((x[0,0,:] - mean) < 0.6) - [True, True] - - """ - cdef ndarray resarr "arrayObject_resarr" - cdef ndarray marr "arrayObject_marr" - cdef ndarray tarr "arrayObject_tarr" - cdef double *res_data - cdef double *mean_data - cdef double *t_data - cdef npy_intp dim, n - cdef ch_st_enum storage_mode - - # Check preconditions on arguments - marr = PyArray_FROM_OTF(mean, NPY_DOUBLE, NPY_ARRAY_IN_ARRAY) - tarr = PyArray_FROM_OTF(ch, NPY_DOUBLE, NPY_ARRAY_IN_ARRAY) - - if size is None: - shape = [] - elif isinstance(size, (int, long, np.integer)): - shape = [size] - else: - shape = size - - if marr.ndim != 1: - raise ValueError("mean must be 1 dimensional") - dim = marr.shape[0]; - if (tarr.ndim == 2): - storage_mode = MATRIX - if (tarr.shape[0] != tarr.shape[1]): - raise ValueError("ch must be a square lower triangular 2-dimensional array or a row-packed one-dimensional representation of such") - if dim != tarr.shape[0]: - raise ValueError("mean and ch must have consistent shapes") - elif (tarr.ndim == 1): - if (tarr.shape[0] == dim): - storage_mode = DIAGONAL - elif (tarr.shape[0] == packed_cholesky_size(dim)): - storage_mode = PACKED - else: - raise ValueError("ch must be a square lower triangular 2-dimensional array or a row-packed one-dimensional representation of such") - else: - raise ValueError("ch must be a square lower triangular 2-dimensional array or a row-packed one-dimensional representation of such") - - # Compute shape of output and create a matrix of independent - # standard normally distributed random numbers. The matrix has rows - # with the same length as mean and as many rows are necessary to - # form a matrix of shape final_shape. - final_shape = list(shape[:]) - final_shape.append(int(dim)) - - resarr = np.empty(final_shape, np.float64) - res_data = PyArray_DATA(resarr) - mean_data = PyArray_DATA(marr) - t_data = PyArray_DATA(tarr) - - n = PyArray_SIZE(resarr) // dim - - method = choose_method(method, [ICDF, BOXMULLER2, BOXMULLER], _method_alias_dict_gaussian) - if (method is ICDF): - irk_multinormal_vec_ICDF(self.internal_state, n, res_data, dim, mean_data, t_data, storage_mode) - elif (method is BOXMULLER2): - irk_multinormal_vec_BM2(self.internal_state, n, res_data, dim, mean_data, t_data, storage_mode) - else: - irk_multinormal_vec_BM1(self.internal_state, n, res_data, dim, mean_data, t_data, storage_mode) - - return resarr - - def multinomial(self, int n, object pvals, size=None): - """ - multinomial(n, pvals, size=None, method='ICDF') - - Draw samples from a multinomial distribution. - - The multinomial distribution is a multivariate generalisation of the - binomial distribution. Take an experiment with one of ``p`` - possible outcomes. An example of such an experiment is throwing a dice, - where the outcome can be 1 through 6. Each sample drawn from the - distribution represents `n` such experiments. Its values, - ``X_i = [X_0, X_1, ..., X_p]``, represent the number of times the - outcome was ``i``. - - Parameters - ---------- - n : int - Number of experiments. - pvals : sequence of floats, length p - Probabilities of each of the ``p`` different outcomes. These - should sum to 1 (however, the last element is always assumed to - account for the remaining probability, as long as - ``sum(pvals[:-1]) <= 1)``. - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - method : 'ICDF, 'BoxMuller', 'BoxMuller2', optional - Sampling method used by Intel MKL. Can also be specified using - tokens mkl_random.ICDF, mkl_random.BOXMULLER, mkl_random.BOXMULLER2 - - Returns - ------- - out : ndarray - The drawn samples, of shape *size*, if that was provided. If not, - the shape is ``(N,)``. - - In other words, each entry ``out[i,j,...,:]`` is an N-dimensional - value drawn from the distribution. - - Examples - -------- - Throw a dice 20 times: - - >>> mkl_random.multinomial(20, [1/6.]*6, size=1) - array([[4, 1, 7, 5, 2, 1]]) - - It landed 4 times on 1, once on 2, etc. - - Now, throw the dice 20 times, and 20 times again: - - >>> mkl_random.multinomial(20, [1/6.]*6, size=2) - array([[3, 4, 3, 3, 4, 3], - [2, 4, 3, 4, 0, 7]]) - - For the first run, we threw 3 times 1, 4 times 2, etc. For the second, - we threw 2 times 1, 4 times 2, etc. - - A loaded die is more likely to land on number 6: - - >>> mkl_random.multinomial(100, [1/7.]*5 + [2./7.]) - array([11, 16, 14, 17, 16, 26]) - - The probability inputs should be normalized. As an implementation - detail, the value of the last entry is ignored and assumed to take - up any leftover probability mass, but this should not be relied on. - A biased coin which has twice as much weight on one side as on the - other should be sampled like so: - - >>> mkl_random.multinomial(100, [1.0 / 3, 2.0 / 3]) # RIGHT - array([38, 62]) - - not like: - - >>> mkl_random.multinomial(100, [1.0, 2.0]) # WRONG - array([100, 0]) - - """ - cdef npy_intp d - cdef ndarray parr "arrayObject_parr", mnarr "arrayObject_mnarr" - cdef double *pix - cdef int *mnix - cdef npy_intp i, j, sz - cdef double Sum - cdef int dn - - d = len(pvals) - parr = PyArray_ContiguousFromObject(pvals, NPY_DOUBLE, 1, 1) - pix = PyArray_DATA(parr) - - if kahan_sum(pix, d-1) > (1.0 + 1e-12): - raise ValueError("sum(pvals[:-1]) > 1.0") - - shape = _shape_from_size(size, d) - multin = np.zeros(shape, np.int32) - - mnarr = multin - mnix = PyArray_DATA(mnarr) - sz = PyArray_SIZE(mnarr) - - irk_multinomial_vec(self.internal_state, sz // d, mnix, n, d, pix) - - return multin - - - def dirichlet(self, object alpha, size=None): - """ - dirichlet(alpha, size=None) - - Draw samples from the Dirichlet distribution. - - Draw `size` samples of dimension k from a Dirichlet distribution. A - Dirichlet-distributed random variable can be seen as a multivariate - generalization of a Beta distribution. Dirichlet pdf is the conjugate - prior of a multinomial in Bayesian inference. - - Parameters - ---------- - alpha : array - Parameter of the distribution (k dimension for sample of - dimension k). - size : int or tuple of ints, optional - Output shape. If the given shape is, e.g., ``(m, n, k)``, then - ``m * n * k`` samples are drawn. Default is None, in which case a - single value is returned. - - Returns - ------- - samples : ndarray, - The drawn samples, of shape (size, alpha.ndim). - - Notes - ----- - .. math:: X \\approx \\prod_{i=1}^{k}{x^{\\alpha_i-1}_i} - - Uses the following property for computation: for each dimension, - draw a random sample y_i from a standard gamma generator of shape - `alpha_i`, then - :math:`X = \\frac{1}{\\sum_{i=1}^k{y_i}} (y_1, \\ldots, y_n)` is - Dirichlet distributed. - - References - ---------- - .. [1] David McKay, "Information Theory, Inference and Learning - Algorithms," chapter 23, - http://www.inference.phy.cam.ac.uk/mackay/ - .. [2] Wikipedia, "Dirichlet distribution", - http://en.wikipedia.org/wiki/Dirichlet_distribution - - Examples - -------- - Taking an example cited in Wikipedia, this distribution can be used if - one wanted to cut strings (each of initial length 1.0) into K pieces - with different lengths, where each piece had, on average, a designated - average length, but allowing some variation in the relative sizes of - the pieces. - - >>> s = mkl_random.dirichlet((10, 5, 3), 20).transpose() - - >>> plt.barh(range(20), s[0]) - >>> plt.barh(range(20), s[1], left=s[0], color='g') - >>> plt.barh(range(20), s[2], left=s[0]+s[1], color='r') - >>> plt.title("Lengths of Strings") - - """ - #================= - # Pure python algo - #================= - #alpha = N.atleast_1d(alpha) - #k = alpha.size - - #if n == 1: - # val = N.zeros(k) - # for i in range(k): - # val[i] = sgamma(alpha[i], n) - # val /= N.sum(val) - #else: - # val = N.zeros((k, n)) - # for i in range(k): - # val[i] = sgamma(alpha[i], n) - # val /= N.sum(val, axis = 0) - # val = val.T - - #return val - cdef npy_intp k - cdef npy_intp totsize - cdef ndarray alpha_arr, val_arr - cdef double *alpha_data - cdef double *val_data - cdef npy_intp i, j - cdef double invacc, acc - cdef broadcast multi1, multi2 - - alpha_arr = PyArray_FROM_OTF(alpha, NPY_DOUBLE, NPY_ARRAY_ALIGNED); - if (alpha_arr.ndim != 1): - raise ValueError("Parameter alpha is not a vector") - - k = len(alpha) - shape = _shape_from_size(size, k) - - diric = self.standard_gamma(alpha_arr, shape) - - val_arr = diric - totsize = PyArray_SIZE(val_arr) - - # Use of iterators is faster than calling PyArray_ContiguousFromObject and iterating in C - multi1 = PyArray_MultiIterNew(2, val_arr, alpha_arr); - multi2 = PyArray_MultiIterNew(2, val_arr, alpha_arr); - - i = 0 - with self.lock, nogil: - while i < totsize: - acc = 0.0 - for j from 0 <= j < k: - val_data = PyArray_MultiIter_DATA(multi1, 0) - acc += val_data[0] - PyArray_MultiIter_NEXTi(multi1, 0) - invacc = 1.0/acc; - for j from 0 <= j < k: - val_data = PyArray_MultiIter_DATA(multi2, 0); - val_data[0] *= invacc - PyArray_MultiIter_NEXTi(multi2, 0) - i += k - - return diric - - # Shuffling and permutations: - def shuffle(self, object x): - """ - shuffle(x) - - Modify a sequence in-place by shuffling its contents. - - Parameters - ---------- - x : array_like - The array or list to be shuffled. - - Returns - ------- - None - - Examples - -------- - >>> arr = np.arange(10) - >>> mkl_random.shuffle(arr) - >>> arr - [1 7 5 2 9 4 3 6 0 8] - - This function only shuffles the array along the first index of a - multi-dimensional array: - - >>> arr = np.arange(9).reshape((3, 3)) - >>> mkl_random.shuffle(arr) - >>> arr - array([[3, 4, 5], - [6, 7, 8], - [0, 1, 2]]) - - """ - cdef: - npy_intp i, j, n = len(x), stride, itemsize - char* x_ptr - char* buf_ptr - cdef ndarray u "arrayObject_u" - cdef double *u_data - - if (n == 0): - return - - u = self.random_sample(n-1) - u_data = PyArray_DATA(u) - - if type(x) is np.ndarray and x.ndim == 1 and x.size: - # Fast, statically typed path: shuffle the underlying buffer. - # Only for non-empty, 1d objects of class ndarray (subclasses such - # as MaskedArrays may not support this approach). - x_ptr = x.ctypes.data - stride = x.strides[0] - itemsize = x.dtype.itemsize - # As the array x could contain python objects we use a buffer - # of bytes for the swaps to avoid leaving one of the objects - # within the buffer and erroneously decrementing it's refcount - # when the function exits. - buf = np.empty(itemsize, dtype=np.int8) # GC'd at function exit - buf_ptr = buf.ctypes.data - with self.lock: - # We trick gcc into providing a specialized implementation for - # the most common case, yielding a ~33% performance improvement. - # Note that apparently, only one branch can ever be specialized. - if itemsize == sizeof(npy_intp): - self._shuffle_raw(n, sizeof(npy_intp), stride, x_ptr, buf_ptr, u_data) - else: - self._shuffle_raw(n, itemsize, stride, x_ptr, buf_ptr, u_data) - elif isinstance(x, np.ndarray) and x.ndim > 1 and x.size: - # Multidimensional ndarrays require a bounce buffer. - buf = np.empty_like(x[0]) - with self.lock: - for i in reversed(range(1, n)): - j = floor( (i + 1) * u_data[i - 1]) - if (j < i): - buf[...] = x[j] - x[j] = x[i] - x[i] = buf - else: - # Untyped path. - with self.lock: - for i in reversed(range(1, n)): - j = floor( (i + 1) * u_data[i - 1]) - x[i], x[j] = x[j], x[i] - - cdef inline _shuffle_raw(self, npy_intp n, npy_intp itemsize, - npy_intp stride, char* data, char* buf, double* udata): - cdef npy_intp i, j - for i in reversed(range(1, n)): - j = floor( (i + 1) * udata[i - 1]) - memcpy(buf, data + j * stride, itemsize) - memcpy(data + j * stride, data + i * stride, itemsize) - memcpy(data + i * stride, buf, itemsize) - - def permutation(self, object x): - """ - permutation(x) - - Randomly permute a sequence, or return a permuted range. - - If `x` is a multi-dimensional array, it is only shuffled along its - first index. - - Parameters - ---------- - x : int or array_like - If `x` is an integer, randomly permute ``np.arange(x)``. - If `x` is an array, make a copy and shuffle the elements - randomly. - - Returns - ------- - out : ndarray - Permuted sequence or array range. - - Examples - -------- - >>> mkl_random.permutation(10) - array([1, 7, 4, 3, 0, 9, 2, 5, 8, 6]) - - >>> mkl_random.permutation([1, 4, 9, 12, 15]) - array([15, 1, 9, 4, 12]) - - >>> arr = np.arange(9).reshape((3, 3)) - >>> mkl_random.permutation(arr) - array([[6, 7, 8], - [0, 1, 2], - [3, 4, 5]]) - - """ - if isinstance(x, (int, long, np.integer)): - arr = np.arange(x) - else: - arr = np.array(x) - self.shuffle(arr) - return arr - - -def __RandomState_ctor(): - """Return a RandomState instance. - This function exists solely to assist (un)pickling. - Note that the state of the RandomState returned here is irrelevant, as this function's - entire purpose is to return a newly allocated RandomState whose state pickle can set. - Consequently the RandomState returned by this function is a freshly allocated copy - with a seed=0. - See https://github.com/numpy/numpy/issues/4763 for a detailed discussion - """ - return RandomState(seed=0) - -_rand = RandomState() -seed = _rand.seed -get_state = _rand.get_state -set_state = _rand.set_state -random_sample = _rand.random_sample -choice = _rand.choice -randint = _rand.randint -bytes = _rand.bytes -uniform = _rand.uniform -rand = _rand.rand -randn = _rand.randn -random_integers = _rand.random_integers -standard_normal = _rand.standard_normal -normal = _rand.normal -beta = _rand.beta -exponential = _rand.exponential -standard_exponential = _rand.standard_exponential -standard_gamma = _rand.standard_gamma -gamma = _rand.gamma -f = _rand.f -noncentral_f = _rand.noncentral_f -chisquare = _rand.chisquare -noncentral_chisquare = _rand.noncentral_chisquare -standard_cauchy = _rand.standard_cauchy -standard_t = _rand.standard_t -vonmises = _rand.vonmises -pareto = _rand.pareto -weibull = _rand.weibull -power = _rand.power -laplace = _rand.laplace -gumbel = _rand.gumbel -logistic = _rand.logistic -lognormal = _rand.lognormal -rayleigh = _rand.rayleigh -wald = _rand.wald -triangular = _rand.triangular - -binomial = _rand.binomial -negative_binomial = _rand.negative_binomial -poisson = _rand.poisson -zipf = _rand.zipf -geometric = _rand.geometric -hypergeometric = _rand.hypergeometric -logseries = _rand.logseries - -multivariate_normal = _rand.multivariate_normal -multinormal_cholesky = _rand.multinormal_cholesky -multinomial = _rand.multinomial -dirichlet = _rand.dirichlet - -shuffle = _rand.shuffle -permutation = _rand.permutation diff --git a/mkl_random/src/.gitignore b/mkl_random/src/.gitignore deleted file mode 100644 index 2174c73..0000000 --- a/mkl_random/src/.gitignore +++ /dev/null @@ -1 +0,0 @@ -mklrand.c diff --git a/mkl_random/src/generate_mklrand_c.py b/mkl_random/src/generate_mklrand_c.py deleted file mode 100644 index bb6fd20..0000000 --- a/mkl_random/src/generate_mklrand_c.py +++ /dev/null @@ -1,42 +0,0 @@ -#!/usr/bin/env python -from __future__ import division, absolute_import, print_function - -import sys -import re -import os - -unused_internal_funcs = ['__Pyx_PrintItem', - '__Pyx_PrintNewline', - '__Pyx_ReRaise', - #'__Pyx_GetExcValue', - '__Pyx_ArgTypeTest', - '__Pyx_SetVtable', - '__Pyx_GetVtable', - '__Pyx_CreateClass'] - -if __name__ == '__main__': - # Use cython here so that long docstrings are broken up. - # This is needed for some VC++ compilers. - os.system('cython mklrand.pyx') - mklrand_c = open('mklrand.c', 'r') - processed = open('mklrand_pp.c', 'w') - unused_funcs_str = '(' + '|'.join(unused_internal_funcs) + ')' - uifpat = re.compile(r'static \w+ \*?'+unused_funcs_str+r'.*/\*proto\*/') - linepat = re.compile(r'/\* ".*/mklrand.pyx":') - for linenum, line in enumerate(mklrand_c): - m = re.match(r'^(\s+arrayObject\w*\s*=\s*[(])[(]PyObject\s*[*][)]', - line) - if m: - line = '%s(PyArrayObject *)%s' % (m.group(1), line[m.end():]) - m = uifpat.match(line) - if m: - line = '' - m = re.search(unused_funcs_str, line) - if m: - print("%s was declared unused, but is used at line %d" % (m.group(), - linenum+1), file=sys.stderr) - line = linepat.sub(r'/* "mklrand.pyx":', line) - processed.write(line) - mklrand_c.close() - processed.close() - os.rename('mklrand_pp.c', 'mklrand.c') diff --git a/mkl_random/src/mkl_distributions.cpp b/mkl_random/src/mkl_distributions.cpp deleted file mode 100644 index 38be263..0000000 --- a/mkl_random/src/mkl_distributions.cpp +++ /dev/null @@ -1,2057 +0,0 @@ -/* - Copyright (c) 2017-2021, Intel Corporation - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - * Neither the name of Intel Corporation nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER - CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - */ - -#include /* for nullptr */ -#include /* for ULONG_MAX */ -#include -#include /* fmod, fabs */ -#include /* expm1 */ -#include /* std::sort */ - -#include "mkl.h" -#include "mkl_vml.h" -#include "mkl_distributions.h" -#include "Python.h" -#include "numpy/npy_common.h" /* npy_intp */ - -#define MKL_INT_MAX ((npy_intp)(~((MKL_UINT)0) >> 1)) - -#if defined(__ICC) || defined(__INTEL_COMPILER) -#define DIST_PRAGMA_VECTOR _Pragma("vector") -#define DIST_PRAGMA_NOVECTOR _Pragma("novector") -#define DIST_ASSUME_ALIGNED(p, b) __assume_aligned((p), (b)); -#elif defined(__clang__) -#define DIST_PRAGMA_VECTOR _Pragma("clang loop vectorize(enable)") -#define DIST_PRAGMA_NOVECTOR _Pragma("clang loop vectorize(disable)") -#define DIST_ASSUME_ALIGNED(p, b) -#elif defined(__GNUG__) -#define DIST_PRAGMA_VECTOR _Pragma("GCC ivdep") -#define DIST_PRAGMA_NOVECTOR -#define DIST_ASSUME_ALIGNED(p, b) -#else -#define DIST_PRAGMA_VECTOR -#define DIST_PRAGMA_NOVECTOR -#define DIST_ASSUME_ALIGNED(p, b) -#endif - -void irk_double_vec(irk_state *state, npy_intp len, double *res) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, MKL_INT_MAX, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, len, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); -} - -void irk_uniform_vec(irk_state *state, npy_intp len, double *res, const double low, const double high) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, MKL_INT_MAX, res, low, high); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, len, res, low, high); - assert(err == VSL_STATUS_OK); -} - -void irk_standard_normal_vec_ICDF(irk_state *state, npy_intp len, double *res) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_ICDF, state->stream, MKL_INT_MAX, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_ICDF, state->stream, len, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); -} - -void irk_normal_vec_ICDF(irk_state *state, npy_intp len, double *res, const double loc, const double scale) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_ICDF, state->stream, MKL_INT_MAX, res, loc, scale); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_ICDF, state->stream, len, res, loc, scale); - assert(err == VSL_STATUS_OK); -} - -void irk_standard_normal_vec_BM1(irk_state *state, npy_intp len, double *res) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_BOXMULLER, state->stream, MKL_INT_MAX, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_BOXMULLER, state->stream, len, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); -} - -void irk_normal_vec_BM1(irk_state *state, npy_intp len, double *res, const double loc, const double scale) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_BOXMULLER, state->stream, MKL_INT_MAX, res, loc, scale); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_BOXMULLER, state->stream, len, res, loc, scale); - assert(err == VSL_STATUS_OK); -} - -void irk_standard_normal_vec_BM2(irk_state *state, npy_intp len, double *res) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_BOXMULLER2, state->stream, MKL_INT_MAX, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_BOXMULLER2, state->stream, len, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); -} - -void irk_normal_vec_BM2(irk_state *state, npy_intp len, double *res, const double loc, const double scale) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_BOXMULLER2, state->stream, MKL_INT_MAX, res, loc, scale); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_BOXMULLER2, state->stream, len, res, loc, scale); - assert(err == VSL_STATUS_OK); -} - -void irk_standard_exponential_vec(irk_state *state, npy_intp len, double *res) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngExponential(VSL_RNG_METHOD_EXPONENTIAL_ICDF_ACCURATE, state->stream, MKL_INT_MAX, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngExponential(VSL_RNG_METHOD_EXPONENTIAL_ICDF_ACCURATE, state->stream, len, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); -} - -void irk_exponential_vec(irk_state *state, npy_intp len, double *res, const double scale) -{ - int err = 0; - const double d_zero = 0.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngExponential(VSL_RNG_METHOD_EXPONENTIAL_ICDF_ACCURATE, state->stream, MKL_INT_MAX, res, d_zero, scale); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngExponential(VSL_RNG_METHOD_EXPONENTIAL_ICDF_ACCURATE, state->stream, len, res, d_zero, scale); - assert(err == VSL_STATUS_OK); -} - -void irk_standard_cauchy_vec(irk_state *state, npy_intp len, double *res) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngCauchy(VSL_RNG_METHOD_CAUCHY_ICDF, state->stream, MKL_INT_MAX, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngCauchy(VSL_RNG_METHOD_CAUCHY_ICDF, state->stream, len, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); -} - -void irk_standard_gamma_vec(irk_state *state, npy_intp len, double *res, const double shape) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngGamma(VSL_RNG_METHOD_GAMMA_GNORM_ACCURATE, state->stream, MKL_INT_MAX, res, shape, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGamma(VSL_RNG_METHOD_GAMMA_GNORM_ACCURATE, state->stream, len, res, shape, d_zero, d_one); - assert(err == VSL_STATUS_OK); -} - -void irk_gamma_vec(irk_state *state, npy_intp len, double *res, const double shape, const double scale) -{ - int err = 0; - const double d_zero = 0.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngGamma(VSL_RNG_METHOD_GAMMA_GNORM_ACCURATE, state->stream, MKL_INT_MAX, res, shape, d_zero, scale); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGamma(VSL_RNG_METHOD_GAMMA_GNORM_ACCURATE, state->stream, len, res, shape, d_zero, scale); - assert(err == VSL_STATUS_OK); -} - -/* X ~ Z * (G*(2/df))**-0.5 */ -void irk_standard_t_vec(irk_state *state, npy_intp len, double *res, const double df) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - double shape = df / 2; - double *sn = nullptr; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_standard_t_vec(state, MKL_INT_MAX, res, df); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGamma(VSL_RNG_METHOD_GAMMA_GNORM_ACCURATE, state->stream, len, res, shape, d_zero, 1.0 / shape); - assert(err == VSL_STATUS_OK); - - vmdInvSqrt(len, res, res, VML_HA); - - sn = (double *)mkl_malloc(len * sizeof(double), 64); - assert(sn != nullptr); - - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_ICDF, state->stream, len, sn, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - vmdMul(len, res, sn, res, VML_HA); - mkl_free(sn); -} - -/* chisquare(df) ~ G(df/2, 2) */ -void irk_chisquare_vec(irk_state *state, npy_intp len, double *res, const double df) -{ - int err = 0; - const double d_zero = 0.0, d_two = 2.0; - double shape = 0.5 * df; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_chisquare_vec(state, MKL_INT_MAX, res, df); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGamma(VSL_RNG_METHOD_GAMMA_GNORM_ACCURATE, state->stream, len, res, shape, d_zero, d_two); - assert(err == VSL_STATUS_OK); -} - -/* P ~ U^(-1/a) - 1 = */ -void irk_pareto_vec(irk_state *state, npy_intp len, double *res, const double alp) -{ - int err = 0; - npy_intp i = 0; - const double d_zero = 0.0, d_one = 1.0; - double neg_rec_alp = -1.0 / alp; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_pareto_vec(state, MKL_INT_MAX, res, alp); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, len, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - /* res[i] = pow(res[i], neg_rec_alp) */ - vmdPowx(len, res, neg_rec_alp, res, VML_HA); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] -= 1.0; -} - -/* W ~ E^(1/alp) */ -void irk_weibull_vec(irk_state *state, npy_intp len, double *res, const double alp) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - double rec_alp = 1.0 / alp; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_weibull_vec(state, MKL_INT_MAX, res, alp); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngExponential(VSL_RNG_METHOD_EXPONENTIAL_ICDF_ACCURATE, state->stream, len, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - vmdPowx(len, res, rec_alp, res, VML_HA); -} - -/* pow(1 - exp(-E(1))), 1./a) == pow(U, 1./a) */ -void irk_power_vec(irk_state *state, npy_intp len, double *res, const double alp) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - double rec_alp = 1.0 / alp; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_power_vec(state, MKL_INT_MAX, res, alp); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, len, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - /* res[i] = pow(res[i], rec_alp) */ - vmdPowx(len, res, rec_alp, res, VML_HA); -} - -/* scale * sqrt(2.0 * E(1)) */ -void irk_rayleigh_vec(irk_state *state, npy_intp len, double *res, const double scale) -{ - int err = 0; - npy_intp i = 0; - const double d_zero = 0.0, d_two = 2.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_rayleigh_vec(state, MKL_INT_MAX, res, scale); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngExponential(VSL_RNG_METHOD_EXPONENTIAL_ICDF_ACCURATE, state->stream, len, res, d_zero, d_two); - assert(err == VSL_STATUS_OK); - - vmdSqrt(len, res, res, VML_HA); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] *= scale; -} - -void irk_beta_vec(irk_state *state, npy_intp len, double *res, const double a, const double b) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngBeta(VSL_RNG_METHOD_BETA_CJA_ACCURATE, state->stream, MKL_INT_MAX, res, a, b, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngBeta(VSL_RNG_METHOD_BETA_CJA_ACCURATE, state->stream, len, res, a, b, d_zero, d_one); - assert(err == VSL_STATUS_OK); -} - -/* F(df_num, df_den) ~ G( df_num/2, 2/df_num) / G(df_den/2, 2/df_den)) */ -void irk_f_vec(irk_state *state, npy_intp len, double *res, const double df_num, const double df_den) -{ - int err = 0; - const double d_zero = 0.0; - double shape = 0.5 * df_num, scale = 2.0 / df_num; - double *den = nullptr; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_f_vec(state, MKL_INT_MAX, res, df_num, df_den); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGamma(VSL_RNG_METHOD_GAMMA_GNORM_ACCURATE, state->stream, len, res, shape, d_zero, scale); - assert(err == VSL_STATUS_OK); - - den = (double *)mkl_malloc(len * sizeof(double), 64); - assert(den != nullptr); - - shape = 0.5 * df_den; - scale = 2.0 / df_den; - err = vdRngGamma(VSL_RNG_METHOD_GAMMA_GNORM_ACCURATE, state->stream, len, den, shape, d_zero, scale); - assert(err == VSL_STATUS_OK); - - vmdDiv(len, res, den, res, VML_HA); - mkl_free(den); -} - -/* - for df > 1, X ~ Chi2(df - 1) + ( sqrt(nonc) + Z)^2 - for df <=1, X ~ Chi2( df + 2*I), where I ~ Poisson( nonc/2.0) -*/ -void irk_noncentral_chisquare_vec(irk_state *state, npy_intp len, double *res, const double df, const double nonc) -{ - int err = 0; - npy_intp i = 0; - const double d_zero = 0.0, d_one = 1.0, d_two = 2.0; - double shape, loc; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_noncentral_chisquare_vec(state, MKL_INT_MAX, res, df, nonc); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - if (df > 1) - { - double *nvec; - - shape = 0.5 * (df - 1.0); - /* res has chi^2 with (df - 1) */ - err = vdRngGamma(VSL_RNG_METHOD_GAMMA_GNORM_ACCURATE, state->stream, len, res, shape, d_zero, d_two); - - nvec = (double *)mkl_malloc(len * sizeof(double), 64); - assert(nvec != nullptr); - - loc = sqrt(nonc); - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_ICDF, state->stream, len, nvec, loc, d_one); - assert(err == VSL_STATUS_OK); - - /* squaring could result in an overflow */ - vmdSqr(len, nvec, nvec, VML_HA); - vmdAdd(len, res, nvec, res, VML_HA); - - mkl_free(nvec); - } - else - { - if (df == 0.) - { - return irk_chisquare_vec(state, len, res, df); - } - if (df < 1) - { - /* noncentral_chisquare(df, nonc) ~ G( df/2 + Poisson(nonc/2), 2) */ - double lambda; - int *pvec = (int *)mkl_malloc(len * sizeof(int), 64); - - assert(pvec != nullptr); - - lambda = 0.5 * nonc; - err = viRngPoisson(VSL_RNG_METHOD_POISSON_PTPE, state->stream, len, pvec, lambda); - assert(err == VSL_STATUS_OK); - - shape = 0.5 * df; - - if (0.125 * len > sqrt(lambda)) - { - int *idx = nullptr; - double *tmp = nullptr; - - idx = (int *)mkl_malloc(len * sizeof(int), 64); - assert(idx != nullptr); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - idx[i] = (int)i; - - std::sort(idx, idx + len, [pvec](int i1, int i2) - { return pvec[i1] < pvec[i2]; }); - /* idx now contains original indexes of ordered Poisson outputs */ - - /* allocate workspace to store samples of gamma, enough to hold entire output */ - tmp = (double *)mkl_malloc(len * sizeof(double), 64); - assert(tmp != nullptr); - - for (i = 0; i < len;) - { - int cv = pvec[idx[i]]; - npy_intp k = 0, j = 0; - - for (j = i + 1; (j < len) && (pvec[idx[j]] == cv); ++j) - { - } - - assert(j > i); - err = vdRngGamma(VSL_RNG_METHOD_GAMMA_GNORM_ACCURATE, state->stream, j - i, tmp, - shape + cv, d_zero, d_two); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (k = 0; k < j - i; ++k) - res[idx[k + i]] = tmp[k]; - - i = j; - } - - mkl_free(tmp); - mkl_free(idx); - } - else - { - - for (i = 0; i < len; ++i) - { - err = vdRngGamma(VSL_RNG_METHOD_GAMMA_GNORM_ACCURATE, state->stream, 1, - res + i, shape + pvec[i], d_zero, d_two); - assert(err == VSL_STATUS_OK); - } - } - - mkl_free(pvec); - } - else - { - /* noncentral_chisquare(1, nonc) ~ (Z + sqrt(nonc))**2 for df == 1 */ - loc = sqrt(nonc); - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_ICDF, state->stream, len, res, loc, d_one); - assert(err == VSL_STATUS_OK); - /* squaring could result in an overflow */ - vmdSqr(len, res, res, VML_HA); - } - } -} - -void irk_laplace_vec(irk_state *state, npy_intp len, double *res, const double loc, const double scale) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngLaplace(VSL_RNG_METHOD_LAPLACE_ICDF, state->stream, MKL_INT_MAX, res, loc, scale); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngLaplace(VSL_RNG_METHOD_LAPLACE_ICDF, state->stream, len, res, loc, scale); - assert(err == VSL_STATUS_OK); -} - -void irk_gumbel_vec(irk_state *state, npy_intp len, double *res, const double loc, const double scale) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngGumbel(VSL_RNG_METHOD_GUMBEL_ICDF, state->stream, MKL_INT_MAX, res, loc, scale); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGumbel(VSL_RNG_METHOD_GUMBEL_ICDF, state->stream, len, res, loc, scale); - assert(err == VSL_STATUS_OK); -} - -/* Logistic(loc, scale) ~ loc + scale * log(u/(1.0 - u)) */ -void irk_logistic_vec(irk_state *state, npy_intp len, double *res, const double loc, const double scale) -{ - int err = 0; - npy_intp i = 0; - const double d_one = 1.0, d_zero = 0.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_logistic_vec(state, MKL_INT_MAX, res, loc, scale); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, len, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - /* can MKL optimize computation of the logit function p \mapsto \ln(p/(1-p)) */ - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = log(res[i] / (1.0 - res[i])); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = loc + scale * res[i]; -} - -void irk_lognormal_vec_ICDF(irk_state *state, npy_intp len, double *res, const double mean, const double sigma) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngLognormal(VSL_RNG_METHOD_LOGNORMAL_ICDF_ACCURATE, state->stream, MKL_INT_MAX, res, mean, sigma, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngLognormal(VSL_RNG_METHOD_LOGNORMAL_ICDF_ACCURATE, state->stream, len, res, mean, sigma, d_zero, d_one); - assert(err == VSL_STATUS_OK); -} - -void irk_lognormal_vec_BM(irk_state *state, npy_intp len, double *res, const double mean, const double sigma) -{ - int err = 0; - const double d_zero = 0.0, d_one = 1.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngLognormal(VSL_RNG_METHOD_LOGNORMAL_BOXMULLER2_ACCURATE, state->stream, MKL_INT_MAX, res, mean, sigma, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngLognormal(VSL_RNG_METHOD_LOGNORMAL_BOXMULLER2_ACCURATE, state->stream, len, res, mean, sigma, d_zero, d_one); - assert(err == VSL_STATUS_OK); -} - -/* direct transformation method */ -void irk_wald_vec(irk_state *state, npy_intp len, double *res, const double mean, const double scale) -{ - int err = 0; - npy_intp i = 0; - const double d_zero = 0., d_one = 1.0; - double *uvec = nullptr; - double gsc = sqrt(0.5 * mean / scale); - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_wald_vec(state, MKL_INT_MAX, res, mean, scale); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngGaussian(VSL_RNG_METHOD_GAUSSIAN_ICDF, state->stream, len, res, d_zero, gsc); - assert(err == VSL_STATUS_OK); - - /* Y = mean/(2 scale) * Z^2 */ - vmdSqr(len, res, res, VML_HA); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - { - if (res[i] <= 2.0) - { - res[i] = 1.0 + res[i] + sqrt(res[i] * (res[i] + 2.0)); - } - else - { - res[i] = 1.0 + res[i] * (1.0 + sqrt(1.0 + 2.0 / res[i])); - } - } - - uvec = (double *)mkl_malloc(len * sizeof(double), 64); - assert(uvec != nullptr); - - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, len, uvec, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - { - if (uvec[i] * (1.0 + res[i]) <= res[i]) - res[i] = mean / res[i]; - else - res[i] = mean * res[i]; - } - - mkl_free(uvec); -} - -#ifndef M_PI -/* 128-bits worth of pi */ -#define M_PI 3.141592653589793238462643383279502884197 -#endif - -/* Uses the rejection algorithm compared against the wrapped Cauchy - distribution suggested by Best and Fisher and documented in - Chapter 9 of Luc's Non-Uniform Random Variate Generation. - http://cg.scs.carleton.ca/~luc/rnbookindex.html - (but corrected to match the algorithm in R and Python) -*/ -static void -irk_vonmises_vec_small_kappa(irk_state *state, npy_intp len, double *res, const double mu, const double kappa) -{ - int err = 0; - npy_intp n = 0, i = 0, size = 0; - double rho_over_kappa, rho, r, s_kappa, Z, W, Y, V; - double *Uvec = nullptr, *Vvec = nullptr; - float *VFvec = nullptr; - const double d_zero = 0.0, d_one = 1.0; - - assert(0. < kappa <= 1.0); - - r = 1 + sqrt(1 + 4 * kappa * kappa); - rho_over_kappa = (2) / (r + sqrt(2 * r)); - rho = rho_over_kappa * kappa; - - /* s times kappa */ - s_kappa = (1 + rho * rho) / (2 * rho_over_kappa); - - Uvec = (double *)mkl_malloc(len * sizeof(double), 64); - assert(Uvec != nullptr); - Vvec = (double *)mkl_malloc(len * sizeof(double), 64); - assert(Vvec != nullptr); - - for (n = 0; n < len;) - { - size = len - n; - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, size, Uvec, d_zero, M_PI); - assert(err == VSL_STATUS_OK); - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, size, Vvec, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - for (i = 0; i < size; ++i) - { - Z = cos(Uvec[i]); - V = Vvec[i]; - W = (kappa + s_kappa * Z) / (s_kappa + kappa * Z); - Y = s_kappa - kappa * W; - if ((Y * (2 - Y) >= V) || (log(Y / V) + 1 >= Y)) - { - res[n++] = acos(W); - } - } - } - - mkl_free(Uvec); - - VFvec = (float *)Vvec; - err = vsRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, VFvec, (float)d_zero, (float)d_one); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - { - double mod, resi; - - resi = (VFvec[i] < 0.5) ? mu - res[i] : mu + res[i]; - mod = fabs(resi); - mod = (fmod(mod + M_PI, 2 * M_PI) - M_PI); - res[i] = (resi < 0) ? -mod : mod; - } - - mkl_free(Vvec); -} - -static void -irk_vonmises_vec_large_kappa(irk_state *state, npy_intp len, double *res, const double mu, const double kappa) -{ - int err = 0; - npy_intp i = 0, n = 0, size = 0; - double r_over_two_kappa, recip_two_kappa; - double s_minus_one, hpt, r_over_two_kappa_minus_one, rho_minus_one; - double *Uvec = nullptr, *Vvec = nullptr; - float *VFvec = nullptr; - const double d_zero = 0.0, d_one = 1.0; - - assert(kappa > 1.0); - - recip_two_kappa = 1 / (2 * kappa); - - /* variables here are dwindling to zero as kappa grows */ - hpt = sqrt(1 + recip_two_kappa * recip_two_kappa); - r_over_two_kappa_minus_one = recip_two_kappa * (1 + recip_two_kappa / (1 + hpt)); - r_over_two_kappa = 1 + r_over_two_kappa_minus_one; - rho_minus_one = r_over_two_kappa_minus_one - sqrt(2 * r_over_two_kappa * recip_two_kappa); - s_minus_one = rho_minus_one * (0.5 * rho_minus_one / (1 + rho_minus_one)); - - Uvec = (double *)mkl_malloc(len * sizeof(double), 64); - assert(Uvec != nullptr); - Vvec = (double *)mkl_malloc(len * sizeof(double), 64); - assert(Vvec != nullptr); - - for (n = 0; n < len;) - { - size = len - n; - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, size, Uvec, d_zero, 0.5 * M_PI); - assert(err == VSL_STATUS_OK); - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, size, Vvec, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - for (i = 0; i < size; ++i) - { - double sn, cn, sn2, cn2; - double neg_W_minus_one, V, Y; - - sn = sin(Uvec[i]); - cn = cos(Uvec[i]); - V = Vvec[i]; - sn2 = sn * sn; - cn2 = cn * cn; - - neg_W_minus_one = s_minus_one * sn2 / (0.5 * s_minus_one + cn2); - Y = kappa * (s_minus_one + neg_W_minus_one); - - if ((Y * (2 - Y) >= V) || (log(Y / V) + 1 >= Y)) - { - Y = neg_W_minus_one * (2 - neg_W_minus_one); - if (Y < 0) - Y = 0.; - else if (Y > 1.0) - Y = 1.0; - - res[n++] = asin(sqrt(Y)); - } - } - } - - mkl_free(Uvec); - - VFvec = (float *)Vvec; - err = vsRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, VFvec, (float)d_zero, (float)d_one); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - { - double mod, resi; - - resi = (VFvec[i] < 0.5) ? mu - res[i] : mu + res[i]; - mod = fabs(resi); - mod = (fmod(mod + M_PI, 2 * M_PI) - M_PI); - res[i] = (resi < 0) ? -mod : mod; - } - - mkl_free(Vvec); -} - -void irk_vonmises_vec(irk_state *state, npy_intp len, double *res, const double mu, const double kappa) -{ - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_vonmises_vec(state, MKL_INT_MAX, res, mu, kappa); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - if (kappa > 1.0) - irk_vonmises_vec_large_kappa(state, len, res, mu, kappa); - else - irk_vonmises_vec_small_kappa(state, len, res, mu, kappa); -} - -void irk_noncentral_f_vec(irk_state *state, npy_intp len, double *res, const double df_num, const double df_den, const double nonc) -{ - npy_intp i; - double *den = nullptr, fctr; - - if (len < 1) - return; - - if (nonc == 0.) - return irk_f_vec(state, len, res, df_num, df_den); - - while (len > MKL_INT_MAX) - { - irk_noncentral_f_vec(state, MKL_INT_MAX, res, df_num, df_den, nonc); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - irk_noncentral_chisquare_vec(state, len, res, df_num, nonc); - - den = (double *)mkl_malloc(len * sizeof(double), 64); - - if (den == nullptr) - return; - - irk_noncentral_chisquare_vec(state, len, den, df_den, nonc); - - vmdDiv(len, res, den, res, VML_HA); - - mkl_free(den); - fctr = df_den / df_num; - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] *= fctr; -} - -void irk_triangular_vec(irk_state *state, npy_intp len, double *res, const double x_min, const double x_mode, const double x_max) -{ - int err = 0; - npy_intp i = 0; - const double d_zero = 0.0, d_one = 1.0; - double ratio, lpr, rpr; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_triangular_vec(state, MKL_INT_MAX, res, x_min, x_mode, x_max); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, len, res, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - { - double wtot, wl, wr; - - wtot = x_max - x_min; - wl = x_mode - x_min; - wr = x_max - x_mode; - - ratio = wl / wtot; - lpr = wl * wtot; - rpr = wr * wtot; - } - - assert(0 <= ratio && ratio <= 1); - - if (ratio <= 0) - { - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - { - /* U and 1 - U are equal in distribution */ - res[i] = x_max - sqrt(res[i] * rpr); - } - } - else if (ratio >= 1) - { - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - { - res[i] = x_min + sqrt(res[i] * lpr); - } - } - else - { - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - { - double ui = res[i]; - res[i] = (ui > ratio) ? x_max - sqrt((1.0 - ui) * rpr) : x_min + sqrt(ui * lpr); - } - } -} - -void irk_binomial_vec(irk_state *state, npy_intp len, int *res, const int n, const double p) -{ - int err = 0; - - if (len < 1) - return; - - if (n == 0) - { - memset(res, 0, len * sizeof(int)); - } - else - { - while (len > MKL_INT_MAX) - { - err = viRngBinomial(VSL_RNG_METHOD_BINOMIAL_BTPE, state->stream, MKL_INT_MAX, res, n, p); - assert(err == VSL_STATUS_OK); - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = viRngBinomial(VSL_RNG_METHOD_BINOMIAL_BTPE, state->stream, len, res, n, p); - assert(err == VSL_STATUS_OK); - } -} - -void irk_multinomial_vec(irk_state *state, npy_intp len, int *res, const int n, const int k, const double *pvec) -{ - int err = 0; - - if (len < 1) - return; - - if (n == 0) - { - memset(res, 0, len * k * sizeof(int)); - } - else - { - while (len > MKL_INT_MAX) - { - err = viRngMultinomial(VSL_RNG_METHOD_MULTINOMIAL_MULTPOISSON, state->stream, MKL_INT_MAX, res, n, k, pvec); - assert(err == VSL_STATUS_OK); - res += k * MKL_INT_MAX; - len -= k * MKL_INT_MAX; - } - - err = viRngMultinomial(VSL_RNG_METHOD_MULTINOMIAL_MULTPOISSON, state->stream, len, res, n, k, pvec); - assert(err == VSL_STATUS_OK); - } -} - -void irk_geometric_vec(irk_state *state, npy_intp len, int *res, const double p) -{ - int err = 0; - - if (len < 1) - return; - - if ((0.0 < p) && (p < 1.0)) - { - while (len > MKL_INT_MAX) - { - err = viRngGeometric(VSL_RNG_METHOD_GEOMETRIC_ICDF, state->stream, MKL_INT_MAX, res, p); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = viRngGeometric(VSL_RNG_METHOD_GEOMETRIC_ICDF, state->stream, len, res, p); - assert(err == VSL_STATUS_OK); - } - else - { - if (p == 1.0) - { - npy_intp i; - for (i = 0; i < len; ++i) - res[i] = 0; - } - else - { - assert(p >= 0.0); - assert(p <= 1.0); - } - } -} - -void irk_negbinomial_vec(irk_state *state, npy_intp len, int *res, const double a, const double p) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = viRngNegbinomial(VSL_RNG_METHOD_NEGBINOMIAL_NBAR, state->stream, MKL_INT_MAX, res, a, p); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = viRngNegbinomial(VSL_RNG_METHOD_NEGBINOMIAL_NBAR, state->stream, len, res, a, p); - assert(err == VSL_STATUS_OK); -} - -void irk_hypergeometric_vec(irk_state *state, npy_intp len, int *res, const int lot_s, - const int sampling_s, const int marked_s) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = viRngHypergeometric(VSL_RNG_METHOD_HYPERGEOMETRIC_H2PE, state->stream, MKL_INT_MAX, res, - lot_s, sampling_s, marked_s); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = viRngHypergeometric(VSL_RNG_METHOD_HYPERGEOMETRIC_H2PE, state->stream, len, res, - lot_s, sampling_s, marked_s); - assert(err == VSL_STATUS_OK); -} - -void irk_poisson_vec_PTPE(irk_state *state, npy_intp len, int *res, const double lambda) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = viRngPoisson(VSL_RNG_METHOD_POISSON_PTPE, state->stream, MKL_INT_MAX, res, lambda); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = viRngPoisson(VSL_RNG_METHOD_POISSON_PTPE, state->stream, len, res, lambda); - assert(err == VSL_STATUS_OK); -} - -void irk_poisson_vec_POISNORM(irk_state *state, npy_intp len, int *res, const double lambda) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = viRngPoisson(VSL_RNG_METHOD_POISSON_POISNORM, state->stream, MKL_INT_MAX, res, lambda); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = viRngPoisson(VSL_RNG_METHOD_POISSON_POISNORM, state->stream, len, res, lambda); - assert(err == VSL_STATUS_OK); -} - -void irk_poisson_vec_V(irk_state *state, npy_intp len, int *res, double *lambdas) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = viRngPoissonV(VSL_RNG_METHOD_POISSONV_POISNORM, state->stream, MKL_INT_MAX, res, lambdas); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - lambdas += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = viRngPoissonV(VSL_RNG_METHOD_POISSONV_POISNORM, state->stream, len, res, lambdas); - assert(err == VSL_STATUS_OK); -} - -void irk_zipf_long_vec(irk_state *state, npy_intp len, long *res, const double a) -{ - int err = 0; - npy_intp i = 0, n_accepted = 0, batch_size = 0; - double T, U, V, am1, b; - double *Uvec = nullptr, *Vvec = nullptr; - long X; - const double d_zero = 0.0, d_one = 1.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_zipf_long_vec(state, MKL_INT_MAX, res, a); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - am1 = a - d_one; - b = pow(2.0, am1); - - Uvec = (double *)mkl_malloc(len * sizeof(double), 64); - assert(Uvec != nullptr); - Vvec = (double *)mkl_malloc(len * sizeof(double), 64); - assert(Vvec != nullptr); - - for (n_accepted = 0; n_accepted < len;) - { - batch_size = len - n_accepted; - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, batch_size, Uvec, d_zero, d_one); - assert(err == VSL_STATUS_OK); - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, batch_size, Vvec, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < batch_size; ++i) - { - U = d_one - Uvec[i]; - V = Vvec[i]; - X = (long)floor(pow(U, (-1.0) / am1)); - /* The real result may be above what can be represented in a signed - * long. It will get casted to -sys.maxint-1. Since this is - * a straightforward rejection algorithm, we can just reject this value - * in the rejection condition below. This function then models a Zipf - * distribution truncated to sys.maxint. - */ - T = pow(d_one + d_one / X, am1); - if ((X > 0) && ((V * X) * (T - d_one) / (b - d_one) <= T / b)) - { - res[n_accepted++] = X; - } - } - } - - mkl_free(Vvec); - mkl_free(Uvec); -} - -void irk_logseries_vec(irk_state *state, npy_intp len, int *res, const double theta) -{ - int err = 0; - npy_intp i = 0, n_accepted = 0, batch_size = 0; - double q, r, V; - double *Uvec = nullptr, *Vvec = nullptr; - int result; - const double d_zero = 0.0, d_one = 1.0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_logseries_vec(state, MKL_INT_MAX, res, theta); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - r = log(d_one - theta); - - Uvec = (double *)mkl_malloc(len * sizeof(double), 64); - assert(Uvec != nullptr); - Vvec = (double *)mkl_malloc(len * sizeof(double), 64); - assert(Vvec != nullptr); - - for (n_accepted = 0; n_accepted < len;) - { - batch_size = len - n_accepted; - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, batch_size, Uvec, d_zero, d_one); - assert(err == VSL_STATUS_OK); - err = vdRngUniform(VSL_RNG_METHOD_UNIFORM_STD_ACCURATE, state->stream, batch_size, Vvec, d_zero, d_one); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < batch_size; ++i) - { - V = Vvec[i]; - if (V >= theta) - { - res[n_accepted++] = 1; - } - else - { -#if __cplusplus > 199711L - q = -expm1(r * Uvec[i]); -#else - /* exp(x) - 1 == 2 * exp(x/2) * sinh(x/2) */ - q = r * Uvec[i]; - if (q > 1.) - { - q = 1.0 - exp(q); - } - else - { - q = 0.5 * q; - q = -2.0 * exp(q) * sinh(q); - } -#endif - if (V <= q * q) - { - result = (int)floor(1 + log(V) / log(q)); - if (result > 0) - { - res[n_accepted++] = result; - } - } - else - { - res[n_accepted++] = (V < q) ? 2 : 1; - } - } - } - } - - mkl_free(Vvec); -} - -/* samples discrete uniforms from [low, high) */ -void irk_discrete_uniform_vec(irk_state *state, npy_intp len, int *res, const int low, const int high) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = viRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, MKL_INT_MAX, res, low, high); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - err = viRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, res, low, high); - assert(err == VSL_STATUS_OK); -} - -void irk_discrete_uniform_long_vec(irk_state *state, npy_intp len, long *res, const long low, const long high) -{ - int err = 0; - unsigned long max; - npy_intp i = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_discrete_uniform_long_vec(state, MKL_INT_MAX, res, low, high); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - max = ((unsigned long)high) - ((unsigned long)low) - 1UL; - if (max == 0) - { - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = low; - - return; - } - - if (max <= (unsigned long)INT_MAX) - { - int *buf = (int *)mkl_malloc(len * sizeof(int), 64); - assert(buf != nullptr); - - err = viRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, buf, -1, (const int)max); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = low + ((long)buf[i]) + 1L; - - mkl_free(buf); - } - else - { - unsigned long mask = max; - unsigned long *buf = nullptr; - int n_accepted; - - /* Smallest bit mask >= max */ - mask |= mask >> 1; - mask |= mask >> 2; - mask |= mask >> 4; - mask |= mask >> 8; - mask |= mask >> 16; -#if ULONG_MAX > 0xffffffffUL - mask |= mask >> 32; -#endif - - buf = (unsigned long *)mkl_malloc(len * sizeof(long), 64); - assert(buf != nullptr); - n_accepted = 0; - - while (n_accepted < len) - { - int k, batchSize = len - n_accepted; - - err = viRngUniformBits64(VSL_RNG_METHOD_UNIFORM_STD, state->stream, batchSize, (unsigned MKL_INT64 *)buf); - assert(err == VSL_STATUS_OK); - - for (k = 0; k < batchSize; ++k) - { - unsigned long value = buf[k] & mask; - if (value <= max) - { - res[n_accepted++] = low + value; - } - } - } - - mkl_free(buf); - } -} - -void irk_ulong_vec(irk_state *state, npy_intp len, unsigned long *res) -{ - int err = 0; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - irk_ulong_vec(state, MKL_INT_MAX, res); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - -#if ULONG_MAX <= 0xffffffffUL - err = viRngUniformBits32(VSL_RNG_METHOD_UNIFORMBITS32_STD, state->stream, len, (unsigned int *)res); -#else - err = viRngUniformBits64(VSL_RNG_METHOD_UNIFORMBITS64_STD, state->stream, len, (unsigned MKL_INT64 *)res); -#endif - - assert(err == VSL_STATUS_OK); -} - -void irk_long_vec(irk_state *state, npy_intp len, long *res) -{ - npy_intp i = 0; - unsigned long *ulptr = (unsigned long *)res; - - irk_ulong_vec(state, len, ulptr); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = (long)(ulptr[i] >> 1); -} - -void irk_rand_bool_vec(irk_state *state, npy_intp len, npy_bool *res, const npy_bool lo, const npy_bool hi) -{ - int err = 0; - npy_intp i = 0; - int *buf = nullptr; - - if (len < 1) - return; - - if (len > MKL_INT_MAX) - { - irk_rand_bool_vec(state, MKL_INT_MAX, res, lo, hi); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - if (lo == hi) - { - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = lo; - - return; - } - - assert((lo == 0) && (hi == 1)); - buf = (int *)mkl_malloc(len * sizeof(int), 64); - assert(buf != nullptr); - - err = viRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, buf, (const int)lo, (const int)hi + 1); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = (npy_bool)buf[i]; - - mkl_free(buf); -} - -void irk_rand_uint8_vec(irk_state *state, npy_intp len, npy_uint8 *res, const npy_uint8 lo, const npy_uint8 hi) -{ - int err = 0; - npy_intp i = 0; - int *buf = nullptr; - - if (len < 1) - return; - - if (len > MKL_INT_MAX) - { - irk_rand_uint8_vec(state, MKL_INT_MAX, res, lo, hi); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - if (lo == hi) - { - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = lo; - - return; - } - - assert(lo < hi); - buf = (int *)mkl_malloc(len * sizeof(int), 64); - assert(buf != nullptr); - - err = viRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, buf, (const int)lo, (const int)hi + 1); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = (npy_uint8)buf[i]; - - mkl_free(buf); -} - -void irk_rand_int8_vec(irk_state *state, npy_intp len, npy_int8 *res, const npy_int8 lo, const npy_int8 hi) -{ - int err = 0; - npy_intp i = 0; - int *buf = nullptr; - - if (len < 1) - return; - - if (len > MKL_INT_MAX) - { - irk_rand_int8_vec(state, MKL_INT_MAX, res, lo, hi); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - if (lo == hi) - { - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = lo; - - return; - } - - assert(lo < hi); - buf = (int *)mkl_malloc(len * sizeof(int), 64); - assert(buf != nullptr); - - err = viRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, buf, (const int)lo, (const int)hi + 1); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = (npy_int8)buf[i]; - - mkl_free(buf); -} - -void irk_rand_uint16_vec(irk_state *state, npy_intp len, npy_uint16 *res, const npy_uint16 lo, const npy_uint16 hi) -{ - int err = 0; - npy_intp i = 0; - int *buf = nullptr; - - if (len < 1) - return; - - if (len > MKL_INT_MAX) - { - irk_rand_uint16_vec(state, MKL_INT_MAX, res, lo, hi); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - if (lo == hi) - { - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = lo; - - return; - } - - assert(lo < hi); - buf = (int *)mkl_malloc(len * sizeof(int), 64); - assert(buf != nullptr); - - err = viRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, buf, (const int)lo, (const int)hi + 1); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = (npy_uint16)buf[i]; - - mkl_free(buf); -} - -void irk_rand_int16_vec(irk_state *state, npy_intp len, npy_int16 *res, const npy_int16 lo, const npy_int16 hi) -{ - int err = 0; - npy_intp i = 0; - int *buf = nullptr; - - if (len < 1) - return; - - if (len > MKL_INT_MAX) - { - irk_rand_int16_vec(state, MKL_INT_MAX, res, lo, hi); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - if (lo == hi) - { - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = lo; - - return; - } - - assert(lo < hi); - buf = (int *)mkl_malloc(len * sizeof(int), 64); - assert(buf != nullptr); - - err = viRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, buf, (const int)lo, (const int)hi + 1); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = (npy_int16)buf[i]; - - mkl_free(buf); -} - -void irk_rand_uint32_vec(irk_state *state, npy_intp len, npy_uint32 *res, const npy_uint32 lo, const npy_uint32 hi) -{ - int err = 0; - unsigned int intm = INT_MAX; - - if (len < 1) - return; - - if (len > MKL_INT_MAX) - { - irk_rand_uint32_vec(state, MKL_INT_MAX, res, lo, hi); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - /* optimization for lo = 0 and hi = 2**32-1 */ - if (!(lo || ~hi)) - { - err = viRngUniformBits32(VSL_RNG_METHOD_UNIFORMBITS32_STD, state->stream, len, (unsigned int *)res); - assert(err == VSL_STATUS_OK); - - return; - } - - if (hi >= intm) - { - - npy_int32 shft = ((npy_uint32)intm) + ((npy_uint32)1); - int i; - - /* if lo is non-zero, shift one more to accommodate possibility of hi being ULONG_MAX */ - if (lo) - shft++; - - err = viRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, (int *)res, (const int)(lo - shft), (const int)(hi - shft + 1U)); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] += shft; - } - else - { - err = viRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, (int *)res, (const int)lo, (const int)hi + 1); - assert(err == VSL_STATUS_OK); - } -} - -void irk_rand_int32_vec(irk_state *state, npy_intp len, npy_int32 *res, const npy_int32 lo, const npy_int32 hi) -{ - int err = 0; - int intm = INT_MAX; - - if (len < 1) - return; - - if (len > MKL_INT_MAX) - { - irk_rand_int32_vec(state, MKL_INT_MAX, res, lo, hi); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - if (hi >= intm) - { - int i; - - irk_rand_uint32_vec(state, len, (npy_uint32 *)res, 0U, (npy_uint32)(hi - lo)); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] += lo; - } - else - { - err = viRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, (int *)res, (const int)lo, (const int)hi + 1); - assert(err == VSL_STATUS_OK); - } -} - -void irk_rand_uint64_vec(irk_state *state, npy_intp len, npy_uint64 *res, const npy_uint64 lo, const npy_uint64 hi) -{ - npy_uint64 rng; - int err = 0; - npy_intp i = 0; - - if (len < 1) - return; - - if (len > MKL_INT_MAX) - { - irk_rand_uint64_vec(state, MKL_INT_MAX, res, lo, hi); - - res += MKL_INT_MAX; - len -= MKL_INT_MAX; - } - - /* optimization for lo = 0 and hi = 2**64-1 */ - if (!(lo || ~hi)) - { - err = viRngUniformBits64(VSL_RNG_METHOD_UNIFORMBITS64_STD, state->stream, len, (unsigned MKL_INT64 *)res); - assert(err == VSL_STATUS_OK); - - return; - } - - rng = hi - lo; - if (!rng) - { - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = lo; - - return; - } - - rng++; - - if (rng <= (npy_uint64)INT_MAX) - { - int *buf = (int *)mkl_malloc(len * sizeof(int), 64); - assert(buf != nullptr); - - err = viRngUniform(VSL_RNG_METHOD_UNIFORM_STD, state->stream, len, buf, 0, (const int)rng); - assert(err == VSL_STATUS_OK); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = lo + ((npy_uint64)buf[i]); - - mkl_free(buf); - } - else - { - npy_uint64 mask = rng; - npy_uint64 *buf = nullptr; - npy_intp n_accepted = 0; - - mask |= mask >> 1; - mask |= mask >> 2; - mask |= mask >> 4; - mask |= mask >> 8; - mask |= mask >> 16; - mask |= mask >> 32; - - buf = (npy_uint64 *)mkl_malloc(len * sizeof(npy_uint64), 64); - assert(buf != nullptr); - - while (n_accepted < len) - { - npy_intp k = 0; - npy_intp batchSize = len - n_accepted; - - err = viRngUniformBits64(VSL_RNG_METHOD_UNIFORM_STD, state->stream, batchSize, (unsigned MKL_INT64 *)buf); - assert(err == VSL_STATUS_OK); - - for (k = 0; k < batchSize; ++k) - { - npy_uint64 value = buf[k] & mask; - if (value <= rng) - { - res[n_accepted++] = lo + value; - } - } - } - - mkl_free(buf); - } -} - -void irk_rand_int64_vec(irk_state *state, npy_intp len, npy_int64 *res, const npy_int64 lo, const npy_int64 hi) -{ - npy_uint64 rng = 0; - npy_intp i = 0; - - if (len < 1) - return; - - rng = ((npy_uint64)hi) - ((npy_uint64)lo); - - irk_rand_uint64_vec(state, len, (npy_uint64 *)res, 0, rng); - - DIST_PRAGMA_VECTOR - for (i = 0; i < len; ++i) - res[i] = res[i] + lo; -} - -const MKL_INT cholesky_storage_flags[3] = { - VSL_MATRIX_STORAGE_FULL, - VSL_MATRIX_STORAGE_PACKED, - VSL_MATRIX_STORAGE_DIAGONAL}; - -void irk_multinormal_vec_ICDF(irk_state *state, npy_intp len, double *res, const int dim, double *mean_vec, double *ch, - const ch_st_enum storage_flag) -{ - int err = 0; - const MKL_INT storage_mode = cholesky_storage_flags[storage_flag]; - - err = vdRngGaussianMV(VSL_RNG_METHOD_GAUSSIANMV_ICDF, state->stream, len, res, dim, storage_mode, mean_vec, ch); - assert(err == VSL_STATUS_OK); -} - -void irk_multinormal_vec_BM1(irk_state *state, npy_intp len, double *res, const int dim, double *mean_vec, double *ch, - const ch_st_enum storage_flag) -{ - int err = 0; - const MKL_INT storage_mode = cholesky_storage_flags[storage_flag]; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngGaussianMV(VSL_RNG_METHOD_GAUSSIANMV_BOXMULLER, state->stream, MKL_INT_MAX, res, dim, storage_mode, mean_vec, ch); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX * dim; - len -= MKL_INT_MAX; - } - - err = vdRngGaussianMV(VSL_RNG_METHOD_GAUSSIANMV_BOXMULLER, state->stream, len, res, dim, storage_mode, mean_vec, ch); - assert(err == VSL_STATUS_OK); -} - -void irk_multinormal_vec_BM2(irk_state *state, npy_intp len, double *res, const int dim, double *mean_vec, double *ch, - const ch_st_enum storage_flag) -{ - int err = 0; - const MKL_INT storage_mode = cholesky_storage_flags[storage_flag]; - - if (len < 1) - return; - - while (len > MKL_INT_MAX) - { - err = vdRngGaussianMV(VSL_RNG_METHOD_GAUSSIANMV_BOXMULLER2, state->stream, MKL_INT_MAX, res, dim, storage_mode, mean_vec, ch); - assert(err == VSL_STATUS_OK); - - res += MKL_INT_MAX * dim; - len -= MKL_INT_MAX; - } - - err = vdRngGaussianMV(VSL_RNG_METHOD_GAUSSIANMV_BOXMULLER2, state->stream, len, res, dim, storage_mode, mean_vec, ch); - assert(err == VSL_STATUS_OK); -} - -/* This code is taken from distribution.c, and is currently unused. It is retained here for - possible future optimization of sampling from multinomial */ - -static double irk_double(irk_state *state) -{ - double res; - - irk_double_vec(state, 1, &res); - - return res; -} diff --git a/mkl_random/src/mkl_distributions.h b/mkl_random/src/mkl_distributions.h deleted file mode 100644 index 3322761..0000000 --- a/mkl_random/src/mkl_distributions.h +++ /dev/null @@ -1,137 +0,0 @@ -/* - Copyright (c) 2017-2019, Intel Corporation - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - * Neither the name of Intel Corporation nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER - CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - */ - -#include -#include "randomkit.h" - -#ifndef _MKL_DISTRIBUTIONS_H_ -#define _MKL_DISTRIBUTIONS_H_ - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum { - MATRIX = 0, - PACKED = 1, - DIAGONAL = 2 -} ch_st_enum; - -extern void irk_double_vec(irk_state *state, npy_intp len, double *res); -extern void irk_uniform_vec(irk_state *state, npy_intp len, double *res, const double low, const double high); -extern void irk_standard_normal_vec_ICDF(irk_state *state, npy_intp len, double *res); -extern void irk_standard_normal_vec_BM1(irk_state *state, npy_intp len, double *res); -extern void irk_standard_normal_vec_BM2(irk_state *state, npy_intp len, double *res); - -extern void irk_normal_vec_ICDF(irk_state *state, npy_intp len, double *res, const double loc, const double scale); -extern void irk_normal_vec_BM1(irk_state *state, npy_intp len, double *res, const double loc, const double scale); -extern void irk_normal_vec_BM2(irk_state *state, npy_intp len, double *res, const double loc, const double scale); - -extern void irk_standard_t_vec(irk_state *state, npy_intp len, double *res, const double df); -extern void irk_chisquare_vec(irk_state *state, npy_intp len, double *res, const double df); - -extern void irk_standard_exponential_vec(irk_state *state, npy_intp len, double *res); -extern void irk_standard_cauchy_vec(irk_state *state, npy_intp len, double *res); - -extern void irk_standard_gamma_vec(irk_state *state, npy_intp len, double *res, const double shape); -extern void irk_exponential_vec(irk_state *state, npy_intp len, double *res, const double scale); -extern void irk_gamma_vec(irk_state *state, npy_intp len, double *res, const double shape, const double scale); - -extern void irk_pareto_vec(irk_state *state, npy_intp len, double *res, const double alph); -extern void irk_power_vec(irk_state *state, npy_intp len, double *res, const double alph); - -extern void irk_weibull_vec(irk_state *state, npy_intp len, double *res, const double alph); - -extern void irk_rayleigh_vec(irk_state *state, npy_intp len, double *res, const double scale); - -extern void irk_beta_vec(irk_state *state, npy_intp len, double *res, const double p, const double q); -extern void irk_f_vec(irk_state *state, npy_intp len, double *res, const double df_num, const double df_den); - -extern void irk_noncentral_chisquare_vec(irk_state *state, npy_intp len, double *res, const double df, const double nonc); - -extern void irk_laplace_vec(irk_state *vec, npy_intp len, double *res, const double loc, const double scale); -extern void irk_gumbel_vec(irk_state *vec, npy_intp len, double *res, const double loc, const double scale); -extern void irk_logistic_vec(irk_state *vec, npy_intp len, double *res, const double loc, const double scale); - -extern void irk_lognormal_vec_ICDF(irk_state *state, npy_intp len, double *res, const double mean, const double sigma); -extern void irk_lognormal_vec_BM(irk_state *state, npy_intp len, double *res, const double mean, const double sigma); - -extern void irk_wald_vec(irk_state *state, npy_intp len, double *res, const double mean, const double scale); - -extern void irk_vonmises_vec(irk_state *state, npy_intp len, double *res, const double mu, const double kappa); - -extern void irk_noncentral_f_vec(irk_state *state, npy_intp len, double *res, double df_num, double df_den, double nonc); -extern void irk_triangular_vec(irk_state *state, npy_intp len, double *res, double left, double mode, double right); - -extern void irk_binomial_vec(irk_state *state, npy_intp len, int *res, const int n, const double p); - -extern void irk_multinomial_vec(irk_state *state, npy_intp len, int *res, const int n, const int k, const double* pvec); - -extern void irk_geometric_vec(irk_state *state, npy_intp len, int *res, const double p); -extern void irk_negbinomial_vec(irk_state *state, npy_intp len, int *res, const double a, const double p); -extern void irk_hypergeometric_vec(irk_state *state, npy_intp len, int *res, const int ls, const int ss, const int ms); -extern void irk_poisson_vec_PTPE(irk_state *state, npy_intp len, int *res, const double lambda); -extern void irk_poisson_vec_POISNORM(irk_state *state, npy_intp len, int *res, const double lambda); - -extern void irk_poisson_vec_V(irk_state *state, npy_intp len, int *res, double *lambdas); - -extern void irk_zipf_long_vec(irk_state *state, npy_intp len, long *res, const double alp); - -extern void irk_logseries_vec(irk_state *state, npy_intp len, int *res, const double alp); - -extern void irk_discrete_uniform_vec(irk_state *state, npy_intp len, int *res, const int low, const int high); - -extern void irk_discrete_uniform_long_vec(irk_state *state, npy_intp len, long *res, const long low, const long high); - -extern void irk_rand_int64_vec(irk_state *state, npy_intp len, npy_int64 *res, const npy_int64 lo, const npy_int64 hi); -extern void irk_rand_uint64_vec(irk_state *state, npy_intp len, npy_uint64 *res, const npy_uint64 lo, const npy_uint64 hi); -extern void irk_rand_int32_vec(irk_state *state, npy_intp len, npy_int32 *res, const npy_int32 lo, const npy_int32 hi); -extern void irk_rand_uint32_vec(irk_state *state, npy_intp len, npy_uint32 *res, const npy_uint32 lo, const npy_uint32 hi); -extern void irk_rand_int16_vec(irk_state *state, npy_intp len, npy_int16 *res, const npy_int16 lo, const npy_int16 hi); -extern void irk_rand_uint16_vec(irk_state *state, npy_intp len, npy_uint16 *res, const npy_uint16 lo, const npy_uint16 hi); -extern void irk_rand_int8_vec(irk_state *state, npy_intp len, npy_int8 *res, const npy_int8 lo, const npy_int8 hi); -extern void irk_rand_uint8_vec(irk_state *state, npy_intp len, npy_uint8 *res, const npy_uint8 lo, const npy_uint8 hi); -extern void irk_rand_bool_vec(irk_state *state, npy_intp len, npy_bool *res, const npy_bool lo, const npy_bool hi); - -extern void irk_ulong_vec(irk_state *state, npy_intp len, unsigned long *res); -extern void irk_long_vec(irk_state *state, npy_intp len, long *res); - -extern void irk_multinormal_vec_ICDF(irk_state *state, npy_intp len, double *res, const int dim, - double *mean_vec, double *ch, const ch_st_enum storage_mode); - -extern void irk_multinormal_vec_BM1(irk_state *state, npy_intp len, double *res, const int dim, - double *mean_vec, double *ch, const ch_st_enum storage_mode); - -extern void irk_multinormal_vec_BM2(irk_state *state, npy_intp len, double *res, const int dim, - double *mean_vec, double *ch, const ch_st_enum storage_mode); - -#ifdef __cplusplus -} -#endif - - -#endif diff --git a/mkl_random/src/mklrand_py_helper.h b/mkl_random/src/mklrand_py_helper.h deleted file mode 100644 index 28d713d..0000000 --- a/mkl_random/src/mklrand_py_helper.h +++ /dev/null @@ -1,41 +0,0 @@ -#ifndef _MKLRAND_PY_HELPER_H_ -#define _MKLRAND_PY_HELPER_H_ - -#include - -static PyObject *empty_py_bytes(npy_intp length, void **bytesVec) -{ - PyObject *b; -#if PY_MAJOR_VERSION >= 3 - b = PyBytes_FromStringAndSize(NULL, length); - if (b) { - *bytesVec = PyBytes_AS_STRING(b); - } -#else - b = PyString_FromStringAndSize(NULL, length); - if (b) { - *bytesVec = PyString_AS_STRING(b); - } -#endif - return b; -} - -static char *py_bytes_DataPtr(PyObject *b) -{ -#if PY_MAJOR_VERSION >= 3 - return PyBytes_AS_STRING(b); -#else - return PyString_AS_STRING(b); -#endif -} - -static int is_bytes_object(PyObject *b) -{ -#if PY_MAJOR_VERSION >= 3 - return PyBytes_Check(b); -#else - return PyString_Check(b); -#endif -} - -#endif /* _MKLRAND_PY_HELPER_H_ */ diff --git a/mkl_random/src/numpy.pxd b/mkl_random/src/numpy.pxd deleted file mode 100644 index fa8af74..0000000 --- a/mkl_random/src/numpy.pxd +++ /dev/null @@ -1,152 +0,0 @@ -# :Author: Travis Oliphant - -cdef extern from "numpy/npy_no_deprecated_api.h": pass - -cdef extern from "numpy/arrayobject.h": - - cdef enum NPY_TYPES: - NPY_BOOL - NPY_BYTE - NPY_UBYTE - NPY_SHORT - NPY_USHORT - NPY_INT - NPY_UINT - NPY_LONG - NPY_ULONG - NPY_LONGLONG - NPY_ULONGLONG - NPY_FLOAT - NPY_DOUBLE - NPY_LONGDOUBLE - NPY_CFLOAT - NPY_CDOUBLE - NPY_CLONGDOUBLE - NPY_OBJECT - NPY_STRING - NPY_UNICODE - NPY_VOID - NPY_NTYPES - NPY_NOTYPE - - cdef enum requirements: - NPY_ARRAY_C_CONTIGUOUS - NPY_ARRAY_F_CONTIGUOUS - NPY_ARRAY_OWNDATA - NPY_ARRAY_FORCECAST - NPY_ARRAY_ENSURECOPY - NPY_ARRAY_ENSUREARRAY - NPY_ARRAY_ELEMENTSTRIDES - NPY_ARRAY_ALIGNED - NPY_ARRAY_NOTSWAPPED - NPY_ARRAY_WRITEABLE - NPY_ARRAY_UPDATEIFCOPY - NPY_ARR_HAS_DESCR - - NPY_ARRAY_BEHAVED - NPY_ARRAY_BEHAVED_NS - NPY_ARRAY_CARRAY - NPY_ARRAY_CARRAY_RO - NPY_ARRAY_FARRAY - NPY_ARRAY_FARRAY_RO - NPY_ARRAY_DEFAULT - - NPY_ARRAY_IN_ARRAY - NPY_ARRAY_OUT_ARRAY - NPY_ARRAY_INOUT_ARRAY - NPY_ARRAY_IN_FARRAY - NPY_ARRAY_OUT_FARRAY - NPY_ARRAY_INOUT_FARRAY - - NPY_ARRAY_UPDATE_ALL - - cdef enum defines: - NPY_MAXDIMS - - ctypedef struct npy_cdouble: - double real - double imag - - ctypedef struct npy_cfloat: - double real - double imag - - ctypedef int npy_int - ctypedef int npy_intp - ctypedef int npy_int64 - ctypedef int npy_uint64 - ctypedef int npy_int32 - ctypedef int npy_uint32 - ctypedef int npy_int16 - ctypedef int npy_uint16 - ctypedef int npy_int8 - ctypedef int npy_uint8 - ctypedef int npy_bool - - ctypedef extern class numpy.dtype [object PyArray_Descr]: pass - - ctypedef extern class numpy.ndarray [object PyArrayObject]: pass - - ctypedef extern class numpy.flatiter [object PyArrayIterObject]: - cdef int nd_m1 - cdef npy_intp index, size - cdef ndarray ao - cdef char *dataptr - - ctypedef extern class numpy.broadcast [object PyArrayMultiIterObject]: - cdef int numiter - cdef npy_intp size, index - cdef int nd - cdef npy_intp *dimensions - cdef void **iters - - object PyArray_ZEROS(int ndims, npy_intp* dims, NPY_TYPES type_num, int fortran) - object PyArray_EMPTY(int ndims, npy_intp* dims, NPY_TYPES type_num, int fortran) - dtype PyArray_DescrFromTypeNum(NPY_TYPES type_num) - object PyArray_SimpleNew(int ndims, npy_intp* dims, NPY_TYPES type_num) - int PyArray_Check(object obj) - object PyArray_ContiguousFromAny(object obj, NPY_TYPES type, - int mindim, int maxdim) - object PyArray_ContiguousFromObject(object obj, NPY_TYPES type, - int mindim, int maxdim) - npy_intp PyArray_SIZE(ndarray arr) - npy_intp PyArray_NBYTES(ndarray arr) - object PyArray_FromAny(object obj, dtype newtype, int mindim, int maxdim, - int requirements, object context) - object PyArray_FROMANY(object obj, NPY_TYPES type_num, int min, - int max, int requirements) - object PyArray_NewFromDescr(object subtype, dtype newtype, int nd, - npy_intp* dims, npy_intp* strides, void* data, - int flags, object parent) - - object PyArray_FROM_OTF(object obj, NPY_TYPES type, int flags) - object PyArray_EnsureArray(object) - - object PyArray_MultiIterNew(int n, ...) - - char *PyArray_MultiIter_DATA(broadcast multi, int i) nogil - void PyArray_MultiIter_NEXTi(broadcast multi, int i) nogil - void PyArray_MultiIter_NEXT(broadcast multi) nogil - - object PyArray_IterNew(object arr) - void PyArray_ITER_NEXT(flatiter it) nogil - - dtype PyArray_DescrFromType(int) - -# include functions that were once macros in the new api - - int PyArray_NDIM(ndarray arr) - char * PyArray_DATA(ndarray arr) - npy_intp * PyArray_DIMS(ndarray arr) - npy_intp * PyArray_STRIDES(ndarray arr) - npy_intp PyArray_DIM(ndarray arr, int idim) - npy_intp PyArray_STRIDE(ndarray arr, int istride) - object PyArray_BASE(ndarray arr) - dtype PyArray_DESCR(ndarray arr) - int PyArray_FLAGS(ndarray arr) - npy_intp PyArray_ITEMSIZE(ndarray arr) - int PyArray_TYPE(ndarray arr) - int PyArray_CHKFLAGS(ndarray arr, int flags) - object PyArray_GETITEM(ndarray arr, char *itemptr) - - int _import_array() diff --git a/mkl_random/src/randomkit.cpp b/mkl_random/src/randomkit.cpp deleted file mode 100644 index af19167..0000000 --- a/mkl_random/src/randomkit.cpp +++ /dev/null @@ -1,440 +0,0 @@ -/* - Copyright (c) 2017-2019, Intel Corporation - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - * Neither the name of Intel Corporation nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER - CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - */ -/* - Adopted from NumPy's Random kit 1.3, - Copyright (c) 2003-2005, Jean-Sebastien Roy (js@jeannot.org) - */ -#include -#include -#include -#include -#include -#include -#include - -#ifdef _WIN32 -/* - * Windows - * XXX: we have to use this ugly defined(__GNUC__) because it is not easy to - * detect the compiler used in distutils itself - */ -#if (defined(__GNUC__) && defined(NEED_MINGW_TIME_WORKAROUND)) - -/* - * FIXME: ideally, we should set this to the real version of MSVCRT. We need - * something higher than 0x601 to enable _ftime64 and co - */ -#define __MSVCRT_VERSION__ 0x0700 -#include -#include - -/* - * mingw msvcr lib import wrongly export _ftime, which does not exist in the - * actual msvc runtime for version >= 8; we make it an alias to _ftime64, which - * is available in those versions of the runtime - */ -#define _FTIME(x) _ftime64((x)) -#else -#include -#include -#define _FTIME(x) _ftime((x)) -#endif - -#ifndef RK_NO_WINCRYPT -/* Windows crypto */ -#ifndef _WIN32_WINNT -#define _WIN32_WINNT 0x0400 -#endif -#include -#include -#endif - -#else -/* Unix */ -#include -#include -#include -#endif - -#include "randomkit.h" - -#ifndef RK_DEV_URANDOM -#define RK_DEV_URANDOM "/dev/urandom" -#endif - -#ifndef RK_DEV_RANDOM -#define RK_DEV_RANDOM "/dev/random" -#endif - -const char *irk_strerror[RK_ERR_MAX] = - { - "no error", - "random device unvavailable"}; - -/* static functions */ -static unsigned long irk_hash(unsigned long key); - -void irk_dealloc_stream(irk_state *state) -{ - VSLStreamStatePtr stream = state->stream; - - if (stream) - { - vslDeleteStream(&stream); - } -} - -const MKL_INT brng_list[BRNG_KINDS] = { - VSL_BRNG_MT19937, - VSL_BRNG_SFMT19937, - VSL_BRNG_WH, - VSL_BRNG_MT2203, - VSL_BRNG_MCG31, - VSL_BRNG_R250, - VSL_BRNG_MRG32K3A, - VSL_BRNG_MCG59, - VSL_BRNG_PHILOX4X32X10, - VSL_BRNG_NONDETERM, - VSL_BRNG_ARS5}; - -/* Mersenne-Twister 2203 algorithm and Wichmann-Hill algorithm - * each have a parameter which produces a family of BRNG algorithms, - * MKL identifies individual members of these families by VSL_BRNG_ALGO + family_id - */ -#define SIZE_OF_MT2203_FAMILY 6024 -#define SIZE_OF_WH_FAMILY 273 - -int irk_get_brng_mkl(irk_state *state) -{ - int i, mkl_brng_id = vslGetStreamStateBrng(state->stream); - - if ((VSL_BRNG_MT2203 <= mkl_brng_id) && (mkl_brng_id < VSL_BRNG_MT2203 + SIZE_OF_MT2203_FAMILY)) - mkl_brng_id = VSL_BRNG_MT2203; - else if ((VSL_BRNG_WH <= mkl_brng_id) && (mkl_brng_id < VSL_BRNG_WH + SIZE_OF_WH_FAMILY)) - mkl_brng_id = VSL_BRNG_WH; - - for (i = 0; i < BRNG_KINDS; i++) - if (mkl_brng_id == brng_list[i]) - return i; - - return -1; -} - -int irk_get_brng_and_stream_mkl(irk_state *state, unsigned int *stream_id) -{ - int i, mkl_brng_id = vslGetStreamStateBrng(state->stream); - - if ((VSL_BRNG_MT2203 <= mkl_brng_id) && (mkl_brng_id < VSL_BRNG_MT2203 + SIZE_OF_MT2203_FAMILY)) - { - *stream_id = (unsigned int)(mkl_brng_id - VSL_BRNG_MT2203); - mkl_brng_id = VSL_BRNG_MT2203; - } - else if ((VSL_BRNG_WH <= mkl_brng_id) && (mkl_brng_id < VSL_BRNG_WH + SIZE_OF_WH_FAMILY)) - { - *stream_id = (unsigned int)(mkl_brng_id - VSL_BRNG_WH); - mkl_brng_id = VSL_BRNG_WH; - } - - for (i = 0; i < BRNG_KINDS; i++) - if (mkl_brng_id == brng_list[i]) - { - *stream_id = (unsigned int)(0); - return i; - } - - return -1; -} - -void irk_seed_mkl(irk_state *state, const unsigned int seed, const irk_brng_t brng, const unsigned int stream_id) -{ - VSLStreamStatePtr stream_loc; - int err = VSL_STATUS_OK; - const MKL_INT mkl_brng = brng_list[brng]; - - if (NULL == state->stream) - { - err = vslNewStream(&(state->stream), mkl_brng + stream_id, seed); - - assert(err == VSL_STATUS_OK); - } - else - { - err = vslNewStream(&stream_loc, mkl_brng + stream_id, seed); - assert(err == VSL_STATUS_OK); - - err = vslDeleteStream(&(state->stream)); - assert(err == VSL_STATUS_OK); - - state->stream = stream_loc; - } - if (err) - { - printf( - "irk_seed_mkl: encountered error when calling Intel(R) MKL\n"); - } -} - -void irk_seed_mkl_array(irk_state *state, const unsigned int seed_vec[], const int seed_len, - const irk_brng_t brng, const unsigned int stream_id) -{ - VSLStreamStatePtr stream_loc; - int err = VSL_STATUS_OK; - const MKL_INT mkl_brng = brng_list[brng]; - - if (NULL == state->stream) - { - - err = vslNewStreamEx(&(state->stream), mkl_brng + stream_id, (MKL_INT)seed_len, seed_vec); - - assert(err == VSL_STATUS_OK); - } - else - { - - err = vslNewStreamEx(&stream_loc, mkl_brng + stream_id, (MKL_INT)seed_len, seed_vec); - if (err == VSL_STATUS_OK) - { - - err = vslDeleteStream(&(state->stream)); - assert(err == VSL_STATUS_OK); - - state->stream = stream_loc; - } - } -} - -irk_error -irk_randomseed_mkl(irk_state *state, const irk_brng_t brng, const unsigned int stream_id) -{ -#ifndef _WIN32 - struct timeval tv; -#else - struct _timeb tv; -#endif - int no_err; - unsigned int *seed_array; - size_t buf_size = 624; - size_t seed_array_len = buf_size * sizeof(unsigned int); - - seed_array = (unsigned int *)malloc(seed_array_len); - no_err = irk_devfill(seed_array, seed_array_len, 0) == RK_NOERR; - - if (no_err) - { - /* ensures non-zero seed */ - seed_array[0] |= 0x80000000UL; - irk_seed_mkl_array(state, seed_array, buf_size, brng, stream_id); - free(seed_array); - - return RK_NOERR; - } - else - { - free(seed_array); - } - -#ifndef _WIN32 - gettimeofday(&tv, NULL); - irk_seed_mkl(state, irk_hash(getpid()) ^ irk_hash(tv.tv_sec) ^ irk_hash(tv.tv_usec) ^ irk_hash(clock()), brng, stream_id); -#else - _FTIME(&tv); - irk_seed_mkl(state, irk_hash(tv.time) ^ irk_hash(tv.millitm) ^ irk_hash(clock()), brng, stream_id); -#endif - - return RK_ENODEV; -} - -/* - * Python needs this to determine the amount memory to allocate for the buffer - */ -int irk_get_stream_size(irk_state *state) -{ - return vslGetStreamSize(state->stream); -} - -void irk_get_state_mkl(irk_state *state, char *buf) -{ - int err = vslSaveStreamM(state->stream, buf); - - if (err != VSL_STATUS_OK) - { - assert(err == VSL_STATUS_OK); - printf( - "irk_get_state_mkl encountered error when calling Intel(R) MKL\n"); - } -} - -int irk_set_state_mkl(irk_state *state, char *buf) -{ - int err = vslLoadStreamM(&(state->stream), buf); - - return (err == VSL_STATUS_OK) ? 0 : 1; -} - -int irk_leapfrog_stream_mkl(irk_state *state, const MKL_INT k, const MKL_INT nstreams) -{ - int err; - - err = vslLeapfrogStream(state->stream, k, nstreams); - - switch (err) - { - case VSL_STATUS_OK: - return 0; - case VSL_RNG_ERROR_LEAPFROG_UNSUPPORTED: - return 1; - default: - return -1; - } -} - -int irk_skipahead_stream_mkl(irk_state *state, const long long int nskip) -{ - int err; - - err = vslSkipAheadStream(state->stream, nskip); - - switch (err) - { - case VSL_STATUS_OK: - return 0; - case VSL_RNG_ERROR_SKIPAHEAD_UNSUPPORTED: - return 1; - default: - return -1; - } -} - -/* Thomas Wang 32 bits integer hash function */ -static unsigned long -irk_hash(unsigned long key) -{ - key += ~(key << 15); - key ^= (key >> 10); - key += (key << 3); - key ^= (key >> 6); - key += ~(key << 11); - key ^= (key >> 16); - return key; -} - -void irk_random_vec(irk_state *state, const int len, unsigned int *res) -{ - viRngUniformBits(VSL_RNG_METHOD_UNIFORMBITS_STD, state->stream, len, res); -} - -void irk_fill(void *buffer, size_t size, irk_state *state) -{ - unsigned int r; - unsigned char *buf = reinterpret_cast(buffer); - int err, len; - - /* len = size / 4 */ - len = (size >> 2); - err = viRngUniformBits32(VSL_RNG_METHOD_UNIFORMBITS32_STD, state->stream, len, (unsigned int *)buf); - assert(err == VSL_STATUS_OK); - - /* size = size % 4 */ - size &= 0x03; - if (!size) - { - return; - } - - buf += (len << 2); - err = viRngUniformBits32(VSL_RNG_METHOD_UNIFORMBITS32_STD, state->stream, 1, &r); - assert(err == VSL_STATUS_OK); - - for (; size; r >>= 8, size--) - { - *(buf++) = (unsigned char)(r & 0xFF); - } - if (err) - printf("irk_fill: error encountered when calling Intel(R) MKL \n"); -} - -irk_error -irk_devfill(void *buffer, size_t size, int strong) -{ -#ifndef _WIN32 - FILE *rfile; - int done; - - if (strong) - { - rfile = fopen(RK_DEV_RANDOM, "rb"); - } - else - { - rfile = fopen(RK_DEV_URANDOM, "rb"); - } - if (rfile == NULL) - { - return RK_ENODEV; - } - done = fread(buffer, size, 1, rfile); - fclose(rfile); - if (done) - { - return RK_NOERR; - } -#else - -#ifndef RK_NO_WINCRYPT - HCRYPTPROV hCryptProv; - BOOL done; - - if (!CryptAcquireContext(&hCryptProv, NULL, NULL, PROV_RSA_FULL, - CRYPT_VERIFYCONTEXT) || - !hCryptProv) - { - return RK_ENODEV; - } - done = CryptGenRandom(hCryptProv, size, (unsigned char *)buffer); - CryptReleaseContext(hCryptProv, 0); - if (done) - { - return RK_NOERR; - } -#endif - -#endif - return RK_ENODEV; -} - -irk_error -irk_altfill(void *buffer, size_t size, int strong, irk_state *state) -{ - irk_error err; - - err = irk_devfill(buffer, size, strong); - if (err) - { - irk_fill(buffer, size, state); - } - return err; -} diff --git a/mkl_random/src/randomkit.h b/mkl_random/src/randomkit.h deleted file mode 100644 index 485e596..0000000 --- a/mkl_random/src/randomkit.h +++ /dev/null @@ -1,134 +0,0 @@ -/* - Copyright (c) 2017-2019, Intel Corporation - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - * Neither the name of Intel Corporation nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR - SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER - CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - */ - -#include -#include "mkl_vsl.h" -#include "Python.h" -#include "numpy/npy_common.h" - -#ifndef _I_RANDOMKIT_ -#define _I_RANDOMKIT_ - -typedef struct irk_state_ -{ - VSLStreamStatePtr stream; -} irk_state; - -typedef enum { - RK_NOERR = 0, /* no error */ - RK_ENODEV = 1, /* no RK_DEV_RANDOM device */ - RK_ERR_MAX = 2 -} irk_error; - -/* if changing this, also adjust brng_list[BRNG_KINDS] in randomkit.c */ -#define BRNG_KINDS 11 - -typedef enum { - MT19937 = 0, - SFMT19937 = 1, - WH = 2, - MT2203 = 3, - MCG31 = 4, - R250 = 5, - MRG32K3A = 6, - MCG59 = 7, - PHILOX4X32X10 = 8, - NONDETERM = 9, - ARS5 = 10 -} irk_brng_t; - - -/* error strings */ -extern const char *irk_strerror[RK_ERR_MAX]; - -/* Maximum generated random value */ -#define RK_MAX 0xFFFFFFFFUL - -#ifdef __cplusplus -extern "C" { -#endif - -/* - * Initialize the RNG state using the given seed. - */ - - -/* - * Initialize the RNG state using a random seed. - * Uses /dev/random or, when unavailable, the clock (see randomkit.c). - * Returns RK_NOERR when no errors occurs. - * Returns RK_ENODEV when the use of RK_DEV_RANDOM failed (for example because - * there is no such device). In this case, the RNG was initialized using the - * clock. - */ - -/* - * Initialize the RNG state using the given seed. - */ -extern void irk_dealloc_stream(irk_state *state); -extern void irk_seed_mkl(irk_state *state, const unsigned int seed, const irk_brng_t brng, const unsigned int stream_id); -extern void irk_seed_mkl_array(irk_state *state, const unsigned int *seed_vec, - const int seed_len, const irk_brng_t brng, const unsigned int stream_id); -extern irk_error irk_randomseed_mkl(irk_state *state, const irk_brng_t brng, const unsigned int stream_id); -extern int irk_get_stream_size(irk_state *state); -extern void irk_get_state_mkl(irk_state *state, char * buf); -extern int irk_set_state_mkl(irk_state *state, char * buf); -extern int irk_get_brng_mkl(irk_state *state); -extern int irk_get_brng_and_stream_mkl(irk_state *state, unsigned int* stream_id); - -extern int irk_leapfrog_stream_mkl(irk_state *state, const int k, const int nstreams); -extern int irk_skipahead_stream_mkl(irk_state *state, const long long int nskip); - -/* - * fill the buffer with size random bytes - */ -extern void irk_fill(void *buffer, size_t size, irk_state *state); - -/* - * fill the buffer with randombytes from the random device - * Returns RK_ENODEV if the device is unavailable, or RK_NOERR if it is - * On Unix, if strong is defined, RK_DEV_RANDOM is used. If not, RK_DEV_URANDOM - * is used instead. This parameter has no effect on Windows. - * Warning: on most unixes RK_DEV_RANDOM will wait for enough entropy to answer - * which can take a very long time on quiet systems. - */ -extern irk_error irk_devfill(void *buffer, size_t size, int strong); - -/* - * fill the buffer using irk_devfill if the random device is available and using - * irk_fill if is is not - * parameters have the same meaning as irk_fill and irk_devfill - * Returns RK_ENODEV if the device is unavailable, or RK_NOERR if it is - */ -extern irk_error irk_altfill(void *buffer, size_t size, int strong, - irk_state *state); - -#ifdef __cplusplus -} -#endif - -#endif /* _I_RANDOMKIT_ */ diff --git a/mkl_random/tests/__init__.py b/mkl_random/tests/__init__.py deleted file mode 100644 index 8b917bd..0000000 --- a/mkl_random/tests/__init__.py +++ /dev/null @@ -1,25 +0,0 @@ -#!/usr/bin/env python -# Copyright (c) 2017-2019, Intel Corporation -# -# Redistribution and use in source and binary forms, with or without -# modification, are permitted provided that the following conditions are met: -# -# * Redistributions of source code must retain the above copyright notice, -# this list of conditions and the following disclaimer. -# * Redistributions in binary form must reproduce the above copyright -# notice, this list of conditions and the following disclaimer in the -# documentation and/or other materials provided with the distribution. -# * Neither the name of Intel Corporation nor the names of its contributors -# may be used to endorse or promote products derived from this software -# without specific prior written permission. -# -# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE -# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/mkl_random/tests/test_random.py b/mkl_random/tests/test_random.py deleted file mode 100644 index 3f9babd..0000000 --- a/mkl_random/tests/test_random.py +++ /dev/null @@ -1,1045 +0,0 @@ -#!/usr/bin/env python -# Copyright (c) 2017-2019, Intel Corporation -# -# Redistribution and use in source and binary forms, with or without -# modification, are permitted provided that the following conditions are met: -# -# * Redistributions of source code must retain the above copyright notice, -# this list of conditions and the following disclaimer. -# * Redistributions in binary form must reproduce the above copyright -# notice, this list of conditions and the following disclaimer in the -# documentation and/or other materials provided with the distribution. -# * Neither the name of Intel Corporation nor the names of its contributors -# may be used to endorse or promote products derived from this software -# without specific prior written permission. -# -# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE -# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -from typing import NamedTuple - -import numpy as np -import mkl_random as rnd -from numpy.testing import ( - assert_, assert_raises, assert_equal, - assert_warns, suppress_warnings) -from numpy.compat import asbytes -import sys -import warnings - -import pytest - - -def test_zero_scalar_seed(): - evs_zero_seed = { - 'MT19937' : 844, 'SFMT19937' : 857, - 'WH' : 0, 'MT2203' : 890, - 'MCG31' : 0, 'R250' : 229, - 'MRG32K3A' : 0, 'MCG59' : 0 } - for brng_algo in evs_zero_seed: - s = rnd.RandomState(0, brng = brng_algo) - assert_equal(s.get_state()[0], brng_algo) - assert_equal(s.randint(1000), evs_zero_seed[brng_algo]) - -def test_max_scalar_seed(): - evs_max_seed = { - 'MT19937' : 635, 'SFMT19937' : 25, - 'WH' : 100, 'MT2203' : 527, - 'MCG31' : 0, 'R250' : 229, - 'MRG32K3A' : 961, 'MCG59' : 0 } - for brng_algo in evs_max_seed: - s = rnd.RandomState(4294967295, brng = brng_algo) - assert_equal(s.get_state()[0], brng_algo) - assert_equal(s.randint(1000), evs_max_seed[brng_algo]) - - -def test_array_seed(): - s = rnd.RandomState(range(10), brng='MT19937') - assert_equal(s.randint(1000), 410) - s = rnd.RandomState(np.arange(10), brng='MT19937') - assert_equal(s.randint(1000), 410) - s = rnd.RandomState([0], brng='MT19937') - assert_equal(s.randint(1000), 844) - s = rnd.RandomState([4294967295], brng='MT19937') - assert_equal(s.randint(1000), 635) - - -def test_invalid_scalar_seed(): - # seed must be an unsigned 32 bit integers - pytest.raises(TypeError, rnd.RandomState, -0.5) - pytest.raises(ValueError, rnd.RandomState, -1) - - -def test_invalid_array_seed(): - # seed must be an unsigned 32 bit integers - pytest.raises(TypeError, rnd.RandomState, [-0.5]) - pytest.raises(ValueError, rnd.RandomState, [-1]) - pytest.raises(ValueError, rnd.RandomState, [4294967296]) - pytest.raises(ValueError, rnd.RandomState, [1, 2, 4294967296]) - pytest.raises(ValueError, rnd.RandomState, [1, -2, 4294967296]) - - -def test_non_deterministic_brng(): - rs = rnd.RandomState(brng='nondeterministic') - v = rs.rand(10) - assert isinstance(v, np.ndarray) - v = rs.randint(0, 10) - assert isinstance(v, int) - - -def test_binomial_n_zero(): - zeros = np.zeros(2, dtype='int') - for p in [0, .5, 1]: - assert rnd.binomial(0, p) == 0 - actual = rnd.binomial(zeros, p) - np.testing.assert_allclose(actual, zeros) - - -def test_binomial_p_is_nan(): - # Issue #4571. - pytest.raises(ValueError, rnd.binomial, 1, np.nan) - - -def test_multinomial_basic(): - rnd.multinomial(100, [0.2, 0.8]) - - -def test_multinomial_zero_probability(): - rnd.multinomial(100, [0.2, 0.8, 0.0, 0.0, 0.0]) - - -def test_multinomial_int_negative_interval(): - assert -5 <= rnd.randint(-5, -1) < -1 - x = rnd.randint(-5, -1, 5) - assert np.all(-5 <= x) - assert np.all(x < -1) - - -def test_size(): - # gh-3173 - p = [0.5, 0.5] - assert_equal(rnd.multinomial(1, p, np.uint32(1)).shape, (1, 2)) - assert_equal(rnd.multinomial(1, p, np.uint32(1)).shape, (1, 2)) - assert_equal(rnd.multinomial(1, p, np.uint32(1)).shape, (1, 2)) - assert_equal(rnd.multinomial(1, p, [2, 2]).shape, (2, 2, 2)) - assert_equal(rnd.multinomial(1, p, (2, 2)).shape, (2, 2, 2)) - assert_equal(rnd.multinomial(1, p, np.array((2, 2))).shape, - (2, 2, 2)) - - pytest.raises(TypeError, rnd.multinomial, 1, p, - np.float64(1)) - -class RngState(NamedTuple): - seed: int - prng: object - state: object - - -@pytest.fixture -def rng_state(): - seed = 1234567890 - prng = rnd.RandomState(seed) - state = prng.get_state() - return RngState(seed, prng, state) - - -def test_set_state_basic(rng_state): - sample_ref = rng_state.prng.tomaxint(16) - new_rng = rnd.RandomState() - new_rng.set_state(rng_state.state) - sample_from_new = new_rng.tomaxint(16) - assert_equal(sample_ref, sample_from_new) - - -def test_set_state_gaussian_reset(rng_state): - # Make sure the cached every-other-Gaussian is reset. - sample_ref = rng_state.prng.standard_normal(size=3) - new_rng = rnd.RandomState() - new_rng.set_state(rng_state.state) - sample_from_new = new_rng.standard_normal(size=3) - assert_equal(sample_ref, sample_from_new) - - -def test_set_state_gaussian_reset_in_media_res(rng_state): - # When the state is saved with a cached Gaussian, make sure the - # cached Gaussian is restored. - prng = rng_state.prng - _ = prng.standard_normal() - state_after_draw = prng.get_state() - sample_ref = prng.standard_normal(size=3) - new_rng = rnd.RandomState() - new_rng.set_state(state_after_draw) - sample_from_new = new_rng.standard_normal(size=3) - assert_equal(sample_ref, sample_from_new) - - -def test_set_state_backward_compatibility(rng_state): - # Make sure we can accept old state tuples that do not have the - # cached Gaussian value. - if len(rng_state.state) == 5: - state_old_format = rng_state.state[:-2] - x1 = rng_state.prng.standard_normal(size=16) - new_rng = rnd.RandomState() - new_rng.set_state(state_old_format) - x2 = new_rng.standard_normal(size=16) - new_rng.set_state(rng_state.state) - x3 = new_rng.standard_normal(size=16) - assert_equal(x1, x2) - assert_equal(x1, x3) - - -def test_set_state_negative_binomial(rng_state): - # Ensure that the negative binomial results take floating point - # arguments without truncation. - v = rng_state.prng.negative_binomial(0.5, 0.5) - assert isinstance(v, int) - - -class RandIntData(NamedTuple): - rfunc : object - itype : list - - -@pytest.fixture -def randint(): - rfunc_method = rnd.randint - integral_dtypes = [ - np.bool_, np.int8, np.uint8, np.int16, np.uint16, - np.int32, np.uint32, np.int64, np.uint64 - ] - return RandIntData(rfunc_method, integral_dtypes) - - -def test_randint_unsupported_type(randint): - pytest.raises(TypeError, randint.rfunc, 1, dtype=np.float64) - - -def test_randint_bounds_checking(randint): - for dt in randint.itype: - lbnd = 0 if dt is np.bool_ else np.iinfo(dt).min - ubnd = 2 if dt is np.bool_ else np.iinfo(dt).max + 1 - pytest.raises(ValueError, randint.rfunc, lbnd - 1, ubnd, dtype=dt) - pytest.raises(ValueError, randint.rfunc, lbnd, ubnd + 1, dtype=dt) - pytest.raises(ValueError, randint.rfunc, ubnd, lbnd, dtype=dt) - pytest.raises(ValueError, randint.rfunc, 1, 0, dtype=dt) - - -def test_randint_rng_zero_and_extremes(randint): - for dt in randint.itype: - lbnd = 0 if dt is np.bool_ else np.iinfo(dt).min - ubnd = 2 if dt is np.bool_ else np.iinfo(dt).max + 1 - tgt = ubnd - 1 - assert_equal(randint.rfunc(tgt, tgt + 1, size=1000, dtype=dt), tgt) - tgt = lbnd - assert_equal(randint.rfunc(tgt, tgt + 1, size=1000, dtype=dt), tgt) - tgt = lbnd + ((ubnd - lbnd)//2) - assert_equal(randint.rfunc(tgt, tgt + 1, size=1000, dtype=dt), tgt) - - -def test_randint_in_bounds_fuzz(randint): - # Don't use fixed seed - rnd.seed() - for dt in randint.itype[1:]: - for ubnd in [4, 8, 16]: - vals = randint.rfunc(2, ubnd, size=2**16, dtype=dt) - assert_(vals.max() < ubnd) - assert_(vals.min() >= 2) - vals = randint.rfunc(0, 2, size=2**16, dtype='bool') - assert (vals.max() < 2) - assert (vals.min() >= 0) - - -def test_randint_repeatability(randint): - import hashlib - # We use a md5 hash of generated sequences of 1000 samples - # in the range [0, 6) for all but np.bool, where the range - # is [0, 2). Hashes are for little endian numbers. - tgt = {'bool': '4fee98a6885457da67c39331a9ec336f', - 'int16': '80a5ff69c315ab6f80b03da1d570b656', - 'int32': '15a3c379b6c7b0f296b162194eab68bc', - 'int64': 'ea9875f9334c2775b00d4976b85a1458', - 'int8': '0f56333af47de94930c799806158a274', - 'uint16': '80a5ff69c315ab6f80b03da1d570b656', - 'uint32': '15a3c379b6c7b0f296b162194eab68bc', - 'uint64': 'ea9875f9334c2775b00d4976b85a1458', - 'uint8': '0f56333af47de94930c799806158a274'} - - for dt in randint.itype[1:]: - rnd.seed(1234, brng='MT19937') - - # view as little endian for hash - if sys.byteorder == 'little': - val = randint.rfunc(0, 6, size=1000, dtype=dt) - else: - val = randint.rfunc(0, 6, size=1000, dtype=dt).byteswap() - - res = hashlib.md5(val.view(np.int8)).hexdigest() - assert tgt[np.dtype(dt).name] == res - - # bools do not depend on endianess - rnd.seed(1234, brng='MT19937') - val = randint.rfunc(0, 2, size=1000, dtype='bool').view(np.int8) - res = hashlib.md5(val).hexdigest() - assert (tgt[np.dtype('bool').name] == res) - - -def test_randint_respect_dtype_singleton(randint): - # See gh-7203 - for dt in randint.itype: - lbnd = 0 if dt is np.bool_ else np.iinfo(dt).min - ubnd = 2 if dt is np.bool_ else np.iinfo(dt).max + 1 - - sample = randint.rfunc(lbnd, ubnd, dtype=dt) - assert_equal(sample.dtype, np.dtype(dt)) - - for dt in (bool, int): - lbnd = 0 if dt is bool else np.iinfo(np.dtype(dt)).min - ubnd = 2 if dt is bool else np.iinfo(np.dtype(dt)).max + 1 - - # gh-7284: Ensure that we get Python data types - sample = randint.rfunc(lbnd, ubnd, dtype=dt) - assert not hasattr(sample, 'dtype') - assert (type(sample) == dt) - - -class RandomDistData(NamedTuple): - seed : int - brng : str - - -@pytest.fixture -def randomdist(): - return RandomDistData(seed=1234567890, brng='SFMT19937') - - -# Make sure the random distribution returns the correct value for a -# given seed. Low value of decimal argument is intended, since functional -# transformations's implementation or approximations thereof used to produce non-uniform -# random variates can vary across platforms, yet be statistically indistinguishable to the end user, -# that is no computationally feasible statistical experiment can detect the difference. - -def test_randomdist_rand(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.rand(3, 2) - desired = np.array([[0.9838694715872407, 0.019142669625580311], - [0.1767608025111258, 0.70966427633538842], - [0.518550637178123, 0.98780936631374061]]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - -def test_randomdist_randn(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.randn(3, 2) - desired = np.array([[2.1411609928913298, -2.0717866791744819], - [-0.92778018318550248, 0.55240420724917727], - [0.04651632135517459, 2.2510674226058036]]) - np.testing.assert_allclose(actual, desired, atol=1e-10) - - -def test_randomdist_randint(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.randint(-99, 99, size=(3, 2)) - desired = np.array([[95, -96], [-65, 41], [3, 96]]) - np.testing.assert_array_equal(actual, desired) - - -def test_randomdist_random_integers(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - with suppress_warnings() as sup: - w = sup.record(DeprecationWarning) - actual = rnd.random_integers(-99, 99, size=(3, 2)) - assert len(w) == 1 - - desired = np.array([[96, -96], [-64, 42], [4, 97]]) - np.testing.assert_array_equal(actual, desired) - - -def test_random_integers_max_int(): - # Tests whether random_integers can generate the - # maximum allowed Python int that can be converted - # into a C long. Previous implementations of this - # method have thrown an OverflowError when attempting - # to generate this integer. - with suppress_warnings() as sup: - w = sup.record(DeprecationWarning) - actual = rnd.random_integers(np.iinfo('l').max, - np.iinfo('l').max) - assert len(w) == 1 - desired = np.iinfo('l').max - np.testing.assert_equal(actual, desired) - - -def test_random_integers_deprecated(): - with warnings.catch_warnings(): - warnings.simplefilter("error", DeprecationWarning) - - # DeprecationWarning raised with high == None - assert_raises(DeprecationWarning, - rnd.random_integers, - np.iinfo('l').max) - - # DeprecationWarning raised with high != None - assert_raises(DeprecationWarning, - rnd.random_integers, - np.iinfo('l').max, np.iinfo('l').max) - - -def test_randomdist_random_sample(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.random_sample((3, 2)) - desired = np.array([[0.9838694715872407, 0.01914266962558031], - [0.1767608025111258, 0.7096642763353884], - [0.518550637178123, 0.9878093663137406]]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - -def test_randomdist_choice_uniform_replace(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.choice(4, 4) - desired = np.array([3, 0, 0, 2]) - np.testing.assert_array_equal(actual, desired) - - -def test_randomdist_choice_nonuniform_replace(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.choice(4, 4, p=[0.4, 0.4, 0.1, 0.1]) - desired = np.array([3, 0, 0, 1]) - np.testing.assert_array_equal(actual, desired) - - -def test_randomdist_choice_nonuniform_replace(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.choice(4, 4, p=[0.4, 0.4, 0.1, 0.1]) - desired = np.array([3, 0, 0, 1]) - np.testing.assert_array_equal(actual, desired) - - -def test_randomdist_choice_uniform_noreplace(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.choice(4, 3, replace=False) - desired = np.array([2, 1, 3]) - np.testing.assert_array_equal(actual, desired) - - -def test_randomdist_choice_nonuniform_noreplace(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.choice(4, 3, replace=False, - p=[0.1, 0.3, 0.5, 0.1]) - desired = np.array([3, 0, 1]) - np.testing.assert_array_equal(actual, desired) - - -def test_randomdist_choice_noninteger(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.choice(['a', 'b', 'c', 'd'], 4) - desired = np.array(['d', 'a', 'a', 'c']) - np.testing.assert_array_equal(actual, desired) - - -def test_choice_exceptions(): - sample = rnd.choice - pytest.raises(ValueError, sample, -1, 3) - pytest.raises(ValueError, sample, 3., 3) - pytest.raises(ValueError, sample, [[1, 2], [3, 4]], 3) - pytest.raises(ValueError, sample, [], 3) - pytest.raises(ValueError, sample, [1, 2, 3, 4], 3, - p=[[0.25, 0.25], [0.25, 0.25]]) - pytest.raises(ValueError, sample, [1, 2], 3, p=[0.4, 0.4, 0.2]) - pytest.raises(ValueError, sample, [1, 2], 3, p=[1.1, -0.1]) - pytest.raises(ValueError, sample, [1, 2], 3, p=[0.4, 0.4]) - pytest.raises(ValueError, sample, [1, 2, 3], 4, replace=False) - pytest.raises(ValueError, sample, [1, 2, 3], 2, replace=False, - p=[1, 0, 0]) - - -def test_choice_return_shape(): - p = [0.1, 0.9] - # Check scalar - assert np.isscalar(rnd.choice(2, replace=True)) - assert np.isscalar(rnd.choice(2, replace=False)) - assert np.isscalar(rnd.choice(2, replace=True, p=p)) - assert np.isscalar(rnd.choice(2, replace=False, p=p)) - assert np.isscalar(rnd.choice([1, 2], replace=True)) - assert rnd.choice([None], replace=True) is None - a = np.array([1, 2]) - arr = np.empty(1, dtype=object) - arr[0] = a - assert rnd.choice(arr, replace=True) is a - - # Check 0-d array - s = tuple() - assert not np.isscalar(rnd.choice(2, s, replace=True)) - assert not np.isscalar(rnd.choice(2, s, replace=False)) - assert not np.isscalar(rnd.choice(2, s, replace=True, p=p)) - assert not np.isscalar(rnd.choice(2, s, replace=False, p=p)) - assert not np.isscalar(rnd.choice([1, 2], s, replace=True)) - assert rnd.choice([None], s, replace=True).ndim == 0 - a = np.array([1, 2]) - arr = np.empty(1, dtype=object) - arr[0] = a - assert rnd.choice(arr, s, replace=True).item() is a - - # Check multi dimensional array - s = (2, 3) - p = [0.1, 0.1, 0.1, 0.1, 0.4, 0.2] - assert_(rnd.choice(6, s, replace=True).shape, s) - assert_(rnd.choice(6, s, replace=False).shape, s) - assert_(rnd.choice(6, s, replace=True, p=p).shape, s) - assert_(rnd.choice(6, s, replace=False, p=p).shape, s) - assert_(rnd.choice(np.arange(6), s, replace=True).shape, s) - - -def test_randomdist_bytes(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.bytes(10) - desired = asbytes('\xa4\xde\xde{\xb4\x88\xe6\x84*2') - np.testing.assert_equal(actual, desired) - - -def test_randomdist_shuffle(randomdist): - # Test lists, arrays (of various dtypes), and multidimensional versions - # of both, c-contiguous or not: - for conv in [lambda x: np.array([]), - lambda x: x, - lambda x: np.asarray(x).astype(np.int8), - lambda x: np.asarray(x).astype(np.float32), - lambda x: np.asarray(x).astype(np.complex64), - lambda x: np.asarray(x).astype(object), - lambda x: [(i, i) for i in x], - lambda x: np.asarray([[i, i] for i in x]), - lambda x: np.vstack([x, x]).T, - # gh-4270 - lambda x: np.asarray([(i, i) for i in x], - [("a", object, (1,)), - ("b", np.int32, (1,))])]: - rnd.seed(randomdist.seed, brng=randomdist.brng) - alist = conv([1, 2, 3, 4, 5, 6, 7, 8, 9, 0]) - rnd.shuffle(alist) - actual = alist - desired = conv([9, 8, 5, 1, 6, 4, 7, 2, 3, 0]) - np.testing.assert_array_equal(actual, desired) - - -def test_shuffle_masked(): - # gh-3263 - a = np.ma.masked_values(np.reshape(range(20), (5,4)) % 3 - 1, -1) - b = np.ma.masked_values(np.arange(20) % 3 - 1, -1) - a_orig = a.copy() - b_orig = b.copy() - for i in range(50): - rnd.shuffle(a) - assert_equal( - sorted(a.data[~a.mask]), sorted(a_orig.data[~a_orig.mask])) - rnd.shuffle(b) - assert_equal( - sorted(b.data[~b.mask]), sorted(b_orig.data[~b_orig.mask])) - - -def test_randomdist_beta(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.beta(.1, .9, size=(3, 2)) - desired = np.array( - [[0.9856952034381025, 4.35869375658114e-08], - [0.0014230232791189966, 1.4981856288121975e-06], - [1.426135763875603e-06, 4.5801786040477326e-07]]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - -def test_randomdist_binomial(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.binomial(100.123, .456, size=(3, 2)) - desired = np.array([[43, 48], [55, 48], [46, 53]]) - np.testing.assert_array_equal(actual, desired) - - -def test_randomdist_chisquare(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.chisquare(50, size=(3, 2)) - desired = np.array([[50.955833609920589, 50.133178918244099], - [61.513615847062013, 50.757127871422448], - [52.79816819717081, 49.973023331993552]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-10) - - -def test_randomdist_dirichlet(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - alpha = np.array([51.72840233779265162, 39.74494232180943953]) - actual = rnd.dirichlet(alpha, size=(3, 2)) - desired = np.array([[[0.6332947001908874, 0.36670529980911254], - [0.5376828907571894, 0.4623171092428107]], - [[0.6835615930093024, 0.3164384069906976], - [0.5452378139016114, 0.45476218609838875]], - [[0.6498494402738553, 0.3501505597261446], - [0.5622024400324822, 0.43779755996751785]]]) - np.testing.assert_allclose(actual, desired, atol=4e-10, rtol=4e-10) - - -def test_dirichlet_size(): - # gh-3173 - p = np.array([51.72840233779265162, 39.74494232180943953]) - assert_equal(rnd.dirichlet(p, np.uint32(1)).shape, (1, 2)) - assert_equal(rnd.dirichlet(p, np.uint32(1)).shape, (1, 2)) - assert_equal(rnd.dirichlet(p, np.uint32(1)).shape, (1, 2)) - assert_equal(rnd.dirichlet(p, [2, 2]).shape, (2, 2, 2)) - assert_equal(rnd.dirichlet(p, (2, 2)).shape, (2, 2, 2)) - assert_equal(rnd.dirichlet(p, np.array((2, 2))).shape, (2, 2, 2)) - - assert_raises(TypeError, rnd.dirichlet, p, np.float64(1)) - - -def test_randomdist_exponential(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.exponential(1.1234, size=(3, 2)) - desired = np.array([[0.01826877748252199, 4.4439855151117005], - [1.9468048583654507, 0.38528493864979607], - [0.7377565464231758, 0.013779117663987912]]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - -def test_randomdist_f(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.f(12, 77, size=(3, 2)) - desired = np.array([[1.325076177478387, 0.8670927327120197], - [2.1190792007836827, 0.9095296301824258], - [1.4953697422236187, 0.9547125618834837]]) - np.testing.assert_allclose(actual, desired, atol=1e-8, rtol=1e-9) - - -def test_randomdist_gamma(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.gamma(5, 3, size=(3, 2)) - desired = np.array([[15.073510060334929, 14.525495858042685], - [22.73897210140115, 14.94044782480266], - [16.327929995271095, 14.419692564592896]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-10) - - -def test_randomdsit_geometric(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.geometric(.123456789, size=(3, 2)) - desired = np.array([[0, 30], [13, 2], [4, 0]]) - np.testing.assert_array_equal(actual, desired) - - -def test_randomdist_gumbel(randomdist): - rnd.seed(randomdist.seed, randomdist.brng) - actual = rnd.gumbel(loc=.123456789, scale=2.0, size=(3, 2)) - desired = np.array([[-8.114386462751979, 2.873840411460178], - [1.2231161758452016, -2.0168070493213532], - [-0.7175455966332102, -8.678464904504784]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-10) - - -def test_randomdist_hypergeometric(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.hypergeometric(10.1, 5.5, 14, size=(3, 2)) - desired = np.array([[10, 9], [9, 10], [9, 10]]) - np.testing.assert_array_equal(actual, desired) - - # Test nbad = 0 - actual = rnd.hypergeometric(5, 0, 3, size=4) - desired = np.array([3, 3, 3, 3]) - np.testing.assert_array_equal(actual, desired) - - actual = rnd.hypergeometric(15, 0, 12, size=4) - desired = np.array([12, 12, 12, 12]) - np.testing.assert_array_equal(actual, desired) - - # Test ngood = 0 - actual = rnd.hypergeometric(0, 5, 3, size=4) - desired = np.array([0, 0, 0, 0]) - np.testing.assert_array_equal(actual, desired) - - actual = rnd.hypergeometric(0, 15, 12, size=4) - desired = np.array([0, 0, 0, 0]) - np.testing.assert_array_equal(actual, desired) - - -def test_randomdist_laplace(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.laplace(loc=.123456789, scale=2.0, size=(3, 2)) - desired = np.array([[0.15598087210935016, -3.3424589282252994], - [-1.189978401356375, 3.0607925598732253], - [0.0030946589024587745, 3.14795824463997]]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - -def test_randomdist_logistic(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.logistic(loc=.123456789, scale=2.0, size=(3, 2)) - desired = np.array([[8.345015961402696, -7.749557532940552], - [-2.9534419690278444, 1.910964962531448], - [0.2719300361499433, 8.913100396613983]]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - -def test_randomdist_lognormal(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.lognormal(mean=.123456789, sigma=2.0, size=(3, 2)) - desired = np.array([[81.92291750917155, 0.01795087229603931], - [0.1769118704670423, 3.415299544410577], - [1.2417099625339398, 102.0631392685238]]) - np.testing.assert_allclose(actual, desired, atol=1e-6, rtol=1e-10) - actual = rnd.lognormal(mean=.123456789, sigma=2.0, size=(3,2), - method='Box-Muller2') - desired = np.array([[0.2585388231094821, 0.43734953048924663], - [26.050836228611697, 26.76266237820882], - [0.24216420175675096, 0.2481945765083541]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-10) - - -def test_randomdist_logseries(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.logseries(p=.923456789, size=(3, 2)) - desired = np.array([[18, 1], [1, 1], [5, 19]]) - np.testing.assert_array_equal(actual, desired) - - -def test_randomdist_multinomial(randomdist): - rs = rnd.RandomState(randomdist.seed, brng=randomdist.brng) - actual = rs.multinomial(20, [1/6.]*6, size=(3, 2)) - desired = np.full((3, 2), 20, dtype=actual.dtype) - np.testing.assert_array_equal(actual.sum(axis=-1), desired) - expected = np.array([ - [[6, 2, 1, 3, 2, 6], [7, 5, 1, 2, 3, 2]], - [[5, 1, 8, 3, 2, 1], [4, 6, 0, 4, 4, 2]], - [[6, 3, 1, 4, 4, 2], [3, 2, 4, 2, 1, 8]]], actual.dtype) - np.testing.assert_array_equal(actual, expected) - - -def test_randomdist_multivariate_normal(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - mean = (.123456789, 10) - # Hmm... not even symmetric. - cov = [[1, 0], [1, 0]] - size = (3, 2) - actual = rnd.multivariate_normal(mean, cov, size) - desired = np.array([[[-2.42282709811266, 10.0], - [1.2267795840027274, 10.0]], - [[0.06813924868067336, 10.0], - [1.001190462507746, 10.0]], - [[-1.74157261455869, 10.0], - [1.0400952859037553, 10.0]]]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - # Check for default size, was raising deprecation warning - actual = rnd.multivariate_normal(mean, cov) - desired = np.array([1.0579899448949994, 10.0]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - # Check that non positive-semidefinite covariance raises warning - mean = [0, 0] - cov = [[1, 1 + 1e-10], [1 + 1e-10, 1]] - assert_warns(RuntimeWarning, rnd.multivariate_normal, mean, cov) - - -def test_randomdist_multinormal_cholesky(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - mean = (.123456789, 10) - # lower-triangular cholesky matrix - chol_mat = [[1, 0], [-0.5, 1]] - size = (3, 2) - actual = rnd.multinormal_cholesky(mean, chol_mat, size, method='ICDF') - desired = np.array([[[2.26461778189133, 6.857632824379853], - [-0.8043233941855025, 11.01629429884193]], - [[0.1699731103551746, 12.227809261928217], - [-0.6146263106001378, 9.893801873973892]], - [[1.691753328795276, 10.797627196240155], - [-0.647341237129921, 9.626899489691816]]]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - -def test_randomdist_negative_binomial(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.negative_binomial(n=100, p=.12345, size=(3, 2)) - desired = np.array([[667, 679], [677, 676], [779, 648]]) - np.testing.assert_array_equal(actual, desired) - - -def test_randomdist_noncentral_chisquare(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.noncentral_chisquare(df=5, nonc=5, size=(3, 2)) - desired = np.array([[5.871334619375055, 8.756238913383225], - [17.29576535176833, 3.9028417087862177], - [5.1315133729432505, 9.942717979531027]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-10) - - actual = rnd.noncentral_chisquare(df=.5, nonc=.2, size=(3, 2)) - desired = np.array([[0.0008971007339949436, 0.08948578998156566], - [0.6721835871997511, 2.8892645287699352], - [5.0858149962761007e-05, 1.7315797643658821]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-10) - - -def test_randomdist_noncentral_f(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.noncentral_f(dfnum=5, dfden=2, nonc=1, - size=(3, 2)) - desired = np.array([[0.2216297348371284, 0.7632696724492449], - [98.67664232828238, 0.9500319825372799], - [0.3489618249246971, 1.5035633972571092]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-10) - - -def test_randomdist_normal(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.normal(loc=.123456789, scale=2.0, size=(3, 2)) - desired = np.array([[4.405778774782659, -4.020116569348963], - [-1.732103577371005, 1.2282652034983546], - [0.21648943171034918, 4.625591634211608]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-10) - - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.normal(loc=.123456789, scale=2.0, size=(3, 2), method="BoxMuller") - desired = np.array([[0.16673479781277187, -3.4809986872165952], - [-0.05193761082535492, 3.249201213154922], - [-0.11915582299214138, 3.555636100927892]]) - np.testing.assert_allclose(actual, desired, atol=1e-8, rtol=1e-8) - - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.normal(loc=.123456789, scale=2.0, size=(3, 2), method="BoxMuller2") - desired = np.array([[0.16673479781277187, 0.48153966449249175], - [-3.4809986872165952, -0.8101190082826486], - [-0.051937610825354905, 2.4088402362484342]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-7) - - -def test_randomdist_pareto(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.pareto(a=.123456789, size=(3, 2)) - desired = np.array( - [[0.14079174875385214, 82372044085468.92], - [1247881.6368437486, 15.086855668610944], - [203.2638558933401, 0.10445383654349749]]) - # For some reason on 32-bit x86 Ubuntu 12.10 the [1, 0] entry in this - # matrix differs by 24 nulps. Discussion: - # http://mail.scipy.org/pipermail/numpy-discussion/2012-September/063801.html - # Consensus is that this is probably some gcc quirk that affects - # rounding but not in any important way, so we just use a looser - # tolerance on this test: - np.testing.assert_array_almost_equal_nulp(actual, desired, nulp=30) - - -def test_randomdist_poisson(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.poisson(lam=.123456789, size=(3, 2)) - desired = np.array([[1, 0], [0, 0], [0, 1]]) - np.testing.assert_array_equal(actual, desired) - - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.poisson(lam=1234.56789, size=(3, 2)) - desired = np.array([[1310, 1162], [1202, 1254], [1236, 1314]]) - np.testing.assert_array_equal(actual, desired) - - -def test_poisson_exceptions(): - lambig = np.iinfo('l').max - lamneg = -1 - assert_raises(ValueError, rnd.poisson, lamneg) - assert_raises(ValueError, rnd.poisson, [lamneg]*10) - assert_raises(ValueError, rnd.poisson, lambig) - assert_raises(ValueError, rnd.poisson, [lambig]*10) - - -def test_randomdist_power(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.power(a=.123456789, size=(3, 2)) - desired = np.array([[0.8765841803224415, 1.2140041091640163e-14], - [8.013574117268635e-07, 0.06216255187464781], - [0.004895628723087296, 0.9054248959192386]]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - -def test_randomdist_rayleigh(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.rayleigh(scale=10, size=(3, 2)) - desired = np.array([[1.80344345931194, 28.127692489122378], - [18.6169699930609, 8.282068232120208], - [11.460520015934597, 1.5662406536967712]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-10) - - -def test_randomdist_standard_cauchy(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.standard_cauchy(size=(3, 2)) - desired = np.array([[19.716487700629912, -16.608240276131227], - [-1.6117703817332278, 0.7739915895826882], - [0.058344614106131, 26.09825325697747]]) - np.testing.assert_allclose(actual, desired, atol=1e-9, rtol=1e-10) - - -def test_randomdist_standard_exponential(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.standard_exponential(size=(3, 2)) - desired = np.array([[0.016262041554675085, 3.955835423813157], - [1.7329578586126497, 0.3429632710074738], - [0.6567175951781875, 0.012265548926462446]]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - -def test_randomdist_standard_gamma(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.standard_gamma(shape=3, size=(3, 2)) - desired = np.array([[2.939330965027084, 2.799606052259993], - [4.988193705918075, 2.905305108691164], - [3.2630929395548147, 2.772756340265377]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-10) - - -def test_randomdist_standard_normal(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.standard_normal(size=(3, 2)) - desired = np.array([[2.1411609928913298, -2.071786679174482], - [-0.9277801831855025, 0.5524042072491773], - [0.04651632135517459, 2.2510674226058036]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-10) - - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.standard_normal(size=(3, 2), method='BoxMuller2') - desired = np.array([[0.021639004406385935, 0.17904143774624587], - [-1.8022277381082976, -0.4667878986413243], - [-0.08769719991267745, 1.1426917236242171]]) - np.testing.assert_allclose(actual, desired, atol=1e-7, rtol=1e-10) - - -def test_randomdist_standard_t(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.standard_t(df=10, size=(3, 2)) - desired = np.array([[-0.783927044239963, 0.04762883516531178], - [0.7624597987725193, -1.8045540288955506], - [-1.2657694296239195, 0.307870906117017]]) - np.testing.assert_allclose(actual, desired, atol=5e-10, rtol=5e-10) - - -def test_randomdist_triangular(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.triangular(left=5.12, mode=10.23, right=20.34, - size=(3, 2)) - desired = np.array([[18.764540652669638, 6.340166306695037], - [8.827752689522429, 13.65605077739865], - [11.732872979633328, 18.970392754850423]]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - -def test_randomdist_uniform(randomdist): - rnd.seed(randomdist.seed, brng=randomdist.brng) - actual = rnd.uniform(low=1.23, high=10.54, size=(3, 2)) - desired = np.array([[10.38982478047721, 1.408218254214153], - [2.8756430713785814, 7.836974412682466], - [6.057706432128325, 10.426505200380925]]) - np.testing.assert_allclose(actual, desired, atol=1e-10, rtol=1e-10) - - -def test_uniform_range_bounds(): - fmin = np.finfo('float').min - fmax = np.finfo('float').max - - func = rnd.uniform - np.testing.assert_raises(OverflowError, func, -np.inf, 0) - np.testing.assert_raises(OverflowError, func, 0, np.inf) - # this should not throw any error, since rng can be sampled as fmin*u + fmax*(1-u) - # for 0 -np.pi) and np.all(r <= np.pi)) - - -def test_hypergeometric_range(): - # Test for ticket #921 - assert_(np.all(rnd.hypergeometric(3, 18, 11, size=10) < 4)) - assert_(np.all(rnd.hypergeometric(18, 3, 11, size=10) > 0)) - - # Test for ticket #5623 - args = [ - (2**20 - 2, 2**20 - 2, 2**20 - 2), # Check for 32-bit systems - (2 ** 30 - 1, 2 ** 30 - 2, 2 ** 30 - 1) - ] - for arg in args: - assert_(rnd.hypergeometric(*arg) > 0) - - -def test_logseries_convergence(): - # Test for ticket #923 - N = 1000 - rnd.seed(0, brng='MT19937') - rvsn = rnd.logseries(0.8, size=N) - # these two frequency counts should be close to theoretical - # numbers with this large sample - # theoretical large N result is 0.49706795 - freq = np.sum(rvsn == 1) / float(N) - msg = "Frequency was %f, should be > 0.45" % freq - assert_(freq > 0.45, msg) - # theoretical large N result is 0.19882718 - freq = np.sum(rvsn == 2) / float(N) - msg = "Frequency was %f, should be < 0.23" % freq - assert_(freq < 0.23, msg) - - -def test_permutation_longs(): - rnd.seed(1234, brng='MT19937') - a = rnd.permutation(12) - rnd.seed(1234, brng='MT19937') - b = rnd.permutation(long(12)) - assert_array_equal(a, b) - - -def test_randint_range(): - # Test for ticket #1690 - lmax = np.iinfo('l').max - lmin = np.iinfo('l').min - try: - rnd.randint(lmin, lmax) - except: - raise AssertionError - - -def test_shuffle_mixed_dimension(): - # Test for trac ticket #2074 - for t in [[1, 2, 3, None], - [(1, 1), (2, 2), (3, 3), None], - [1, (2, 2), (3, 3), None], - [(1, 1), 2, 3, None]]: - rnd.seed(12345, brng='MT2203') - shuffled = np.array(list(t), dtype=object) - rnd.shuffle(shuffled) - expected = np.array([t[0], t[2], t[1], t[3]], dtype=object) - assert_array_equal(shuffled, expected) - - -def test_call_within_randomstate(): - # Check that custom RandomState does not call into global state - m = rnd.RandomState() - res = np.array([5, 7, 5, 4, 5, 5, 6, 9, 6, 1]) - for i in range(3): - rnd.seed(i) - m.seed(4321, brng='SFMT19937') - # If m.state is not honored, the result will change - assert_array_equal(m.choice(10, size=10, p=np.ones(10)/10.), res) - - -def test_multivariate_normal_size_types(): - # Test for multivariate_normal issue with 'size' argument. - # Check that the multivariate_normal size argument can be a - # numpy integer. - rnd.multivariate_normal([0], [[0]], size=1) - rnd.multivariate_normal([0], [[0]], size=np.int_(1)) - rnd.multivariate_normal([0], [[0]], size=np.int64(1)) - - -def test_beta_small_parameters(): - # Test that beta with small a and b parameters does not produce - # NaNs due to roundoff errors causing 0 / 0, gh-5851 - rnd.seed(1234567890, brng='MT19937') - x = rnd.beta(0.0001, 0.0001, size=100) - assert_(not np.any(np.isnan(x)), 'Nans in rnd.beta') - - -def test_choice_sum_of_probs_tolerance(): - # The sum of probs should be 1.0 with some tolerance. - # For low precision dtypes the tolerance was too tight. - # See numpy github issue 6123. - rnd.seed(1234, brng='MT19937') - a = [1, 2, 3] - counts = [4, 4, 2] - for dt in np.float16, np.float32, np.float64: - probs = np.array(counts, dtype=dt) / sum(counts) - c = rnd.choice(a, p=probs) - assert_(c in a) - assert_raises(ValueError, rnd.choice, a, p=probs*0.9) - - -def test_shuffle_of_array_of_different_length_strings(): - # Test that permuting an array of different length strings - # will not cause a segfault on garbage collection - # Tests gh-7710 - rnd.seed(1234, brng='MT19937') - - a = np.array(['a', 'a' * 1000]) - - for _ in range(100): - rnd.shuffle(a) - - # Force Garbage Collection - should not segfault. - gc.collect() - - -def test_shuffle_of_array_of_objects(): - # Test that permuting an array of objects will not cause - # a segfault on garbage collection. - # See gh-7719 - rnd.seed(1234, brng='MT19937') - a = np.array([np.arange(4), np.arange(4)]) - - for _ in range(1000): - rnd.shuffle(a) - - # Force Garbage Collection - should not segfault. - gc.collect() - - -def test_non_central_chi_squared_df_one(): - a = rnd.noncentral_chisquare(df = 1.0, nonc=2.3, size=10**4) - assert(a.min() > 0.0) diff --git a/setup.py b/setup.py deleted file mode 100644 index 083b211..0000000 --- a/setup.py +++ /dev/null @@ -1,160 +0,0 @@ -#!/usr/bin/env python -# Copyright (c) 2017-2022, Intel Corporation -# -# Redistribution and use in source and binary forms, with or without -# modification, are permitted provided that the following conditions are met: -# -# * Redistributions of source code must retain the above copyright notice, -# this list of conditions and the following disclaimer. -# * Redistributions in binary form must reproduce the above copyright -# notice, this list of conditions and the following disclaimer in the -# documentation and/or other materials provided with the distribution. -# * Neither the name of Intel Corporation nor the names of its contributors -# may be used to endorse or promote products derived from this software -# without specific prior written permission. -# -# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE -# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -import os -import sys -import io -import re -from os.path import join -import Cython.Build -from setuptools import setup, Extension -import numpy as np - - -with io.open('mkl_random/_version.py', 'rt', encoding='utf8') as f: - version = re.search(r'__version__ = \'(.*?)\'', f.read()).group(1) - -with open("README.md", "r", encoding="utf-8") as file: - long_description = file.read() - -VERSION = version - -CLASSIFIERS = CLASSIFIERS = """\ -Development Status :: 5 - Production/Stable -Intended Audience :: Science/Research -Intended Audience :: Developers -License :: OSI Approved -Programming Language :: C -Programming Language :: Python -Programming Language :: Python :: 3 -Programming Language :: Python :: 3.7 -Programming Language :: Python :: 3.8 -Programming Language :: Python :: 3.9 -Programming Language :: Python :: 3.10 -Programming Language :: Python :: Implementation :: CPython -Topic :: Software Development -Topic :: Scientific/Engineering -Operating System :: Microsoft :: Windows -Operating System :: POSIX -Operating System :: Unix -Operating System :: MacOS -""" - - -def extensions(): - mkl_root = os.environ.get('MKLROOT', None) - if mkl_root: - mkl_info = { - 'include_dirs': [join(mkl_root, 'include')], - 'library_dirs': [join(mkl_root, 'lib'), join(mkl_root, 'lib', 'intel64')], - 'libraries': ['mkl_rt'] - } - else: - try: - mkl_info = get_info('mkl') - except: - mkl_info = dict() - - mkl_include_dirs = mkl_info.get('include_dirs', []) - mkl_library_dirs = mkl_info.get('library_dirs', []) - mkl_libraries = mkl_info.get('libraries', ['mkl_rt']) - - libs = mkl_libraries - lib_dirs = mkl_library_dirs - - if sys.platform == 'win32': - libs.append('Advapi32') - - Q = '/Q' if sys.platform.startswith('win') or sys.platform == 'cygwin' else '-' - eca = [Q + "std=c++11"] - if sys.platform == "linux": - eca.extend(["-Wno-unused-but-set-variable", "-Wno-unused-function"]) - - defs = [('_FILE_OFFSET_BITS', '64'), - ('_LARGEFILE_SOURCE', '1'), - ('_LARGEFILE64_SOURCE', '1')] - - exts = [ - Extension( - "mkl_random.mklrand", - [ - os.path.join("mkl_random", "mklrand.pyx"), - os.path.join("mkl_random", "src", "mkl_distributions.cpp"), - os.path.join("mkl_random", "src", "randomkit.cpp"), - ], - depends = [ - os.path.join("mkl_random", "src", "mkl_distributions.hpp"), - os.path.join("mkl_random", "src", "randomkit.h"), - os.path.join("mkl_random", "src", "numpy.pxd") - ], - include_dirs = [os.path.join("mkl_random", "src"), np.get_include()] + mkl_include_dirs, - libraries = libs, - library_dirs = lib_dirs, - extra_compile_args = eca + [ - # "-ggdb", "-O0", "-Wall", "-Wextra", - ], - define_macros=defs + [("NDEBUG",None),], # [("DEBUG", None),] - language="c++" - ) - ] - - return exts - - -setup( - name = "mkl_random", - maintainer = "Intel Corp.", - maintainer_email = "scripting@intel.com", - description = "NumPy-based Python interface to Intel (R) MKL Random Number Generation functionality", - version = version, - include_package_data=True, - ext_modules=extensions(), - cmdclass={'build_ext': Cython.Build.build_ext}, - zip_safe=False, - long_description = long_description, - long_description_content_type="text/markdown", - url = "http://github.com/IntelPython/mkl_random", - author = "Intel Corporation", - download_url = "http://github.com/IntelPython/mkl_random", - license = "BSD", - classifiers = [_f for _f in CLASSIFIERS.split('\n') if _f], - platforms = ["Windows", "Linux", "Mac OS-X"], - test_suite = "pytest", - python_requires = '>=3.7', - setup_requires=["Cython",], - install_requires = ["numpy >=1.16"], - packages=[ - "mkl_random", - ], - package_data={ - "mkl_random" : [ - "tests/*.*", - ] - }, - keywords=["MKL", "VSL", "true randomness", "pseudorandomness", - "Philox", "MT-19937", "SFMT-19937", "MT-2203", "ARS-5", - "R-250", "MCG-31",], -) From d31de89b579ecf89776b7948c5abdc76837cf3ba Mon Sep 17 00:00:00 2001 From: mkl_random-doc-bot Date: Fri, 23 Feb 2024 02:17:45 +0000 Subject: [PATCH 02/18] Deploy: 510ca5c4a4246cdf64b77bd5c2b06338ba842ec4 --- _modules/index.html | 250 ++ _sources/how_to.rst.txt | 4 + _sources/index.rst.txt | 73 + _sources/maintenance/index.rst.txt | 50 + _sources/reference/api.rst.txt | 7 + _sources/reference/ars5.rst.txt | 37 + _sources/reference/index.rst.txt | 39 + _sources/reference/mcg31.rst.txt | 37 + _sources/reference/mcg59.rst.txt | 37 + _sources/reference/mrg32k3a.rst.txt | 37 + _sources/reference/mt19937.rst.txt | 35 + _sources/reference/mt2203.rst.txt | 53 + _sources/reference/nondeterministic.rst.txt | 18 + _sources/reference/philox4x32x10.rst.txt | 37 + _sources/reference/r250.rst.txt | 37 + _sources/reference/sfmt19937.rst.txt | 37 + _sources/reference/wichmann_hill.rst.txt | 54 + _sources/tutorials.rst.txt | 93 + ...e.1e8bd061cd6da7fc9cf755528e8ffc24.min.css | 1 + _sphinx_design_static/design-tabs.js | 27 + _static/basic.css | 925 ++++ _static/debug.css | 69 + ...e.1e8bd061cd6da7fc9cf755528e8ffc24.min.css | 1 + _static/design-tabs.js | 27 + _static/doctools.js | 156 + _static/documentation_options.js | 13 + _static/file.png | Bin 0 -> 286 bytes _static/language_data.js | 199 + _static/minus.png | Bin 0 -> 90 bytes _static/plus.png | Bin 0 -> 90 bytes _static/pygments.css | 258 ++ _static/scripts/furo-extensions.js | 0 _static/scripts/furo.js | 3 + _static/scripts/furo.js.LICENSE.txt | 7 + _static/scripts/furo.js.map | 1 + _static/searchtools.js | 574 +++ _static/skeleton.css | 296 ++ _static/sphinx_highlight.js | 154 + _static/styles/furo-extensions.css | 2 + _static/styles/furo-extensions.css.map | 1 + _static/styles/furo.css | 2 + _static/styles/furo.css.map | 1 + genindex.html | 524 +++ how_to.html | 272 ++ index.html | 321 ++ maintenance/index.html | 307 ++ objects.inv | Bin 0 -> 936 bytes reference/api.html | 3751 +++++++++++++++++ reference/ars5.html | 307 ++ reference/index.html | 290 ++ reference/mcg31.html | 307 ++ reference/mcg59.html | 307 ++ reference/mrg32k3a.html | 307 ++ reference/mt19937.html | 305 ++ reference/mt2203.html | 319 ++ reference/nondeterministic.html | 286 ++ reference/philox4x32x10.html | 307 ++ reference/r250.html | 307 ++ reference/sfmt19937.html | 307 ++ reference/wichmann_hill.html | 320 ++ search.html | 260 ++ searchindex.js | 1 + tutorials.html | 364 ++ 63 files changed, 13121 insertions(+) create mode 100644 _modules/index.html create mode 100644 _sources/how_to.rst.txt create mode 100644 _sources/index.rst.txt create mode 100644 _sources/maintenance/index.rst.txt create mode 100644 _sources/reference/api.rst.txt create mode 100644 _sources/reference/ars5.rst.txt create mode 100644 _sources/reference/index.rst.txt create mode 100644 _sources/reference/mcg31.rst.txt create mode 100644 _sources/reference/mcg59.rst.txt create mode 100644 _sources/reference/mrg32k3a.rst.txt create mode 100644 _sources/reference/mt19937.rst.txt create mode 100644 _sources/reference/mt2203.rst.txt create mode 100644 _sources/reference/nondeterministic.rst.txt create mode 100644 _sources/reference/philox4x32x10.rst.txt create mode 100644 _sources/reference/r250.rst.txt create mode 100644 _sources/reference/sfmt19937.rst.txt create mode 100644 _sources/reference/wichmann_hill.rst.txt create mode 100644 _sources/tutorials.rst.txt create mode 100644 _sphinx_design_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css create mode 100644 _sphinx_design_static/design-tabs.js create mode 100644 _static/basic.css create mode 100644 _static/debug.css create mode 100644 _static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css create mode 100644 _static/design-tabs.js create mode 100644 _static/doctools.js create mode 100644 _static/documentation_options.js create mode 100644 _static/file.png create mode 100644 _static/language_data.js create mode 100644 _static/minus.png create mode 100644 _static/plus.png create mode 100644 _static/pygments.css create mode 100644 _static/scripts/furo-extensions.js create mode 100644 _static/scripts/furo.js create mode 100644 _static/scripts/furo.js.LICENSE.txt create mode 100644 _static/scripts/furo.js.map create mode 100644 _static/searchtools.js create mode 100644 _static/skeleton.css create mode 100644 _static/sphinx_highlight.js create mode 100644 _static/styles/furo-extensions.css create mode 100644 _static/styles/furo-extensions.css.map create mode 100644 _static/styles/furo.css create mode 100644 _static/styles/furo.css.map create mode 100644 genindex.html create mode 100644 how_to.html create mode 100644 index.html create mode 100644 maintenance/index.html create mode 100644 objects.inv create mode 100644 reference/api.html create mode 100644 reference/ars5.html create mode 100644 reference/index.html create mode 100644 reference/mcg31.html create mode 100644 reference/mcg59.html create mode 100644 reference/mrg32k3a.html create mode 100644 reference/mt19937.html create mode 100644 reference/mt2203.html create mode 100644 reference/nondeterministic.html create mode 100644 reference/philox4x32x10.html create mode 100644 reference/r250.html create mode 100644 reference/sfmt19937.html create mode 100644 reference/wichmann_hill.html create mode 100644 search.html create mode 100644 searchindex.js create mode 100644 tutorials.html diff --git a/_modules/index.html b/_modules/index.html new file mode 100644 index 0000000..0a3d6b1 --- /dev/null +++ b/_modules/index.html @@ -0,0 +1,250 @@ + + + + + + + + Overview: module code - mkl_random 1.2.5 documentation + + + + + + + + + + + + + + + + + Contents + + + + + + Menu + + + + + + + + Expand + + + + + + Light mode + + + + + + + + + + + + + + Dark mode + + + + + + + Auto light/dark mode + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+
mkl_random 1.2.5 documentation
 +
+
+
+ +
+ +
+
+ +
+
+
+ + + + + Back to top + +
+
+ +
+ +
+ +
+
+ +
+ + +
+
+
+
+ Copyright © 2017-2024, Intel Corp. +
+ Made with Sphinx and @pradyunsg's + + Furo + +
+
+ +
+
+ +
+
+ +
+
+ + + + + + \ No newline at end of file diff --git a/_sources/how_to.rst.txt b/_sources/how_to.rst.txt new file mode 100644 index 0000000..809a47f --- /dev/null +++ b/_sources/how_to.rst.txt @@ -0,0 +1,4 @@ +How-to Guides +============= + +To be written. \ No newline at end of file diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt new file mode 100644 index 0000000..33149a8 --- /dev/null +++ b/_sources/index.rst.txt @@ -0,0 +1,73 @@ +Random sampling powered by Intel(R) Math Kernel Library +======================================================= + +:mod:`mkl_random` is Python package exposing pseudo-random and non-deterministic random +number generators with continuous and discrete distribution available in +Intel(R) Math Kernel Library (MKL). + +.. grid:: 2 + :gutter: 3 + + .. grid-item-card:: Beginner Guides + + New to :mod:`mkl_random`? Check out the Tutorials. + They are a hands-on introduction for beginners. + + +++ + + .. button-ref:: tutorials + :expand: + :color: secondary + :click-parent: + + To the beginner guides + + .. grid-item-card:: User Guides + + The user guides are recipes for key tasks and common problems. + + +++ + + .. button-ref:: how_to + :expand: + :color: secondary + :click-parent: + + To the user guides + + .. grid-item-card:: Reference Guide + + The reference guide contains a detailed description of class :class:`mkl_random.RandomState` and its methods. + + +++ + + .. button-ref:: reference/index + :expand: + :color: secondary + :click-parent: + + To the reference guide + + .. grid-item-card:: Contributor Guides + + Want to add to the codebase? + The contributing guidelines will guide you through the + process of improving :mod:`mkl_random`. + + +++ + + .. button-ref:: maintenance/index + :expand: + :color: secondary + :click-parent: + + To the contributor guides + + +.. toctree:: + :hidden: + + tutorials + how_to + reference/index + maintenance/index diff --git a/_sources/maintenance/index.rst.txt b/_sources/maintenance/index.rst.txt new file mode 100644 index 0000000..2611957 --- /dev/null +++ b/_sources/maintenance/index.rst.txt @@ -0,0 +1,50 @@ +Contributing +============ + +:mod:`mkl_random` is an free and open source project. +We welcome and appreciate your contributions. + +To contribute, fork the repo https://github.com/IntelPython/mkl_random.git, +clone it: + +.. code-block:: + :caption: How to clone the repo + + git clone https://github.com//mkl_random.git + + +A working compiler is needed build :mod:`mkl_random`. +Both Gnu :code:`g++` and Intel LLVM :code:`icpx` are supported. + +Make sure to install Python packages required to build :mod:`mkl_random`: + +* :mod:`python` +* :mod:`numpy` +* :mod:`cython` +* :mod:`setuptools` + +You would also need Intel(R) MKL library and its headers. Set :code:`MKLROOT` environment +variable so that :code:`${MKLROOT}/include/mkl.h` and :code:`${MKLROOT}/lib/libmkl_rt.so` +can be found. + +.. code-block:: bash + :caption: Building mkl_random + + $ export MKLROOT= + python setup.py develop + +To run test suite, install :mod:`pytest`, and run + +.. code-block:: bash + :caption: Running mkl_random test suite + + python -m pytest mkl_random/tests + +To build documentation, install dependencies and running + +.. code-block:: bash + :caption: Building mkl_random documentation + + $ sphinx-build -M html docs/source docs/build + +Rendered documentation can be found in "docs/build/html". \ No newline at end of file diff --git a/_sources/reference/api.rst.txt b/_sources/reference/api.rst.txt new file mode 100644 index 0000000..cf2f084 --- /dev/null +++ b/_sources/reference/api.rst.txt @@ -0,0 +1,7 @@ +.. _fullapi: + +Class RandomState +================= + +.. autoclass:: mkl_random.RandomState + :members: diff --git a/_sources/reference/ars5.rst.txt b/_sources/reference/ars5.rst.txt new file mode 100644 index 0000000..0a91c02 --- /dev/null +++ b/_sources/reference/ars5.rst.txt @@ -0,0 +1,37 @@ +ARS5 brng +========= + +The ARS5 counter-based pseudorandom number generator based on AES encryption algorithm can be +initialized with either an integral seed, a list of integral seeds, or automatically. + +.. code-block:: python + :caption: Construction for ARS5 basic random number generator with scalar seed + + import mkl_random + rs = mkl_random.RandomState(1234, brng="ars5") + + # Use random state instance to generate 1000 random numbers from + # Uniform(0, 1) distribution + esample = rs.uniform(0, 1, size=1000) + +.. code-block:: python + :caption: Construction for ARS5 basic random number generator with vector seed + + import mkl_random + rs_vec = mkl_random.RandomState([1234, 567, 89, 0], brng="ars5") + + # Use random state instance to generate 1000 random numbers from + # Gamma(3, 1) distibution + gsample = rs_vec.gamma(3, 1, size=1000) + +When seed is not specified, the generator is initialized using system clock, e.g.: + +.. code-block:: python + :caption: Construction for ARS5 basic random number generator automatic seed + + import mkl_random + rs_def = mkl_random.RandomState(brng="ars5") + + # Use random state instance to generate 1000 random numbers + # from discrete uniform distribution [1, 6] + isample = rs_def.randint(1, 6 + 1, size=1000) diff --git a/_sources/reference/index.rst.txt b/_sources/reference/index.rst.txt new file mode 100644 index 0000000..c66d54b --- /dev/null +++ b/_sources/reference/index.rst.txt @@ -0,0 +1,39 @@ +:mod:`mkl_random` APIs +====================== + +The class :doc:`mkl_random.RandomState <./api>` exposes sampling from probability distributions while supporting +different streams of randomness, also known as basic random number generators. + +The basic random number generator is chosen by specifying :code:`brng` keyword argument to the constructor of :code:`mkl.RandomState` class. + +The list of supported basic random number generators is as follows (also see `oneMKL Engines `_): + +* :code:`'MT19937'` - the Mersenne Twister pseudo-random number generator (default), :doc:`example ` +* :code:`'SFMT19937'` - the SIMD-oriented Mersenne Twister pseudo-random number generator, :doc:`example ` +* :code:`'MT2203'` - the set of 6024 Mersenne Twister pseudorandom number generators, :doc:`example ` +* :code:`'R250'` - the 32-bit generalized feedback shift register pseudorandom number generator GFSR(250,103), :doc:`example ` +* :code:`'WH'` - the set of 273 Wichmann-Hill’s combined multiplicative congruential generators, :doc:`example ` +* :code:`'MCG31'` - the 31-bit multiplicative congruential pseudorandom number generator, :doc:`example ` +* :code:`'MCG59'` - the 59-bit multiplicative congruential pseudorandom number generator, :doc:`example ` +* :code:`'MRG32K3A'` - the combined multiple recursive pseudorandom number generator MRG32k3a, :doc:`example ` +* :code:`'PHILOX4X32X10'` - the Philox4x32x10 counter-based pseudorandom number generator, :doc:`example ` +* :code:`'NONDETERM'` - the generator with non-deterministic source of randomness (for example, a hardware device), :doc:`example ` +* :code:`'ARS5'` - the ARS5 counter-based pseudorandom number generator based on AES encryption algorithm, :doc:`example ` + +.. _oneMKLBRNG: https://spec.oneapi.io/versions/1.0-rev-2/elements/oneMKL/source/domains/rng/engines-basic-random-number-generators.html + +.. toctree:: + :hidden: + + api + mt19937 + sfmt19937 + r250 + mt2203 + wichmann_hill + mcg31 + mcg59 + mrg32k3a + philox4x32x10 + nondeterministic + ars5 diff --git a/_sources/reference/mcg31.rst.txt b/_sources/reference/mcg31.rst.txt new file mode 100644 index 0000000..87ee301 --- /dev/null +++ b/_sources/reference/mcg31.rst.txt @@ -0,0 +1,37 @@ +MCG31 brng +========== + +The 31-bit multiplicative congruential pseudorandom number generator MCG(1132489760, 2**31 -1) can be +initialized with either an integral seed, a list of integral seeds, or automatically. + +.. code-block:: python + :caption: Construction for MCG31 basic random number generator with scalar seed + + import mkl_random + rs = mkl_random.RandomState(1234, brng="MCG31") + + # Use random state instance to generate 1000 random numbers from + # Uniform(0, 1) distribution + esample = rs.uniform(0, 1, size=1000) + +.. code-block:: python + :caption: Construction for MCG31 basic random number generator with vector seed + + import mkl_random + rs_vec = mkl_random.RandomState([1234, 567, 89, 0], brng="MCG31") + + # Use random state instance to generate 1000 random numbers from + # Gamma(3, 1) distibution + gsample = rs_vec.gamma(3, 1, size=1000) + +When seed is not specified, the generator is initialized using system clock, e.g.: + +.. code-block:: python + :caption: Construction for MCG31 basic random number generator automatic seed + + import mkl_random + rs_def = mkl_random.RandomState(brng="MCG31") + + # Use random state instance to generate 1000 random numbers + # from discrete uniform distribution [1, 6] + isample = rs_def.randint(1, 6 + 1, size=1000) diff --git a/_sources/reference/mcg59.rst.txt b/_sources/reference/mcg59.rst.txt new file mode 100644 index 0000000..314361a --- /dev/null +++ b/_sources/reference/mcg59.rst.txt @@ -0,0 +1,37 @@ +MCG59 brng +========== + +The 59-bit multiplicative congruential pseudorandom number generator can be +initialized with either an integral seed, a list of integral seeds, or automatically. + +.. code-block:: python + :caption: Construction for MCG31 basic random number generator with scalar seed + + import mkl_random + rs = mkl_random.RandomState(1234, brng="MCG59") + + # Use random state instance to generate 1000 random numbers from + # Uniform(0, 1) distribution + esample = rs.uniform(0, 1, size=1000) + +.. code-block:: python + :caption: Construction for MCG31 basic random number generator with vector seed + + import mkl_random + rs_vec = mkl_random.RandomState([1234, 567, 89, 0], brng="MCG59") + + # Use random state instance to generate 1000 random numbers from + # Gamma(3, 1) distibution + gsample = rs_vec.gamma(3, 1, size=1000) + +When seed is not specified, the generator is initialized using system clock, e.g.: + +.. code-block:: python + :caption: Construction for MCG31 basic random number generator automatic seed + + import mkl_random + rs_def = mkl_random.RandomState(brng="MCG59") + + # Use random state instance to generate 1000 random numbers + # from discrete uniform distribution [1, 6] + isample = rs_def.randint(1, 6 + 1, size=1000) diff --git a/_sources/reference/mrg32k3a.rst.txt b/_sources/reference/mrg32k3a.rst.txt new file mode 100644 index 0000000..54c5c7e --- /dev/null +++ b/_sources/reference/mrg32k3a.rst.txt @@ -0,0 +1,37 @@ +MRG32k3a brng +============= + +The combined multiple recursive pseudorandom number generator MRG32k3a can be +initialized with either an integral seed, a list of integral seeds, or automatically. + +.. code-block:: python + :caption: Construction for MRG32k3a basic random number generator with scalar seed + + import mkl_random + rs = mkl_random.RandomState(1234, brng="MRG32k3a") + + # Use random state instance to generate 1000 random numbers from + # Uniform(0, 1) distribution + esample = rs.uniform(0, 1, size=1000) + +.. code-block:: python + :caption: Construction for MRG32k3a basic random number generator with vector seed + + import mkl_random + rs_vec = mkl_random.RandomState([1234, 567, 89, 0], brng="MRG32k3a") + + # Use random state instance to generate 1000 random numbers from + # Gamma(3, 1) distibution + gsample = rs_vec.gamma(3, 1, size=1000) + +When seed is not specified, the generator is initialized using system clock, e.g.: + +.. code-block:: python + :caption: Construction for MRG32k3a basic random number generator automatic seed + + import mkl_random + rs_def = mkl_random.RandomState(brng="MRG32k3a") + + # Use random state instance to generate 1000 random numbers + # from discrete uniform distribution [1, 6] + isample = rs_def.randint(1, 6 + 1, size=1000) diff --git a/_sources/reference/mt19937.rst.txt b/_sources/reference/mt19937.rst.txt new file mode 100644 index 0000000..6b32777 --- /dev/null +++ b/_sources/reference/mt19937.rst.txt @@ -0,0 +1,35 @@ +MT19937 brng +============ + +The Mersenne Twister random number generator can be initialized with either an integral seed, +a list of integral seeds, or automatically. + +.. code-block:: python + :caption: Construction for MT19937 basic random number generator with scalar seed + + import mkl_random + rs = mkl_random.RandomState(1234, brng="MT19937") + + # Use random state instance to generate 1000 uniform random numbers + usample = rs.uniform(0, 1, size=1000) + +.. code-block:: python + :caption: Construction for MT19937 basic random number generator with vector seed + + import mkl_random + rs_vec = mkl_random.RandomState([1234, 567, 89, 0], brng="MT19937") + + # Use random state instance to generate 1000 Gaussian random numbers + nsample = rs_vec.normal(0, 1, size=1000) + +When seed is not specified, the generator is initialized using system clock, e.g.: + +.. code-block:: python + :caption: Construction for MT19937 basic random number generator automatic seed + + import mkl_random + rs_def = mkl_random.RandomState(brng="MT19937") + + # Use random state instance to generate 1000 random numbers + # from Binomial(10, 0.4) + bsample = rs_def.binomial(10, 0.4, size=1000) diff --git a/_sources/reference/mt2203.rst.txt b/_sources/reference/mt2203.rst.txt new file mode 100644 index 0000000..6bf43a5 --- /dev/null +++ b/_sources/reference/mt2203.rst.txt @@ -0,0 +1,53 @@ +MT2203 brng +=========== + +Each generator from the set of `6024 Mersenne Twister pseudorandom number generators `_ can be +initialized with either an integral seed, a list of integral seeds, or automatically. + +An individual member of the set can be addressed by using a tuple to specify the generator +:code:`brng=("MT2203", set_id)` where :math:`0 \leq \text{set_id} < 6024`. + +.. code-block:: python + :caption: Construction for MT2203 basic random number generator with scalar seed + + import mkl_random + seed = 777 + # initialize representative generator from the set + rs0 = mkl_random.RandomState(seed, brng="MT2203") + + # initialize 0-th member of the set + rs0 = mkl_random.RandomState(seed, brng=("MT2203", 0)) + + # initialize 5-th member of the set + rs5 = mkl_random.RandomState(seed, brng=("MT2203", 5)) + + sample = rs5.uniform(0, 1, size=1_000_000) + +.. code-block:: python + :caption: Construction for MT2203 basic random number generator with vector seed + + import mkl_random + rs = mkl_random.RandomState([1234, 567, 89, 0], brng=("MT2203", 6023)) + + # Use random state instance to generate 1000 random numbers from + # Gamma(3, 1) distibution + gsample = rs_vec.gamma(3, 1, size=1000) + +When seed is not specified, the generator is initialized using system clock, e.g.: + +.. code-block:: python + :caption: Construction for MT2203 basic random number generator automatic seed + + import mkl_random + rs_def = mkl_random.RandomState(brng="MT2203") + + # Use random state instance to generate 1000 random numbers + # from discrete uniform distribution [1, 6] + isample = rs_def.randint(1, 6 + 1, size=1000) + +Different members of the set of generators initialized with the same seed are designed to generate +statistically independent streams of randomness. This property makes MT2203 generator suitable for +parallelizing stochastic algorithms. Please refer to "examples/" folder in the `GitHub repo +`_. + +.. _philoxrng: https://spec.oneapi.io/versions/1.0-rev-2/elements/oneMKL/source/domains/rng/mkl-rng-philox4x32x10.html \ No newline at end of file diff --git a/_sources/reference/nondeterministic.rst.txt b/_sources/reference/nondeterministic.rst.txt new file mode 100644 index 0000000..a3b2212 --- /dev/null +++ b/_sources/reference/nondeterministic.rst.txt @@ -0,0 +1,18 @@ +Nondeterm brng +============== + +The generator with non-deterministic source of randomness, such as a hardware device, requires no seeding. +This basic random number generator should not be used if reproducibility of stochastic simulation is required. + +.. code-block:: python + :caption: Construction for non-deterministic basic random number generator + + import mkl_random + rs = mkl_random.RandomState(brng="nondeterm") + + # Use random state instance to generate 1000 random numbers from + # Uniform(0, 1) distribution + esample = rs.uniform(0, 1, size=1000) + +Seed parameter provided to the constructor of :class:`mkl_random.RandomState`, +or :meth:`mkl_random.RandomState.seed` is ignored. \ No newline at end of file diff --git a/_sources/reference/philox4x32x10.rst.txt b/_sources/reference/philox4x32x10.rst.txt new file mode 100644 index 0000000..9eb5ae1 --- /dev/null +++ b/_sources/reference/philox4x32x10.rst.txt @@ -0,0 +1,37 @@ +Philox4x32x10 brng +================== + +The Philox 4x32x10 counter-based pseudorandom number generator can be +initialized with either an integral seed, a list of integral seeds, or automatically. + +.. code-block:: python + :caption: Construction for Philox4x32x10 basic random number generator with scalar seed + + import mkl_random + rs = mkl_random.RandomState(1234, brng="philox4x32x10") + + # Use random state instance to generate 1000 random numbers from + # Uniform(0, 1) distribution + esample = rs.uniform(0, 1, size=1000) + +.. code-block:: python + :caption: Construction for Philox4x32x10 basic random number generator with vector seed + + import mkl_random + rs_vec = mkl_random.RandomState([1234, 567, 89, 0], brng="philox4x32x10") + + # Use random state instance to generate 1000 random numbers from + # Gamma(3, 1) distibution + gsample = rs_vec.gamma(3, 1, size=1000) + +When seed is not specified, the generator is initialized using system clock, e.g.: + +.. code-block:: python + :caption: Construction for Philox4x32x10 basic random number generator automatic seed + + import mkl_random + rs_def = mkl_random.RandomState(brng="philox4x32x10") + + # Use random state instance to generate 1000 random numbers + # from discrete uniform distribution [1, 6] + isample = rs_def.randint(1, 6 + 1, size=1000) diff --git a/_sources/reference/r250.rst.txt b/_sources/reference/r250.rst.txt new file mode 100644 index 0000000..5f1c5a5 --- /dev/null +++ b/_sources/reference/r250.rst.txt @@ -0,0 +1,37 @@ +R250 brng +========= + +The 32-bit generalized feedback shift register pseudorandom number generator GFSR(250,103) can be +initialized with either an integral seed, a list of integral seeds, or automatically. + +.. code-block:: python + :caption: Construction for R250 basic random number generator with scalar seed + + import mkl_random + rs = mkl_random.RandomState(1234, brng="R250") + + # Use random state instance to generate 1000 random numbers from + # Uniform(0, 1) distribution + esample = rs.uniform(0, 1, size=1000) + +.. code-block:: python + :caption: Construction for R250 basic random number generator with vector seed + + import mkl_random + rs_vec = mkl_random.RandomState([1234, 567, 89, 0], brng="R250") + + # Use random state instance to generate 1000 random numbers from + # Gamma(3, 1) distibution + gsample = rs_vec.gamma(3, 1, size=1000) + +When seed is not specified, the generator is initialized using system clock, e.g.: + +.. code-block:: python + :caption: Construction for R250 basic random number generator automatic seed + + import mkl_random + rs_def = mkl_random.RandomState(brng="R250") + + # Use random state instance to generate 1000 random numbers + # from discrete uniform distribution [1, 6] + isample = rs_def.randint(1, 6 + 1, size=1000) diff --git a/_sources/reference/sfmt19937.rst.txt b/_sources/reference/sfmt19937.rst.txt new file mode 100644 index 0000000..db6c53f --- /dev/null +++ b/_sources/reference/sfmt19937.rst.txt @@ -0,0 +1,37 @@ +SFMT19937 brng +============== + +The SIMD-oriented Mersenne Twister random number generator can be initialized with +either an integral seed, a list of integral seeds, or automatically. + +.. code-block:: python + :caption: Construction for SFMT19937 basic random number generator with scalar seed + + import mkl_random + rs = mkl_random.RandomState(1234, brng="SFMT19937") + + # Use random state instance to generate 1000 random numbers from + # Exponential distribution + esample = rs.exponential(2.3, size=1000) + +.. code-block:: python + :caption: Construction for SFMT19937 basic random number generator with vector seed + + import mkl_random + rs_vec = mkl_random.RandomState([1234, 567, 89, 0], brng="SFMT19937") + + # Use random state instance to generate 1000 random numbers from + # Gamma distibution + gsample = rs_vec.gamma(3, 1, size=1000) + +When seed is not specified, the generator is initialized using system clock, e.g.: + +.. code-block:: python + :caption: Construction for SFMT19937 basic random number generator automatic seed + + import mkl_random + rs_def = mkl_random.RandomState(brng="SFMT19937") + + # Use random state instance to generate 1000 random numbers + # from discrete uniform distribution [1, 6] + isample = rs_def.randint(1, 6 + 1, size=1000) diff --git a/_sources/reference/wichmann_hill.rst.txt b/_sources/reference/wichmann_hill.rst.txt new file mode 100644 index 0000000..b0128dc --- /dev/null +++ b/_sources/reference/wichmann_hill.rst.txt @@ -0,0 +1,54 @@ +Wichmann-Hill brng +================== + +Each generator from the set of 273 Wichmann-Hill’s combined multiplicative congruential +`generators `_ can be initialized with either an integral seed, a list of integral seeds, +or automatically. + +An individual member of the set can be addressed by using a tuple to specify the generator as +:code:`brng=("WH", set_id)` where :math:`0 \leq \text{set_id} < 273`. + +.. code-block:: python + :caption: Construction for WH basic random number generator with scalar seed + + import mkl_random + seed = 777 + # initialize representative generator from the set + rs0 = mkl_random.RandomState(seed, brng="WH") + + # initialize 0-th member of the set + rs0 = mkl_random.RandomState(seed, brng=("WH", 0)) + + # initialize 5-th member of the set + rs5 = mkl_random.RandomState(seed, brng=("WH", 5)) + + sample = rs5.uniform(0, 1, size=1_000_000) + +.. code-block:: python + :caption: Construction for WH basic random number generator with vector seed + + import mkl_random + rs = mkl_random.RandomState([1234, 567, 89, 0], brng=("WH", 200)) + + # Use random state instance to generate 1000 random numbers from + # Gamma(3, 1) distibution + gsample = rs_vec.gamma(3, 1, size=1000) + +When seed is not specified, the generator is initialized using system clock, e.g.: + +.. code-block:: python + :caption: Construction for WH basic random number generator automatic seed + + import mkl_random + rs_def = mkl_random.RandomState(brng="WH") + + # Use random state instance to generate 1000 random numbers + # from discrete uniform distribution [1, 6] + isample = rs_def.randint(1, 6 + 1, size=1000) + +Different members of the set of generators initialized with the same seed are designed to generate +statistically independent streams of randomness. This property makes MT2203 generator suitable for +parallelizing stochastic algorithms. Please refer to "examples/" folder in the `GitHub repo +`_. + +.. _whrng: https://spec.oneapi.io/versions/1.0-rev-2/elements/oneMKL/source/domains/rng/mkl-rng-wichmann_hill.html \ No newline at end of file diff --git a/_sources/tutorials.rst.txt b/_sources/tutorials.rst.txt new file mode 100644 index 0000000..faeb59a --- /dev/null +++ b/_sources/tutorials.rst.txt @@ -0,0 +1,93 @@ +Installation +============ + +Package :mod:`mkl_random` is available in conda ecosystem on "conda-forge", default, and "intel" channels. + +.. code-block:: bash + :caption: Install mkl_random from conda-forge channel + + $ conda install -c conda-forge mkl_random + +.. code-block:: bash + :caption: Install mkl_random from intel channel + + $ conda install -c intel mkl_random + +.. code-block:: bash + :caption: Install mkl_random from default + + $ conda install mkl_random + +The package can also be installed via :code:`pip`, either from PyPI, or from + +.. code-block:: bash + :caption: Install mkl_random using pip from intel channel on Anaconda + + $ pip install -i https://pypi.anaconda.org/intel/simple mkl_random + +.. code-block:: bash + :caption: Install mkl_random using pip from PyPI + + $ pip install mkl_random + +The :mod:`mkl_random` is also distributed as part of `Intel(R) Distribution for Python* `_. + +Beginner's guide +================ + +The :mod:`mkl_random` package was designed following :class:`numpy.random.RandomState` class to +make use of :mod:`mkl_random` easy for current uses of :mod:`numpy.random` module. + +.. note:: + Since the first release of `mkl_random`, NumPy introduced new classes :class:`numpy.random.Generator` and + :class:`numpy.random.BitGenerator`, while also retaining :class:`numpy.random.RandomState` for backwards + compatibility. + +The state of pseudo-random number generator is stored in :class:`mkl_random.RandomState` class, +so using :mod:`mkl_random` begins with creating an instance of this class: + +.. code-block:: python + :caption: Construct random number generator + + import mkl_random + rs = mkl_random.RandomState(seed=1234) + +Sampling from difference probability distribution is done by calling class methods on the constructed instance: + +.. code-block:: python + :caption: Generate one million variates from standard continuous uniform distribution + + s = rs.uniform(0, 1, size=1_000_000) + +Drawing samples updates the state of pseudo-random number generator so that next sample is statistically +independent from the previous one (with caveats of using pseudo-random generators implied). + +Here is an example of estimating value of :math:`\pi` by using Monte-Carlo method: + +.. code-block:: python + :caption: Using Monte-Carlo method to estimate value of pi + + import numpy as np + import mkl_random + + rs = mkl_random.RandomState(seed=1234) + + n = 10**8 + batch_size = 10**6 + accepted = 0 + sampled = 0 + while sampled < n: + sampled += batch_size + x = rs.uniform(0, 1, size=batch_size) + y = rs.uniform(0, 1, size=batch_size) + accepted += np.sum(x*x + y*y < 1.0) + + print("Pi estimate: ", 4. * (accepted / n)) + +Sample output of running such an example: + +.. code-block:: bash + :caption: Sample output after executing above script + + $ python pi.py + Pi estimate: 3.14167732 \ No newline at end of file diff --git a/_sphinx_design_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css b/_sphinx_design_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css new file mode 100644 index 0000000..eb19f69 --- /dev/null +++ b/_sphinx_design_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css @@ -0,0 +1 @@ +.sd-bg-primary{background-color:var(--sd-color-primary) !important}.sd-bg-text-primary{color:var(--sd-color-primary-text) !important}button.sd-bg-primary:focus,button.sd-bg-primary:hover{background-color:var(--sd-color-primary-highlight) !important}a.sd-bg-primary:focus,a.sd-bg-primary:hover{background-color:var(--sd-color-primary-highlight) !important}.sd-bg-secondary{background-color:var(--sd-color-secondary) !important}.sd-bg-text-secondary{color:var(--sd-color-secondary-text) !important}button.sd-bg-secondary:focus,button.sd-bg-secondary:hover{background-color:var(--sd-color-secondary-highlight) !important}a.sd-bg-secondary:focus,a.sd-bg-secondary:hover{background-color:var(--sd-color-secondary-highlight) !important}.sd-bg-success{background-color:var(--sd-color-success) !important}.sd-bg-text-success{color:var(--sd-color-success-text) !important}button.sd-bg-success:focus,button.sd-bg-success:hover{background-color:var(--sd-color-success-highlight) !important}a.sd-bg-success:focus,a.sd-bg-success:hover{background-color:var(--sd-color-success-highlight) !important}.sd-bg-info{background-color:var(--sd-color-info) !important}.sd-bg-text-info{color:var(--sd-color-info-text) !important}button.sd-bg-info:focus,button.sd-bg-info:hover{background-color:var(--sd-color-info-highlight) !important}a.sd-bg-info:focus,a.sd-bg-info:hover{background-color:var(--sd-color-info-highlight) !important}.sd-bg-warning{background-color:var(--sd-color-warning) !important}.sd-bg-text-warning{color:var(--sd-color-warning-text) !important}button.sd-bg-warning:focus,button.sd-bg-warning:hover{background-color:var(--sd-color-warning-highlight) !important}a.sd-bg-warning:focus,a.sd-bg-warning:hover{background-color:var(--sd-color-warning-highlight) !important}.sd-bg-danger{background-color:var(--sd-color-danger) !important}.sd-bg-text-danger{color:var(--sd-color-danger-text) !important}button.sd-bg-danger:focus,button.sd-bg-danger:hover{background-color:var(--sd-color-danger-highlight) !important}a.sd-bg-danger:focus,a.sd-bg-danger:hover{background-color:var(--sd-color-danger-highlight) !important}.sd-bg-light{background-color:var(--sd-color-light) !important}.sd-bg-text-light{color:var(--sd-color-light-text) !important}button.sd-bg-light:focus,button.sd-bg-light:hover{background-color:var(--sd-color-light-highlight) !important}a.sd-bg-light:focus,a.sd-bg-light:hover{background-color:var(--sd-color-light-highlight) !important}.sd-bg-muted{background-color:var(--sd-color-muted) !important}.sd-bg-text-muted{color:var(--sd-color-muted-text) !important}button.sd-bg-muted:focus,button.sd-bg-muted:hover{background-color:var(--sd-color-muted-highlight) !important}a.sd-bg-muted:focus,a.sd-bg-muted:hover{background-color:var(--sd-color-muted-highlight) !important}.sd-bg-dark{background-color:var(--sd-color-dark) !important}.sd-bg-text-dark{color:var(--sd-color-dark-text) !important}button.sd-bg-dark:focus,button.sd-bg-dark:hover{background-color:var(--sd-color-dark-highlight) !important}a.sd-bg-dark:focus,a.sd-bg-dark:hover{background-color:var(--sd-color-dark-highlight) !important}.sd-bg-black{background-color:var(--sd-color-black) !important}.sd-bg-text-black{color:var(--sd-color-black-text) !important}button.sd-bg-black:focus,button.sd-bg-black:hover{background-color:var(--sd-color-black-highlight) !important}a.sd-bg-black:focus,a.sd-bg-black:hover{background-color:var(--sd-color-black-highlight) !important}.sd-bg-white{background-color:var(--sd-color-white) !important}.sd-bg-text-white{color:var(--sd-color-white-text) !important}button.sd-bg-white:focus,button.sd-bg-white:hover{background-color:var(--sd-color-white-highlight) !important}a.sd-bg-white:focus,a.sd-bg-white:hover{background-color:var(--sd-color-white-highlight) !important}.sd-text-primary,.sd-text-primary>p{color:var(--sd-color-primary) !important}a.sd-text-primary:focus,a.sd-text-primary:hover{color:var(--sd-color-primary-highlight) !important}.sd-text-secondary,.sd-text-secondary>p{color:var(--sd-color-secondary) !important}a.sd-text-secondary:focus,a.sd-text-secondary:hover{color:var(--sd-color-secondary-highlight) !important}.sd-text-success,.sd-text-success>p{color:var(--sd-color-success) !important}a.sd-text-success:focus,a.sd-text-success:hover{color:var(--sd-color-success-highlight) !important}.sd-text-info,.sd-text-info>p{color:var(--sd-color-info) !important}a.sd-text-info:focus,a.sd-text-info:hover{color:var(--sd-color-info-highlight) !important}.sd-text-warning,.sd-text-warning>p{color:var(--sd-color-warning) !important}a.sd-text-warning:focus,a.sd-text-warning:hover{color:var(--sd-color-warning-highlight) !important}.sd-text-danger,.sd-text-danger>p{color:var(--sd-color-danger) !important}a.sd-text-danger:focus,a.sd-text-danger:hover{color:var(--sd-color-danger-highlight) !important}.sd-text-light,.sd-text-light>p{color:var(--sd-color-light) !important}a.sd-text-light:focus,a.sd-text-light:hover{color:var(--sd-color-light-highlight) !important}.sd-text-muted,.sd-text-muted>p{color:var(--sd-color-muted) !important}a.sd-text-muted:focus,a.sd-text-muted:hover{color:var(--sd-color-muted-highlight) !important}.sd-text-dark,.sd-text-dark>p{color:var(--sd-color-dark) !important}a.sd-text-dark:focus,a.sd-text-dark:hover{color:var(--sd-color-dark-highlight) !important}.sd-text-black,.sd-text-black>p{color:var(--sd-color-black) !important}a.sd-text-black:focus,a.sd-text-black:hover{color:var(--sd-color-black-highlight) !important}.sd-text-white,.sd-text-white>p{color:var(--sd-color-white) !important}a.sd-text-white:focus,a.sd-text-white:hover{color:var(--sd-color-white-highlight) !important}.sd-outline-primary{border-color:var(--sd-color-primary) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-primary:focus,a.sd-outline-primary:hover{border-color:var(--sd-color-primary-highlight) !important}.sd-outline-secondary{border-color:var(--sd-color-secondary) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-secondary:focus,a.sd-outline-secondary:hover{border-color:var(--sd-color-secondary-highlight) !important}.sd-outline-success{border-color:var(--sd-color-success) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-success:focus,a.sd-outline-success:hover{border-color:var(--sd-color-success-highlight) !important}.sd-outline-info{border-color:var(--sd-color-info) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-info:focus,a.sd-outline-info:hover{border-color:var(--sd-color-info-highlight) !important}.sd-outline-warning{border-color:var(--sd-color-warning) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-warning:focus,a.sd-outline-warning:hover{border-color:var(--sd-color-warning-highlight) !important}.sd-outline-danger{border-color:var(--sd-color-danger) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-danger:focus,a.sd-outline-danger:hover{border-color:var(--sd-color-danger-highlight) !important}.sd-outline-light{border-color:var(--sd-color-light) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-light:focus,a.sd-outline-light:hover{border-color:var(--sd-color-light-highlight) !important}.sd-outline-muted{border-color:var(--sd-color-muted) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-muted:focus,a.sd-outline-muted:hover{border-color:var(--sd-color-muted-highlight) !important}.sd-outline-dark{border-color:var(--sd-color-dark) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-dark:focus,a.sd-outline-dark:hover{border-color:var(--sd-color-dark-highlight) !important}.sd-outline-black{border-color:var(--sd-color-black) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-black:focus,a.sd-outline-black:hover{border-color:var(--sd-color-black-highlight) !important}.sd-outline-white{border-color:var(--sd-color-white) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-white:focus,a.sd-outline-white:hover{border-color:var(--sd-color-white-highlight) !important}.sd-bg-transparent{background-color:transparent !important}.sd-outline-transparent{border-color:transparent !important}.sd-text-transparent{color:transparent !important}.sd-p-0{padding:0 !important}.sd-pt-0,.sd-py-0{padding-top:0 !important}.sd-pr-0,.sd-px-0{padding-right:0 !important}.sd-pb-0,.sd-py-0{padding-bottom:0 !important}.sd-pl-0,.sd-px-0{padding-left:0 !important}.sd-p-1{padding:.25rem !important}.sd-pt-1,.sd-py-1{padding-top:.25rem !important}.sd-pr-1,.sd-px-1{padding-right:.25rem !important}.sd-pb-1,.sd-py-1{padding-bottom:.25rem !important}.sd-pl-1,.sd-px-1{padding-left:.25rem !important}.sd-p-2{padding:.5rem !important}.sd-pt-2,.sd-py-2{padding-top:.5rem !important}.sd-pr-2,.sd-px-2{padding-right:.5rem !important}.sd-pb-2,.sd-py-2{padding-bottom:.5rem !important}.sd-pl-2,.sd-px-2{padding-left:.5rem !important}.sd-p-3{padding:1rem !important}.sd-pt-3,.sd-py-3{padding-top:1rem !important}.sd-pr-3,.sd-px-3{padding-right:1rem !important}.sd-pb-3,.sd-py-3{padding-bottom:1rem !important}.sd-pl-3,.sd-px-3{padding-left:1rem !important}.sd-p-4{padding:1.5rem !important}.sd-pt-4,.sd-py-4{padding-top:1.5rem !important}.sd-pr-4,.sd-px-4{padding-right:1.5rem !important}.sd-pb-4,.sd-py-4{padding-bottom:1.5rem !important}.sd-pl-4,.sd-px-4{padding-left:1.5rem !important}.sd-p-5{padding:3rem !important}.sd-pt-5,.sd-py-5{padding-top:3rem !important}.sd-pr-5,.sd-px-5{padding-right:3rem !important}.sd-pb-5,.sd-py-5{padding-bottom:3rem !important}.sd-pl-5,.sd-px-5{padding-left:3rem !important}.sd-m-auto{margin:auto !important}.sd-mt-auto,.sd-my-auto{margin-top:auto !important}.sd-mr-auto,.sd-mx-auto{margin-right:auto !important}.sd-mb-auto,.sd-my-auto{margin-bottom:auto !important}.sd-ml-auto,.sd-mx-auto{margin-left:auto !important}.sd-m-0{margin:0 !important}.sd-mt-0,.sd-my-0{margin-top:0 !important}.sd-mr-0,.sd-mx-0{margin-right:0 !important}.sd-mb-0,.sd-my-0{margin-bottom:0 !important}.sd-ml-0,.sd-mx-0{margin-left:0 !important}.sd-m-1{margin:.25rem !important}.sd-mt-1,.sd-my-1{margin-top:.25rem !important}.sd-mr-1,.sd-mx-1{margin-right:.25rem !important}.sd-mb-1,.sd-my-1{margin-bottom:.25rem !important}.sd-ml-1,.sd-mx-1{margin-left:.25rem !important}.sd-m-2{margin:.5rem !important}.sd-mt-2,.sd-my-2{margin-top:.5rem !important}.sd-mr-2,.sd-mx-2{margin-right:.5rem !important}.sd-mb-2,.sd-my-2{margin-bottom:.5rem !important}.sd-ml-2,.sd-mx-2{margin-left:.5rem !important}.sd-m-3{margin:1rem !important}.sd-mt-3,.sd-my-3{margin-top:1rem !important}.sd-mr-3,.sd-mx-3{margin-right:1rem !important}.sd-mb-3,.sd-my-3{margin-bottom:1rem !important}.sd-ml-3,.sd-mx-3{margin-left:1rem !important}.sd-m-4{margin:1.5rem !important}.sd-mt-4,.sd-my-4{margin-top:1.5rem !important}.sd-mr-4,.sd-mx-4{margin-right:1.5rem !important}.sd-mb-4,.sd-my-4{margin-bottom:1.5rem !important}.sd-ml-4,.sd-mx-4{margin-left:1.5rem !important}.sd-m-5{margin:3rem !important}.sd-mt-5,.sd-my-5{margin-top:3rem !important}.sd-mr-5,.sd-mx-5{margin-right:3rem !important}.sd-mb-5,.sd-my-5{margin-bottom:3rem !important}.sd-ml-5,.sd-mx-5{margin-left:3rem !important}.sd-w-25{width:25% !important}.sd-w-50{width:50% !important}.sd-w-75{width:75% !important}.sd-w-100{width:100% !important}.sd-w-auto{width:auto !important}.sd-h-25{height:25% !important}.sd-h-50{height:50% !important}.sd-h-75{height:75% !important}.sd-h-100{height:100% !important}.sd-h-auto{height:auto !important}.sd-d-none{display:none !important}.sd-d-inline{display:inline !important}.sd-d-inline-block{display:inline-block !important}.sd-d-block{display:block !important}.sd-d-grid{display:grid !important}.sd-d-flex-row{display:-ms-flexbox !important;display:flex !important;flex-direction:row !important}.sd-d-flex-column{display:-ms-flexbox !important;display:flex !important;flex-direction:column !important}.sd-d-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}@media(min-width: 576px){.sd-d-sm-none{display:none !important}.sd-d-sm-inline{display:inline !important}.sd-d-sm-inline-block{display:inline-block !important}.sd-d-sm-block{display:block !important}.sd-d-sm-grid{display:grid !important}.sd-d-sm-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-sm-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}@media(min-width: 768px){.sd-d-md-none{display:none !important}.sd-d-md-inline{display:inline !important}.sd-d-md-inline-block{display:inline-block !important}.sd-d-md-block{display:block !important}.sd-d-md-grid{display:grid !important}.sd-d-md-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-md-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}@media(min-width: 992px){.sd-d-lg-none{display:none !important}.sd-d-lg-inline{display:inline !important}.sd-d-lg-inline-block{display:inline-block !important}.sd-d-lg-block{display:block !important}.sd-d-lg-grid{display:grid !important}.sd-d-lg-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-lg-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}@media(min-width: 1200px){.sd-d-xl-none{display:none !important}.sd-d-xl-inline{display:inline !important}.sd-d-xl-inline-block{display:inline-block !important}.sd-d-xl-block{display:block !important}.sd-d-xl-grid{display:grid !important}.sd-d-xl-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-xl-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}.sd-align-major-start{justify-content:flex-start !important}.sd-align-major-end{justify-content:flex-end !important}.sd-align-major-center{justify-content:center !important}.sd-align-major-justify{justify-content:space-between !important}.sd-align-major-spaced{justify-content:space-evenly !important}.sd-align-minor-start{align-items:flex-start !important}.sd-align-minor-end{align-items:flex-end !important}.sd-align-minor-center{align-items:center !important}.sd-align-minor-stretch{align-items:stretch !important}.sd-text-justify{text-align:justify !important}.sd-text-left{text-align:left !important}.sd-text-right{text-align:right !important}.sd-text-center{text-align:center !important}.sd-font-weight-light{font-weight:300 !important}.sd-font-weight-lighter{font-weight:lighter !important}.sd-font-weight-normal{font-weight:400 !important}.sd-font-weight-bold{font-weight:700 !important}.sd-font-weight-bolder{font-weight:bolder !important}.sd-font-italic{font-style:italic !important}.sd-text-decoration-none{text-decoration:none !important}.sd-text-lowercase{text-transform:lowercase !important}.sd-text-uppercase{text-transform:uppercase !important}.sd-text-capitalize{text-transform:capitalize !important}.sd-text-wrap{white-space:normal !important}.sd-text-nowrap{white-space:nowrap !important}.sd-text-truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.sd-fs-1,.sd-fs-1>p{font-size:calc(1.375rem + 1.5vw) !important;line-height:unset !important}.sd-fs-2,.sd-fs-2>p{font-size:calc(1.325rem + 0.9vw) !important;line-height:unset !important}.sd-fs-3,.sd-fs-3>p{font-size:calc(1.3rem + 0.6vw) !important;line-height:unset !important}.sd-fs-4,.sd-fs-4>p{font-size:calc(1.275rem + 0.3vw) !important;line-height:unset !important}.sd-fs-5,.sd-fs-5>p{font-size:1.25rem !important;line-height:unset !important}.sd-fs-6,.sd-fs-6>p{font-size:1rem !important;line-height:unset !important}.sd-border-0{border:0 solid !important}.sd-border-top-0{border-top:0 solid !important}.sd-border-bottom-0{border-bottom:0 solid !important}.sd-border-right-0{border-right:0 solid !important}.sd-border-left-0{border-left:0 solid !important}.sd-border-1{border:1px solid !important}.sd-border-top-1{border-top:1px solid !important}.sd-border-bottom-1{border-bottom:1px solid !important}.sd-border-right-1{border-right:1px solid !important}.sd-border-left-1{border-left:1px solid !important}.sd-border-2{border:2px solid !important}.sd-border-top-2{border-top:2px solid !important}.sd-border-bottom-2{border-bottom:2px solid !important}.sd-border-right-2{border-right:2px solid !important}.sd-border-left-2{border-left:2px solid !important}.sd-border-3{border:3px solid !important}.sd-border-top-3{border-top:3px solid !important}.sd-border-bottom-3{border-bottom:3px solid !important}.sd-border-right-3{border-right:3px solid !important}.sd-border-left-3{border-left:3px solid !important}.sd-border-4{border:4px solid !important}.sd-border-top-4{border-top:4px solid !important}.sd-border-bottom-4{border-bottom:4px solid !important}.sd-border-right-4{border-right:4px solid !important}.sd-border-left-4{border-left:4px solid !important}.sd-border-5{border:5px solid !important}.sd-border-top-5{border-top:5px solid !important}.sd-border-bottom-5{border-bottom:5px solid !important}.sd-border-right-5{border-right:5px solid !important}.sd-border-left-5{border-left:5px solid !important}.sd-rounded-0{border-radius:0 !important}.sd-rounded-1{border-radius:.2rem !important}.sd-rounded-2{border-radius:.3rem !important}.sd-rounded-3{border-radius:.5rem !important}.sd-rounded-pill{border-radius:50rem !important}.sd-rounded-circle{border-radius:50% !important}.shadow-none{box-shadow:none !important}.sd-shadow-sm{box-shadow:0 .125rem .25rem var(--sd-color-shadow) !important}.sd-shadow-md{box-shadow:0 .5rem 1rem var(--sd-color-shadow) !important}.sd-shadow-lg{box-shadow:0 1rem 3rem var(--sd-color-shadow) !important}@keyframes sd-slide-from-left{0%{transform:translateX(-100%)}100%{transform:translateX(0)}}@keyframes sd-slide-from-right{0%{transform:translateX(200%)}100%{transform:translateX(0)}}@keyframes sd-grow100{0%{transform:scale(0);opacity:.5}100%{transform:scale(1);opacity:1}}@keyframes sd-grow50{0%{transform:scale(0.5);opacity:.5}100%{transform:scale(1);opacity:1}}@keyframes sd-grow50-rot20{0%{transform:scale(0.5) rotateZ(-20deg);opacity:.5}75%{transform:scale(1) rotateZ(5deg);opacity:1}95%{transform:scale(1) rotateZ(-1deg);opacity:1}100%{transform:scale(1) rotateZ(0);opacity:1}}.sd-animate-slide-from-left{animation:1s ease-out 0s 1 normal none running sd-slide-from-left}.sd-animate-slide-from-right{animation:1s ease-out 0s 1 normal none running sd-slide-from-right}.sd-animate-grow100{animation:1s ease-out 0s 1 normal none running sd-grow100}.sd-animate-grow50{animation:1s ease-out 0s 1 normal none running sd-grow50}.sd-animate-grow50-rot20{animation:1s ease-out 0s 1 normal none running sd-grow50-rot20}.sd-badge{display:inline-block;padding:.35em .65em;font-size:.75em;font-weight:700;line-height:1;text-align:center;white-space:nowrap;vertical-align:baseline;border-radius:.25rem}.sd-badge:empty{display:none}a.sd-badge{text-decoration:none}.sd-btn .sd-badge{position:relative;top:-1px}.sd-btn{background-color:transparent;border:1px solid transparent;border-radius:.25rem;cursor:pointer;display:inline-block;font-weight:400;font-size:1rem;line-height:1.5;padding:.375rem .75rem;text-align:center;text-decoration:none;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out;vertical-align:middle;user-select:none;-moz-user-select:none;-ms-user-select:none;-webkit-user-select:none}.sd-btn:hover{text-decoration:none}@media(prefers-reduced-motion: reduce){.sd-btn{transition:none}}.sd-btn-primary,.sd-btn-outline-primary:hover,.sd-btn-outline-primary:focus{color:var(--sd-color-primary-text) !important;background-color:var(--sd-color-primary) !important;border-color:var(--sd-color-primary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-primary:hover,.sd-btn-primary:focus{color:var(--sd-color-primary-text) !important;background-color:var(--sd-color-primary-highlight) !important;border-color:var(--sd-color-primary-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-primary{color:var(--sd-color-primary) !important;border-color:var(--sd-color-primary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-secondary,.sd-btn-outline-secondary:hover,.sd-btn-outline-secondary:focus{color:var(--sd-color-secondary-text) !important;background-color:var(--sd-color-secondary) !important;border-color:var(--sd-color-secondary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-secondary:hover,.sd-btn-secondary:focus{color:var(--sd-color-secondary-text) !important;background-color:var(--sd-color-secondary-highlight) !important;border-color:var(--sd-color-secondary-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-secondary{color:var(--sd-color-secondary) !important;border-color:var(--sd-color-secondary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-success,.sd-btn-outline-success:hover,.sd-btn-outline-success:focus{color:var(--sd-color-success-text) !important;background-color:var(--sd-color-success) !important;border-color:var(--sd-color-success) !important;border-width:1px !important;border-style:solid !important}.sd-btn-success:hover,.sd-btn-success:focus{color:var(--sd-color-success-text) !important;background-color:var(--sd-color-success-highlight) !important;border-color:var(--sd-color-success-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-success{color:var(--sd-color-success) !important;border-color:var(--sd-color-success) !important;border-width:1px !important;border-style:solid !important}.sd-btn-info,.sd-btn-outline-info:hover,.sd-btn-outline-info:focus{color:var(--sd-color-info-text) !important;background-color:var(--sd-color-info) !important;border-color:var(--sd-color-info) !important;border-width:1px !important;border-style:solid !important}.sd-btn-info:hover,.sd-btn-info:focus{color:var(--sd-color-info-text) !important;background-color:var(--sd-color-info-highlight) !important;border-color:var(--sd-color-info-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-info{color:var(--sd-color-info) !important;border-color:var(--sd-color-info) !important;border-width:1px !important;border-style:solid !important}.sd-btn-warning,.sd-btn-outline-warning:hover,.sd-btn-outline-warning:focus{color:var(--sd-color-warning-text) !important;background-color:var(--sd-color-warning) !important;border-color:var(--sd-color-warning) !important;border-width:1px !important;border-style:solid !important}.sd-btn-warning:hover,.sd-btn-warning:focus{color:var(--sd-color-warning-text) !important;background-color:var(--sd-color-warning-highlight) !important;border-color:var(--sd-color-warning-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-warning{color:var(--sd-color-warning) !important;border-color:var(--sd-color-warning) !important;border-width:1px !important;border-style:solid !important}.sd-btn-danger,.sd-btn-outline-danger:hover,.sd-btn-outline-danger:focus{color:var(--sd-color-danger-text) !important;background-color:var(--sd-color-danger) !important;border-color:var(--sd-color-danger) !important;border-width:1px !important;border-style:solid !important}.sd-btn-danger:hover,.sd-btn-danger:focus{color:var(--sd-color-danger-text) !important;background-color:var(--sd-color-danger-highlight) !important;border-color:var(--sd-color-danger-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-danger{color:var(--sd-color-danger) !important;border-color:var(--sd-color-danger) !important;border-width:1px !important;border-style:solid !important}.sd-btn-light,.sd-btn-outline-light:hover,.sd-btn-outline-light:focus{color:var(--sd-color-light-text) !important;background-color:var(--sd-color-light) !important;border-color:var(--sd-color-light) !important;border-width:1px !important;border-style:solid !important}.sd-btn-light:hover,.sd-btn-light:focus{color:var(--sd-color-light-text) !important;background-color:var(--sd-color-light-highlight) !important;border-color:var(--sd-color-light-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-light{color:var(--sd-color-light) !important;border-color:var(--sd-color-light) !important;border-width:1px !important;border-style:solid !important}.sd-btn-muted,.sd-btn-outline-muted:hover,.sd-btn-outline-muted:focus{color:var(--sd-color-muted-text) !important;background-color:var(--sd-color-muted) !important;border-color:var(--sd-color-muted) !important;border-width:1px !important;border-style:solid !important}.sd-btn-muted:hover,.sd-btn-muted:focus{color:var(--sd-color-muted-text) !important;background-color:var(--sd-color-muted-highlight) !important;border-color:var(--sd-color-muted-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-muted{color:var(--sd-color-muted) !important;border-color:var(--sd-color-muted) !important;border-width:1px !important;border-style:solid !important}.sd-btn-dark,.sd-btn-outline-dark:hover,.sd-btn-outline-dark:focus{color:var(--sd-color-dark-text) !important;background-color:var(--sd-color-dark) !important;border-color:var(--sd-color-dark) !important;border-width:1px !important;border-style:solid !important}.sd-btn-dark:hover,.sd-btn-dark:focus{color:var(--sd-color-dark-text) !important;background-color:var(--sd-color-dark-highlight) !important;border-color:var(--sd-color-dark-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-dark{color:var(--sd-color-dark) !important;border-color:var(--sd-color-dark) !important;border-width:1px !important;border-style:solid !important}.sd-btn-black,.sd-btn-outline-black:hover,.sd-btn-outline-black:focus{color:var(--sd-color-black-text) !important;background-color:var(--sd-color-black) !important;border-color:var(--sd-color-black) !important;border-width:1px !important;border-style:solid !important}.sd-btn-black:hover,.sd-btn-black:focus{color:var(--sd-color-black-text) !important;background-color:var(--sd-color-black-highlight) !important;border-color:var(--sd-color-black-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-black{color:var(--sd-color-black) !important;border-color:var(--sd-color-black) !important;border-width:1px !important;border-style:solid !important}.sd-btn-white,.sd-btn-outline-white:hover,.sd-btn-outline-white:focus{color:var(--sd-color-white-text) !important;background-color:var(--sd-color-white) !important;border-color:var(--sd-color-white) !important;border-width:1px !important;border-style:solid !important}.sd-btn-white:hover,.sd-btn-white:focus{color:var(--sd-color-white-text) !important;background-color:var(--sd-color-white-highlight) !important;border-color:var(--sd-color-white-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-white{color:var(--sd-color-white) !important;border-color:var(--sd-color-white) !important;border-width:1px !important;border-style:solid !important}.sd-stretched-link::after{position:absolute;top:0;right:0;bottom:0;left:0;z-index:1;content:""}.sd-hide-link-text{font-size:0}.sd-octicon,.sd-material-icon{display:inline-block;fill:currentColor;vertical-align:middle}.sd-avatar-xs{border-radius:50%;object-fit:cover;object-position:center;width:1rem;height:1rem}.sd-avatar-sm{border-radius:50%;object-fit:cover;object-position:center;width:3rem;height:3rem}.sd-avatar-md{border-radius:50%;object-fit:cover;object-position:center;width:5rem;height:5rem}.sd-avatar-lg{border-radius:50%;object-fit:cover;object-position:center;width:7rem;height:7rem}.sd-avatar-xl{border-radius:50%;object-fit:cover;object-position:center;width:10rem;height:10rem}.sd-avatar-inherit{border-radius:50%;object-fit:cover;object-position:center;width:inherit;height:inherit}.sd-avatar-initial{border-radius:50%;object-fit:cover;object-position:center;width:initial;height:initial}.sd-card{background-clip:border-box;background-color:var(--sd-color-card-background);border:1px solid var(--sd-color-card-border);border-radius:.25rem;color:var(--sd-color-card-text);display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;min-width:0;position:relative;word-wrap:break-word}.sd-card>hr{margin-left:0;margin-right:0}.sd-card-hover:hover{border-color:var(--sd-color-card-border-hover);transform:scale(1.01)}.sd-card-body{-ms-flex:1 1 auto;flex:1 1 auto;padding:1rem 1rem}.sd-card-title{margin-bottom:.5rem}.sd-card-subtitle{margin-top:-0.25rem;margin-bottom:0}.sd-card-text:last-child{margin-bottom:0}.sd-card-link:hover{text-decoration:none}.sd-card-link+.card-link{margin-left:1rem}.sd-card-header{padding:.5rem 1rem;margin-bottom:0;background-color:var(--sd-color-card-header);border-bottom:1px solid var(--sd-color-card-border)}.sd-card-header:first-child{border-radius:calc(0.25rem - 1px) calc(0.25rem - 1px) 0 0}.sd-card-footer{padding:.5rem 1rem;background-color:var(--sd-color-card-footer);border-top:1px solid var(--sd-color-card-border)}.sd-card-footer:last-child{border-radius:0 0 calc(0.25rem - 1px) calc(0.25rem - 1px)}.sd-card-header-tabs{margin-right:-0.5rem;margin-bottom:-0.5rem;margin-left:-0.5rem;border-bottom:0}.sd-card-header-pills{margin-right:-0.5rem;margin-left:-0.5rem}.sd-card-img-overlay{position:absolute;top:0;right:0;bottom:0;left:0;padding:1rem;border-radius:calc(0.25rem - 1px)}.sd-card-img,.sd-card-img-bottom,.sd-card-img-top{width:100%}.sd-card-img,.sd-card-img-top{border-top-left-radius:calc(0.25rem - 1px);border-top-right-radius:calc(0.25rem - 1px)}.sd-card-img,.sd-card-img-bottom{border-bottom-left-radius:calc(0.25rem - 1px);border-bottom-right-radius:calc(0.25rem - 1px)}.sd-cards-carousel{width:100%;display:flex;flex-wrap:nowrap;-ms-flex-direction:row;flex-direction:row;overflow-x:hidden;scroll-snap-type:x mandatory}.sd-cards-carousel.sd-show-scrollbar{overflow-x:auto}.sd-cards-carousel:hover,.sd-cards-carousel:focus{overflow-x:auto}.sd-cards-carousel>.sd-card{flex-shrink:0;scroll-snap-align:start}.sd-cards-carousel>.sd-card:not(:last-child){margin-right:3px}.sd-card-cols-1>.sd-card{width:90%}.sd-card-cols-2>.sd-card{width:45%}.sd-card-cols-3>.sd-card{width:30%}.sd-card-cols-4>.sd-card{width:22.5%}.sd-card-cols-5>.sd-card{width:18%}.sd-card-cols-6>.sd-card{width:15%}.sd-card-cols-7>.sd-card{width:12.8571428571%}.sd-card-cols-8>.sd-card{width:11.25%}.sd-card-cols-9>.sd-card{width:10%}.sd-card-cols-10>.sd-card{width:9%}.sd-card-cols-11>.sd-card{width:8.1818181818%}.sd-card-cols-12>.sd-card{width:7.5%}.sd-container,.sd-container-fluid,.sd-container-lg,.sd-container-md,.sd-container-sm,.sd-container-xl{margin-left:auto;margin-right:auto;padding-left:var(--sd-gutter-x, 0.75rem);padding-right:var(--sd-gutter-x, 0.75rem);width:100%}@media(min-width: 576px){.sd-container-sm,.sd-container{max-width:540px}}@media(min-width: 768px){.sd-container-md,.sd-container-sm,.sd-container{max-width:720px}}@media(min-width: 992px){.sd-container-lg,.sd-container-md,.sd-container-sm,.sd-container{max-width:960px}}@media(min-width: 1200px){.sd-container-xl,.sd-container-lg,.sd-container-md,.sd-container-sm,.sd-container{max-width:1140px}}.sd-row{--sd-gutter-x: 1.5rem;--sd-gutter-y: 0;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;margin-top:calc(var(--sd-gutter-y) * -1);margin-right:calc(var(--sd-gutter-x) * -0.5);margin-left:calc(var(--sd-gutter-x) * -0.5)}.sd-row>*{box-sizing:border-box;flex-shrink:0;width:100%;max-width:100%;padding-right:calc(var(--sd-gutter-x) * 0.5);padding-left:calc(var(--sd-gutter-x) * 0.5);margin-top:var(--sd-gutter-y)}.sd-col{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-auto>*{flex:0 0 auto;width:auto}.sd-row-cols-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}@media(min-width: 576px){.sd-col-sm{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-sm-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-sm-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-sm-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-sm-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-sm-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-sm-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-sm-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-sm-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-sm-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-sm-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-sm-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-sm-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-sm-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}@media(min-width: 768px){.sd-col-md{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-md-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-md-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-md-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-md-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-md-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-md-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-md-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-md-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-md-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-md-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-md-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-md-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-md-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}@media(min-width: 992px){.sd-col-lg{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-lg-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-lg-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-lg-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-lg-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-lg-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-lg-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-lg-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-lg-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-lg-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-lg-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-lg-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-lg-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-lg-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}@media(min-width: 1200px){.sd-col-xl{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-xl-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-xl-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-xl-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-xl-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-xl-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-xl-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-xl-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-xl-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-xl-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-xl-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-xl-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-xl-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-xl-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}.sd-col-auto{flex:0 0 auto;-ms-flex:0 0 auto;width:auto}.sd-col-1{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}.sd-col-2{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-col-3{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-col-4{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-col-5{flex:0 0 auto;-ms-flex:0 0 auto;width:41.6666666667%}.sd-col-6{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-col-7{flex:0 0 auto;-ms-flex:0 0 auto;width:58.3333333333%}.sd-col-8{flex:0 0 auto;-ms-flex:0 0 auto;width:66.6666666667%}.sd-col-9{flex:0 0 auto;-ms-flex:0 0 auto;width:75%}.sd-col-10{flex:0 0 auto;-ms-flex:0 0 auto;width:83.3333333333%}.sd-col-11{flex:0 0 auto;-ms-flex:0 0 auto;width:91.6666666667%}.sd-col-12{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-g-0,.sd-gy-0{--sd-gutter-y: 0}.sd-g-0,.sd-gx-0{--sd-gutter-x: 0}.sd-g-1,.sd-gy-1{--sd-gutter-y: 0.25rem}.sd-g-1,.sd-gx-1{--sd-gutter-x: 0.25rem}.sd-g-2,.sd-gy-2{--sd-gutter-y: 0.5rem}.sd-g-2,.sd-gx-2{--sd-gutter-x: 0.5rem}.sd-g-3,.sd-gy-3{--sd-gutter-y: 1rem}.sd-g-3,.sd-gx-3{--sd-gutter-x: 1rem}.sd-g-4,.sd-gy-4{--sd-gutter-y: 1.5rem}.sd-g-4,.sd-gx-4{--sd-gutter-x: 1.5rem}.sd-g-5,.sd-gy-5{--sd-gutter-y: 3rem}.sd-g-5,.sd-gx-5{--sd-gutter-x: 3rem}@media(min-width: 576px){.sd-col-sm-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-sm-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-sm-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-sm-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-sm-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-sm-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-sm-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-sm-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-sm-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-sm-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-sm-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-sm-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-sm-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-sm-0,.sd-gy-sm-0{--sd-gutter-y: 0}.sd-g-sm-0,.sd-gx-sm-0{--sd-gutter-x: 0}.sd-g-sm-1,.sd-gy-sm-1{--sd-gutter-y: 0.25rem}.sd-g-sm-1,.sd-gx-sm-1{--sd-gutter-x: 0.25rem}.sd-g-sm-2,.sd-gy-sm-2{--sd-gutter-y: 0.5rem}.sd-g-sm-2,.sd-gx-sm-2{--sd-gutter-x: 0.5rem}.sd-g-sm-3,.sd-gy-sm-3{--sd-gutter-y: 1rem}.sd-g-sm-3,.sd-gx-sm-3{--sd-gutter-x: 1rem}.sd-g-sm-4,.sd-gy-sm-4{--sd-gutter-y: 1.5rem}.sd-g-sm-4,.sd-gx-sm-4{--sd-gutter-x: 1.5rem}.sd-g-sm-5,.sd-gy-sm-5{--sd-gutter-y: 3rem}.sd-g-sm-5,.sd-gx-sm-5{--sd-gutter-x: 3rem}}@media(min-width: 768px){.sd-col-md-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-md-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-md-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-md-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-md-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-md-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-md-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-md-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-md-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-md-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-md-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-md-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-md-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-md-0,.sd-gy-md-0{--sd-gutter-y: 0}.sd-g-md-0,.sd-gx-md-0{--sd-gutter-x: 0}.sd-g-md-1,.sd-gy-md-1{--sd-gutter-y: 0.25rem}.sd-g-md-1,.sd-gx-md-1{--sd-gutter-x: 0.25rem}.sd-g-md-2,.sd-gy-md-2{--sd-gutter-y: 0.5rem}.sd-g-md-2,.sd-gx-md-2{--sd-gutter-x: 0.5rem}.sd-g-md-3,.sd-gy-md-3{--sd-gutter-y: 1rem}.sd-g-md-3,.sd-gx-md-3{--sd-gutter-x: 1rem}.sd-g-md-4,.sd-gy-md-4{--sd-gutter-y: 1.5rem}.sd-g-md-4,.sd-gx-md-4{--sd-gutter-x: 1.5rem}.sd-g-md-5,.sd-gy-md-5{--sd-gutter-y: 3rem}.sd-g-md-5,.sd-gx-md-5{--sd-gutter-x: 3rem}}@media(min-width: 992px){.sd-col-lg-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-lg-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-lg-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-lg-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-lg-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-lg-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-lg-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-lg-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-lg-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-lg-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-lg-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-lg-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-lg-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-lg-0,.sd-gy-lg-0{--sd-gutter-y: 0}.sd-g-lg-0,.sd-gx-lg-0{--sd-gutter-x: 0}.sd-g-lg-1,.sd-gy-lg-1{--sd-gutter-y: 0.25rem}.sd-g-lg-1,.sd-gx-lg-1{--sd-gutter-x: 0.25rem}.sd-g-lg-2,.sd-gy-lg-2{--sd-gutter-y: 0.5rem}.sd-g-lg-2,.sd-gx-lg-2{--sd-gutter-x: 0.5rem}.sd-g-lg-3,.sd-gy-lg-3{--sd-gutter-y: 1rem}.sd-g-lg-3,.sd-gx-lg-3{--sd-gutter-x: 1rem}.sd-g-lg-4,.sd-gy-lg-4{--sd-gutter-y: 1.5rem}.sd-g-lg-4,.sd-gx-lg-4{--sd-gutter-x: 1.5rem}.sd-g-lg-5,.sd-gy-lg-5{--sd-gutter-y: 3rem}.sd-g-lg-5,.sd-gx-lg-5{--sd-gutter-x: 3rem}}@media(min-width: 1200px){.sd-col-xl-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-xl-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-xl-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-xl-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-xl-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-xl-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-xl-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-xl-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-xl-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-xl-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-xl-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-xl-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-xl-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-xl-0,.sd-gy-xl-0{--sd-gutter-y: 0}.sd-g-xl-0,.sd-gx-xl-0{--sd-gutter-x: 0}.sd-g-xl-1,.sd-gy-xl-1{--sd-gutter-y: 0.25rem}.sd-g-xl-1,.sd-gx-xl-1{--sd-gutter-x: 0.25rem}.sd-g-xl-2,.sd-gy-xl-2{--sd-gutter-y: 0.5rem}.sd-g-xl-2,.sd-gx-xl-2{--sd-gutter-x: 0.5rem}.sd-g-xl-3,.sd-gy-xl-3{--sd-gutter-y: 1rem}.sd-g-xl-3,.sd-gx-xl-3{--sd-gutter-x: 1rem}.sd-g-xl-4,.sd-gy-xl-4{--sd-gutter-y: 1.5rem}.sd-g-xl-4,.sd-gx-xl-4{--sd-gutter-x: 1.5rem}.sd-g-xl-5,.sd-gy-xl-5{--sd-gutter-y: 3rem}.sd-g-xl-5,.sd-gx-xl-5{--sd-gutter-x: 3rem}}.sd-flex-row-reverse{flex-direction:row-reverse !important}details.sd-dropdown{position:relative}details.sd-dropdown .sd-summary-title{font-weight:700;padding-right:3em !important;-moz-user-select:none;-ms-user-select:none;-webkit-user-select:none;user-select:none}details.sd-dropdown:hover{cursor:pointer}details.sd-dropdown .sd-summary-content{cursor:default}details.sd-dropdown summary{list-style:none;padding:1em}details.sd-dropdown summary .sd-octicon.no-title{vertical-align:middle}details.sd-dropdown[open] summary .sd-octicon.no-title{visibility:hidden}details.sd-dropdown summary::-webkit-details-marker{display:none}details.sd-dropdown summary:focus{outline:none}details.sd-dropdown .sd-summary-icon{margin-right:.5em}details.sd-dropdown .sd-summary-icon svg{opacity:.8}details.sd-dropdown summary:hover .sd-summary-up svg,details.sd-dropdown summary:hover .sd-summary-down svg{opacity:1;transform:scale(1.1)}details.sd-dropdown .sd-summary-up svg,details.sd-dropdown .sd-summary-down svg{display:block;opacity:.6}details.sd-dropdown .sd-summary-up,details.sd-dropdown .sd-summary-down{pointer-events:none;position:absolute;right:1em;top:1em}details.sd-dropdown[open]>.sd-summary-title .sd-summary-down{visibility:hidden}details.sd-dropdown:not([open])>.sd-summary-title .sd-summary-up{visibility:hidden}details.sd-dropdown:not([open]).sd-card{border:none}details.sd-dropdown:not([open])>.sd-card-header{border:1px solid var(--sd-color-card-border);border-radius:.25rem}details.sd-dropdown.sd-fade-in[open] summary~*{-moz-animation:sd-fade-in .5s ease-in-out;-webkit-animation:sd-fade-in .5s ease-in-out;animation:sd-fade-in .5s ease-in-out}details.sd-dropdown.sd-fade-in-slide-down[open] summary~*{-moz-animation:sd-fade-in .5s ease-in-out,sd-slide-down .5s ease-in-out;-webkit-animation:sd-fade-in .5s ease-in-out,sd-slide-down .5s ease-in-out;animation:sd-fade-in .5s ease-in-out,sd-slide-down .5s ease-in-out}.sd-col>.sd-dropdown{width:100%}.sd-summary-content>.sd-tab-set:first-child{margin-top:0}@keyframes sd-fade-in{0%{opacity:0}100%{opacity:1}}@keyframes sd-slide-down{0%{transform:translate(0, -10px)}100%{transform:translate(0, 0)}}.sd-tab-set{border-radius:.125rem;display:flex;flex-wrap:wrap;margin:1em 0;position:relative}.sd-tab-set>input{opacity:0;position:absolute}.sd-tab-set>input:checked+label{border-color:var(--sd-color-tabs-underline-active);color:var(--sd-color-tabs-label-active)}.sd-tab-set>input:checked+label+.sd-tab-content{display:block}.sd-tab-set>input:not(:checked)+label:hover{color:var(--sd-color-tabs-label-hover);border-color:var(--sd-color-tabs-underline-hover)}.sd-tab-set>input:focus+label{outline-style:auto}.sd-tab-set>input:not(.focus-visible)+label{outline:none;-webkit-tap-highlight-color:transparent}.sd-tab-set>label{border-bottom:.125rem solid transparent;margin-bottom:0;color:var(--sd-color-tabs-label-inactive);border-color:var(--sd-color-tabs-underline-inactive);cursor:pointer;font-size:var(--sd-fontsize-tabs-label);font-weight:700;padding:1em 1.25em .5em;transition:color 250ms;width:auto;z-index:1}html .sd-tab-set>label:hover{color:var(--sd-color-tabs-label-active)}.sd-col>.sd-tab-set{width:100%}.sd-tab-content{box-shadow:0 -0.0625rem var(--sd-color-tabs-overline),0 .0625rem var(--sd-color-tabs-underline);display:none;order:99;padding-bottom:.75rem;padding-top:.75rem;width:100%}.sd-tab-content>:first-child{margin-top:0 !important}.sd-tab-content>:last-child{margin-bottom:0 !important}.sd-tab-content>.sd-tab-set{margin:0}.sd-sphinx-override,.sd-sphinx-override *{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}.sd-sphinx-override p{margin-top:0}:root{--sd-color-primary: #0071bc;--sd-color-secondary: #6c757d;--sd-color-success: #28a745;--sd-color-info: #17a2b8;--sd-color-warning: #f0b37e;--sd-color-danger: #dc3545;--sd-color-light: #f8f9fa;--sd-color-muted: #6c757d;--sd-color-dark: #212529;--sd-color-black: black;--sd-color-white: white;--sd-color-primary-highlight: #0060a0;--sd-color-secondary-highlight: #5c636a;--sd-color-success-highlight: #228e3b;--sd-color-info-highlight: #148a9c;--sd-color-warning-highlight: #cc986b;--sd-color-danger-highlight: #bb2d3b;--sd-color-light-highlight: #d3d4d5;--sd-color-muted-highlight: #5c636a;--sd-color-dark-highlight: #1c1f23;--sd-color-black-highlight: black;--sd-color-white-highlight: #d9d9d9;--sd-color-primary-text: #fff;--sd-color-secondary-text: #fff;--sd-color-success-text: #fff;--sd-color-info-text: #fff;--sd-color-warning-text: #212529;--sd-color-danger-text: #fff;--sd-color-light-text: #212529;--sd-color-muted-text: #fff;--sd-color-dark-text: #fff;--sd-color-black-text: #fff;--sd-color-white-text: #212529;--sd-color-shadow: rgba(0, 0, 0, 0.15);--sd-color-card-border: rgba(0, 0, 0, 0.125);--sd-color-card-border-hover: hsla(231, 99%, 66%, 1);--sd-color-card-background: transparent;--sd-color-card-text: inherit;--sd-color-card-header: transparent;--sd-color-card-footer: transparent;--sd-color-tabs-label-active: hsla(231, 99%, 66%, 1);--sd-color-tabs-label-hover: hsla(231, 99%, 66%, 1);--sd-color-tabs-label-inactive: hsl(0, 0%, 66%);--sd-color-tabs-underline-active: hsla(231, 99%, 66%, 1);--sd-color-tabs-underline-hover: rgba(178, 206, 245, 0.62);--sd-color-tabs-underline-inactive: transparent;--sd-color-tabs-overline: rgb(222, 222, 222);--sd-color-tabs-underline: rgb(222, 222, 222);--sd-fontsize-tabs-label: 1rem} diff --git a/_sphinx_design_static/design-tabs.js b/_sphinx_design_static/design-tabs.js new file mode 100644 index 0000000..36b38cf --- /dev/null +++ b/_sphinx_design_static/design-tabs.js @@ -0,0 +1,27 @@ +var sd_labels_by_text = {}; + +function ready() { + const li = document.getElementsByClassName("sd-tab-label"); + for (const label of li) { + syncId = label.getAttribute("data-sync-id"); + if (syncId) { + label.onclick = onLabelClick; + if (!sd_labels_by_text[syncId]) { + sd_labels_by_text[syncId] = []; + } + sd_labels_by_text[syncId].push(label); + } + } +} + +function onLabelClick() { + // Activate other inputs with the same sync id. + syncId = this.getAttribute("data-sync-id"); + for (label of sd_labels_by_text[syncId]) { + if (label === this) continue; + label.previousElementSibling.checked = true; + } + window.localStorage.setItem("sphinx-design-last-tab", syncId); +} + +document.addEventListener("DOMContentLoaded", ready, false); diff --git a/_static/basic.css b/_static/basic.css new file mode 100644 index 0000000..30fee9d --- /dev/null +++ b/_static/basic.css @@ -0,0 +1,925 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 360px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a:visited { + color: #551A8B; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +nav.contents, +aside.topic, +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +nav.contents, +aside.topic, +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +nav.contents > :last-child, +aside.topic > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +nav.contents::after, +aside.topic::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +aside.footnote > span, +div.citation > span { + float: left; +} +aside.footnote > span:last-of-type, +div.citation > span:last-of-type { + padding-right: 0.5em; +} +aside.footnote > p { + margin-left: 2em; +} +div.citation > p { + margin-left: 4em; +} +aside.footnote > p:last-of-type, +div.citation > p:last-of-type { + margin-bottom: 0em; +} +aside.footnote > p:last-of-type:after, +div.citation > p:last-of-type:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.sig dd { + margin-top: 0px; + margin-bottom: 0px; +} + +.sig dl { + margin-top: 0px; + margin-bottom: 0px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0 0.5em; + content: ":"; + display: inline-block; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +.translated { + background-color: rgba(207, 255, 207, 0.2) +} + +.untranslated { + background-color: rgba(255, 207, 207, 0.2) +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; + white-space: nowrap; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff --git a/_static/debug.css b/_static/debug.css new file mode 100644 index 0000000..74d4aec --- /dev/null +++ b/_static/debug.css @@ -0,0 +1,69 @@ +/* + This CSS file should be overridden by the theme authors. It's + meant for debugging and developing the skeleton that this theme provides. +*/ +body { + font-family: -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, + "Apple Color Emoji", "Segoe UI Emoji"; + background: lavender; +} +.sb-announcement { + background: rgb(131, 131, 131); +} +.sb-announcement__inner { + background: black; + color: white; +} +.sb-header { + background: lightskyblue; +} +.sb-header__inner { + background: royalblue; + color: white; +} +.sb-header-secondary { + background: lightcyan; +} +.sb-header-secondary__inner { + background: cornflowerblue; + color: white; +} +.sb-sidebar-primary { + background: lightgreen; +} +.sb-main { + background: blanchedalmond; +} +.sb-main__inner { + background: antiquewhite; +} +.sb-header-article { + background: lightsteelblue; +} +.sb-article-container { + background: snow; +} +.sb-article-main { + background: white; +} +.sb-footer-article { + background: lightpink; +} +.sb-sidebar-secondary { + background: lightgoldenrodyellow; +} +.sb-footer-content { + background: plum; +} +.sb-footer-content__inner { + background: palevioletred; +} +.sb-footer { + background: pink; +} +.sb-footer__inner { + background: salmon; +} +.sb-article { + background: white; +} diff --git a/_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css b/_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css new file mode 100644 index 0000000..eb19f69 --- /dev/null +++ b/_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css @@ -0,0 +1 @@ +.sd-bg-primary{background-color:var(--sd-color-primary) !important}.sd-bg-text-primary{color:var(--sd-color-primary-text) !important}button.sd-bg-primary:focus,button.sd-bg-primary:hover{background-color:var(--sd-color-primary-highlight) !important}a.sd-bg-primary:focus,a.sd-bg-primary:hover{background-color:var(--sd-color-primary-highlight) !important}.sd-bg-secondary{background-color:var(--sd-color-secondary) !important}.sd-bg-text-secondary{color:var(--sd-color-secondary-text) !important}button.sd-bg-secondary:focus,button.sd-bg-secondary:hover{background-color:var(--sd-color-secondary-highlight) !important}a.sd-bg-secondary:focus,a.sd-bg-secondary:hover{background-color:var(--sd-color-secondary-highlight) !important}.sd-bg-success{background-color:var(--sd-color-success) !important}.sd-bg-text-success{color:var(--sd-color-success-text) !important}button.sd-bg-success:focus,button.sd-bg-success:hover{background-color:var(--sd-color-success-highlight) !important}a.sd-bg-success:focus,a.sd-bg-success:hover{background-color:var(--sd-color-success-highlight) !important}.sd-bg-info{background-color:var(--sd-color-info) !important}.sd-bg-text-info{color:var(--sd-color-info-text) !important}button.sd-bg-info:focus,button.sd-bg-info:hover{background-color:var(--sd-color-info-highlight) !important}a.sd-bg-info:focus,a.sd-bg-info:hover{background-color:var(--sd-color-info-highlight) !important}.sd-bg-warning{background-color:var(--sd-color-warning) !important}.sd-bg-text-warning{color:var(--sd-color-warning-text) !important}button.sd-bg-warning:focus,button.sd-bg-warning:hover{background-color:var(--sd-color-warning-highlight) !important}a.sd-bg-warning:focus,a.sd-bg-warning:hover{background-color:var(--sd-color-warning-highlight) !important}.sd-bg-danger{background-color:var(--sd-color-danger) !important}.sd-bg-text-danger{color:var(--sd-color-danger-text) !important}button.sd-bg-danger:focus,button.sd-bg-danger:hover{background-color:var(--sd-color-danger-highlight) !important}a.sd-bg-danger:focus,a.sd-bg-danger:hover{background-color:var(--sd-color-danger-highlight) !important}.sd-bg-light{background-color:var(--sd-color-light) !important}.sd-bg-text-light{color:var(--sd-color-light-text) !important}button.sd-bg-light:focus,button.sd-bg-light:hover{background-color:var(--sd-color-light-highlight) !important}a.sd-bg-light:focus,a.sd-bg-light:hover{background-color:var(--sd-color-light-highlight) !important}.sd-bg-muted{background-color:var(--sd-color-muted) !important}.sd-bg-text-muted{color:var(--sd-color-muted-text) !important}button.sd-bg-muted:focus,button.sd-bg-muted:hover{background-color:var(--sd-color-muted-highlight) !important}a.sd-bg-muted:focus,a.sd-bg-muted:hover{background-color:var(--sd-color-muted-highlight) !important}.sd-bg-dark{background-color:var(--sd-color-dark) !important}.sd-bg-text-dark{color:var(--sd-color-dark-text) !important}button.sd-bg-dark:focus,button.sd-bg-dark:hover{background-color:var(--sd-color-dark-highlight) !important}a.sd-bg-dark:focus,a.sd-bg-dark:hover{background-color:var(--sd-color-dark-highlight) !important}.sd-bg-black{background-color:var(--sd-color-black) !important}.sd-bg-text-black{color:var(--sd-color-black-text) !important}button.sd-bg-black:focus,button.sd-bg-black:hover{background-color:var(--sd-color-black-highlight) !important}a.sd-bg-black:focus,a.sd-bg-black:hover{background-color:var(--sd-color-black-highlight) !important}.sd-bg-white{background-color:var(--sd-color-white) !important}.sd-bg-text-white{color:var(--sd-color-white-text) !important}button.sd-bg-white:focus,button.sd-bg-white:hover{background-color:var(--sd-color-white-highlight) !important}a.sd-bg-white:focus,a.sd-bg-white:hover{background-color:var(--sd-color-white-highlight) !important}.sd-text-primary,.sd-text-primary>p{color:var(--sd-color-primary) !important}a.sd-text-primary:focus,a.sd-text-primary:hover{color:var(--sd-color-primary-highlight) !important}.sd-text-secondary,.sd-text-secondary>p{color:var(--sd-color-secondary) !important}a.sd-text-secondary:focus,a.sd-text-secondary:hover{color:var(--sd-color-secondary-highlight) !important}.sd-text-success,.sd-text-success>p{color:var(--sd-color-success) !important}a.sd-text-success:focus,a.sd-text-success:hover{color:var(--sd-color-success-highlight) !important}.sd-text-info,.sd-text-info>p{color:var(--sd-color-info) !important}a.sd-text-info:focus,a.sd-text-info:hover{color:var(--sd-color-info-highlight) !important}.sd-text-warning,.sd-text-warning>p{color:var(--sd-color-warning) !important}a.sd-text-warning:focus,a.sd-text-warning:hover{color:var(--sd-color-warning-highlight) !important}.sd-text-danger,.sd-text-danger>p{color:var(--sd-color-danger) !important}a.sd-text-danger:focus,a.sd-text-danger:hover{color:var(--sd-color-danger-highlight) !important}.sd-text-light,.sd-text-light>p{color:var(--sd-color-light) !important}a.sd-text-light:focus,a.sd-text-light:hover{color:var(--sd-color-light-highlight) !important}.sd-text-muted,.sd-text-muted>p{color:var(--sd-color-muted) !important}a.sd-text-muted:focus,a.sd-text-muted:hover{color:var(--sd-color-muted-highlight) !important}.sd-text-dark,.sd-text-dark>p{color:var(--sd-color-dark) !important}a.sd-text-dark:focus,a.sd-text-dark:hover{color:var(--sd-color-dark-highlight) !important}.sd-text-black,.sd-text-black>p{color:var(--sd-color-black) !important}a.sd-text-black:focus,a.sd-text-black:hover{color:var(--sd-color-black-highlight) !important}.sd-text-white,.sd-text-white>p{color:var(--sd-color-white) !important}a.sd-text-white:focus,a.sd-text-white:hover{color:var(--sd-color-white-highlight) !important}.sd-outline-primary{border-color:var(--sd-color-primary) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-primary:focus,a.sd-outline-primary:hover{border-color:var(--sd-color-primary-highlight) !important}.sd-outline-secondary{border-color:var(--sd-color-secondary) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-secondary:focus,a.sd-outline-secondary:hover{border-color:var(--sd-color-secondary-highlight) !important}.sd-outline-success{border-color:var(--sd-color-success) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-success:focus,a.sd-outline-success:hover{border-color:var(--sd-color-success-highlight) !important}.sd-outline-info{border-color:var(--sd-color-info) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-info:focus,a.sd-outline-info:hover{border-color:var(--sd-color-info-highlight) !important}.sd-outline-warning{border-color:var(--sd-color-warning) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-warning:focus,a.sd-outline-warning:hover{border-color:var(--sd-color-warning-highlight) !important}.sd-outline-danger{border-color:var(--sd-color-danger) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-danger:focus,a.sd-outline-danger:hover{border-color:var(--sd-color-danger-highlight) !important}.sd-outline-light{border-color:var(--sd-color-light) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-light:focus,a.sd-outline-light:hover{border-color:var(--sd-color-light-highlight) !important}.sd-outline-muted{border-color:var(--sd-color-muted) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-muted:focus,a.sd-outline-muted:hover{border-color:var(--sd-color-muted-highlight) !important}.sd-outline-dark{border-color:var(--sd-color-dark) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-dark:focus,a.sd-outline-dark:hover{border-color:var(--sd-color-dark-highlight) !important}.sd-outline-black{border-color:var(--sd-color-black) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-black:focus,a.sd-outline-black:hover{border-color:var(--sd-color-black-highlight) !important}.sd-outline-white{border-color:var(--sd-color-white) !important;border-style:solid !important;border-width:1px !important}a.sd-outline-white:focus,a.sd-outline-white:hover{border-color:var(--sd-color-white-highlight) !important}.sd-bg-transparent{background-color:transparent !important}.sd-outline-transparent{border-color:transparent !important}.sd-text-transparent{color:transparent !important}.sd-p-0{padding:0 !important}.sd-pt-0,.sd-py-0{padding-top:0 !important}.sd-pr-0,.sd-px-0{padding-right:0 !important}.sd-pb-0,.sd-py-0{padding-bottom:0 !important}.sd-pl-0,.sd-px-0{padding-left:0 !important}.sd-p-1{padding:.25rem !important}.sd-pt-1,.sd-py-1{padding-top:.25rem !important}.sd-pr-1,.sd-px-1{padding-right:.25rem !important}.sd-pb-1,.sd-py-1{padding-bottom:.25rem !important}.sd-pl-1,.sd-px-1{padding-left:.25rem !important}.sd-p-2{padding:.5rem !important}.sd-pt-2,.sd-py-2{padding-top:.5rem !important}.sd-pr-2,.sd-px-2{padding-right:.5rem !important}.sd-pb-2,.sd-py-2{padding-bottom:.5rem !important}.sd-pl-2,.sd-px-2{padding-left:.5rem !important}.sd-p-3{padding:1rem !important}.sd-pt-3,.sd-py-3{padding-top:1rem !important}.sd-pr-3,.sd-px-3{padding-right:1rem !important}.sd-pb-3,.sd-py-3{padding-bottom:1rem !important}.sd-pl-3,.sd-px-3{padding-left:1rem !important}.sd-p-4{padding:1.5rem !important}.sd-pt-4,.sd-py-4{padding-top:1.5rem !important}.sd-pr-4,.sd-px-4{padding-right:1.5rem !important}.sd-pb-4,.sd-py-4{padding-bottom:1.5rem !important}.sd-pl-4,.sd-px-4{padding-left:1.5rem !important}.sd-p-5{padding:3rem !important}.sd-pt-5,.sd-py-5{padding-top:3rem !important}.sd-pr-5,.sd-px-5{padding-right:3rem !important}.sd-pb-5,.sd-py-5{padding-bottom:3rem !important}.sd-pl-5,.sd-px-5{padding-left:3rem !important}.sd-m-auto{margin:auto !important}.sd-mt-auto,.sd-my-auto{margin-top:auto !important}.sd-mr-auto,.sd-mx-auto{margin-right:auto !important}.sd-mb-auto,.sd-my-auto{margin-bottom:auto !important}.sd-ml-auto,.sd-mx-auto{margin-left:auto !important}.sd-m-0{margin:0 !important}.sd-mt-0,.sd-my-0{margin-top:0 !important}.sd-mr-0,.sd-mx-0{margin-right:0 !important}.sd-mb-0,.sd-my-0{margin-bottom:0 !important}.sd-ml-0,.sd-mx-0{margin-left:0 !important}.sd-m-1{margin:.25rem !important}.sd-mt-1,.sd-my-1{margin-top:.25rem !important}.sd-mr-1,.sd-mx-1{margin-right:.25rem !important}.sd-mb-1,.sd-my-1{margin-bottom:.25rem !important}.sd-ml-1,.sd-mx-1{margin-left:.25rem !important}.sd-m-2{margin:.5rem !important}.sd-mt-2,.sd-my-2{margin-top:.5rem !important}.sd-mr-2,.sd-mx-2{margin-right:.5rem !important}.sd-mb-2,.sd-my-2{margin-bottom:.5rem !important}.sd-ml-2,.sd-mx-2{margin-left:.5rem !important}.sd-m-3{margin:1rem !important}.sd-mt-3,.sd-my-3{margin-top:1rem !important}.sd-mr-3,.sd-mx-3{margin-right:1rem !important}.sd-mb-3,.sd-my-3{margin-bottom:1rem !important}.sd-ml-3,.sd-mx-3{margin-left:1rem !important}.sd-m-4{margin:1.5rem !important}.sd-mt-4,.sd-my-4{margin-top:1.5rem !important}.sd-mr-4,.sd-mx-4{margin-right:1.5rem !important}.sd-mb-4,.sd-my-4{margin-bottom:1.5rem !important}.sd-ml-4,.sd-mx-4{margin-left:1.5rem !important}.sd-m-5{margin:3rem !important}.sd-mt-5,.sd-my-5{margin-top:3rem !important}.sd-mr-5,.sd-mx-5{margin-right:3rem !important}.sd-mb-5,.sd-my-5{margin-bottom:3rem !important}.sd-ml-5,.sd-mx-5{margin-left:3rem !important}.sd-w-25{width:25% !important}.sd-w-50{width:50% !important}.sd-w-75{width:75% !important}.sd-w-100{width:100% !important}.sd-w-auto{width:auto !important}.sd-h-25{height:25% !important}.sd-h-50{height:50% !important}.sd-h-75{height:75% !important}.sd-h-100{height:100% !important}.sd-h-auto{height:auto !important}.sd-d-none{display:none !important}.sd-d-inline{display:inline !important}.sd-d-inline-block{display:inline-block !important}.sd-d-block{display:block !important}.sd-d-grid{display:grid !important}.sd-d-flex-row{display:-ms-flexbox !important;display:flex !important;flex-direction:row !important}.sd-d-flex-column{display:-ms-flexbox !important;display:flex !important;flex-direction:column !important}.sd-d-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}@media(min-width: 576px){.sd-d-sm-none{display:none !important}.sd-d-sm-inline{display:inline !important}.sd-d-sm-inline-block{display:inline-block !important}.sd-d-sm-block{display:block !important}.sd-d-sm-grid{display:grid !important}.sd-d-sm-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-sm-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}@media(min-width: 768px){.sd-d-md-none{display:none !important}.sd-d-md-inline{display:inline !important}.sd-d-md-inline-block{display:inline-block !important}.sd-d-md-block{display:block !important}.sd-d-md-grid{display:grid !important}.sd-d-md-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-md-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}@media(min-width: 992px){.sd-d-lg-none{display:none !important}.sd-d-lg-inline{display:inline !important}.sd-d-lg-inline-block{display:inline-block !important}.sd-d-lg-block{display:block !important}.sd-d-lg-grid{display:grid !important}.sd-d-lg-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-lg-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}@media(min-width: 1200px){.sd-d-xl-none{display:none !important}.sd-d-xl-inline{display:inline !important}.sd-d-xl-inline-block{display:inline-block !important}.sd-d-xl-block{display:block !important}.sd-d-xl-grid{display:grid !important}.sd-d-xl-flex{display:-ms-flexbox !important;display:flex !important}.sd-d-xl-inline-flex{display:-ms-inline-flexbox !important;display:inline-flex !important}}.sd-align-major-start{justify-content:flex-start !important}.sd-align-major-end{justify-content:flex-end !important}.sd-align-major-center{justify-content:center !important}.sd-align-major-justify{justify-content:space-between !important}.sd-align-major-spaced{justify-content:space-evenly !important}.sd-align-minor-start{align-items:flex-start !important}.sd-align-minor-end{align-items:flex-end !important}.sd-align-minor-center{align-items:center !important}.sd-align-minor-stretch{align-items:stretch !important}.sd-text-justify{text-align:justify !important}.sd-text-left{text-align:left !important}.sd-text-right{text-align:right !important}.sd-text-center{text-align:center !important}.sd-font-weight-light{font-weight:300 !important}.sd-font-weight-lighter{font-weight:lighter !important}.sd-font-weight-normal{font-weight:400 !important}.sd-font-weight-bold{font-weight:700 !important}.sd-font-weight-bolder{font-weight:bolder !important}.sd-font-italic{font-style:italic !important}.sd-text-decoration-none{text-decoration:none !important}.sd-text-lowercase{text-transform:lowercase !important}.sd-text-uppercase{text-transform:uppercase !important}.sd-text-capitalize{text-transform:capitalize !important}.sd-text-wrap{white-space:normal !important}.sd-text-nowrap{white-space:nowrap !important}.sd-text-truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.sd-fs-1,.sd-fs-1>p{font-size:calc(1.375rem + 1.5vw) !important;line-height:unset !important}.sd-fs-2,.sd-fs-2>p{font-size:calc(1.325rem + 0.9vw) !important;line-height:unset !important}.sd-fs-3,.sd-fs-3>p{font-size:calc(1.3rem + 0.6vw) !important;line-height:unset !important}.sd-fs-4,.sd-fs-4>p{font-size:calc(1.275rem + 0.3vw) !important;line-height:unset !important}.sd-fs-5,.sd-fs-5>p{font-size:1.25rem !important;line-height:unset !important}.sd-fs-6,.sd-fs-6>p{font-size:1rem !important;line-height:unset !important}.sd-border-0{border:0 solid !important}.sd-border-top-0{border-top:0 solid !important}.sd-border-bottom-0{border-bottom:0 solid !important}.sd-border-right-0{border-right:0 solid !important}.sd-border-left-0{border-left:0 solid !important}.sd-border-1{border:1px solid !important}.sd-border-top-1{border-top:1px solid !important}.sd-border-bottom-1{border-bottom:1px solid !important}.sd-border-right-1{border-right:1px solid !important}.sd-border-left-1{border-left:1px solid !important}.sd-border-2{border:2px solid !important}.sd-border-top-2{border-top:2px solid !important}.sd-border-bottom-2{border-bottom:2px solid !important}.sd-border-right-2{border-right:2px solid !important}.sd-border-left-2{border-left:2px solid !important}.sd-border-3{border:3px solid !important}.sd-border-top-3{border-top:3px solid !important}.sd-border-bottom-3{border-bottom:3px solid !important}.sd-border-right-3{border-right:3px solid !important}.sd-border-left-3{border-left:3px solid !important}.sd-border-4{border:4px solid !important}.sd-border-top-4{border-top:4px solid !important}.sd-border-bottom-4{border-bottom:4px solid !important}.sd-border-right-4{border-right:4px solid !important}.sd-border-left-4{border-left:4px solid !important}.sd-border-5{border:5px solid !important}.sd-border-top-5{border-top:5px solid !important}.sd-border-bottom-5{border-bottom:5px solid !important}.sd-border-right-5{border-right:5px solid !important}.sd-border-left-5{border-left:5px solid !important}.sd-rounded-0{border-radius:0 !important}.sd-rounded-1{border-radius:.2rem !important}.sd-rounded-2{border-radius:.3rem !important}.sd-rounded-3{border-radius:.5rem !important}.sd-rounded-pill{border-radius:50rem !important}.sd-rounded-circle{border-radius:50% !important}.shadow-none{box-shadow:none !important}.sd-shadow-sm{box-shadow:0 .125rem .25rem var(--sd-color-shadow) !important}.sd-shadow-md{box-shadow:0 .5rem 1rem var(--sd-color-shadow) !important}.sd-shadow-lg{box-shadow:0 1rem 3rem var(--sd-color-shadow) !important}@keyframes sd-slide-from-left{0%{transform:translateX(-100%)}100%{transform:translateX(0)}}@keyframes sd-slide-from-right{0%{transform:translateX(200%)}100%{transform:translateX(0)}}@keyframes sd-grow100{0%{transform:scale(0);opacity:.5}100%{transform:scale(1);opacity:1}}@keyframes sd-grow50{0%{transform:scale(0.5);opacity:.5}100%{transform:scale(1);opacity:1}}@keyframes sd-grow50-rot20{0%{transform:scale(0.5) rotateZ(-20deg);opacity:.5}75%{transform:scale(1) rotateZ(5deg);opacity:1}95%{transform:scale(1) rotateZ(-1deg);opacity:1}100%{transform:scale(1) rotateZ(0);opacity:1}}.sd-animate-slide-from-left{animation:1s ease-out 0s 1 normal none running sd-slide-from-left}.sd-animate-slide-from-right{animation:1s ease-out 0s 1 normal none running sd-slide-from-right}.sd-animate-grow100{animation:1s ease-out 0s 1 normal none running sd-grow100}.sd-animate-grow50{animation:1s ease-out 0s 1 normal none running sd-grow50}.sd-animate-grow50-rot20{animation:1s ease-out 0s 1 normal none running sd-grow50-rot20}.sd-badge{display:inline-block;padding:.35em .65em;font-size:.75em;font-weight:700;line-height:1;text-align:center;white-space:nowrap;vertical-align:baseline;border-radius:.25rem}.sd-badge:empty{display:none}a.sd-badge{text-decoration:none}.sd-btn .sd-badge{position:relative;top:-1px}.sd-btn{background-color:transparent;border:1px solid transparent;border-radius:.25rem;cursor:pointer;display:inline-block;font-weight:400;font-size:1rem;line-height:1.5;padding:.375rem .75rem;text-align:center;text-decoration:none;transition:color .15s ease-in-out,background-color .15s ease-in-out,border-color .15s ease-in-out,box-shadow .15s ease-in-out;vertical-align:middle;user-select:none;-moz-user-select:none;-ms-user-select:none;-webkit-user-select:none}.sd-btn:hover{text-decoration:none}@media(prefers-reduced-motion: reduce){.sd-btn{transition:none}}.sd-btn-primary,.sd-btn-outline-primary:hover,.sd-btn-outline-primary:focus{color:var(--sd-color-primary-text) !important;background-color:var(--sd-color-primary) !important;border-color:var(--sd-color-primary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-primary:hover,.sd-btn-primary:focus{color:var(--sd-color-primary-text) !important;background-color:var(--sd-color-primary-highlight) !important;border-color:var(--sd-color-primary-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-primary{color:var(--sd-color-primary) !important;border-color:var(--sd-color-primary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-secondary,.sd-btn-outline-secondary:hover,.sd-btn-outline-secondary:focus{color:var(--sd-color-secondary-text) !important;background-color:var(--sd-color-secondary) !important;border-color:var(--sd-color-secondary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-secondary:hover,.sd-btn-secondary:focus{color:var(--sd-color-secondary-text) !important;background-color:var(--sd-color-secondary-highlight) !important;border-color:var(--sd-color-secondary-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-secondary{color:var(--sd-color-secondary) !important;border-color:var(--sd-color-secondary) !important;border-width:1px !important;border-style:solid !important}.sd-btn-success,.sd-btn-outline-success:hover,.sd-btn-outline-success:focus{color:var(--sd-color-success-text) !important;background-color:var(--sd-color-success) !important;border-color:var(--sd-color-success) !important;border-width:1px !important;border-style:solid !important}.sd-btn-success:hover,.sd-btn-success:focus{color:var(--sd-color-success-text) !important;background-color:var(--sd-color-success-highlight) !important;border-color:var(--sd-color-success-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-success{color:var(--sd-color-success) !important;border-color:var(--sd-color-success) !important;border-width:1px !important;border-style:solid !important}.sd-btn-info,.sd-btn-outline-info:hover,.sd-btn-outline-info:focus{color:var(--sd-color-info-text) !important;background-color:var(--sd-color-info) !important;border-color:var(--sd-color-info) !important;border-width:1px !important;border-style:solid !important}.sd-btn-info:hover,.sd-btn-info:focus{color:var(--sd-color-info-text) !important;background-color:var(--sd-color-info-highlight) !important;border-color:var(--sd-color-info-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-info{color:var(--sd-color-info) !important;border-color:var(--sd-color-info) !important;border-width:1px !important;border-style:solid !important}.sd-btn-warning,.sd-btn-outline-warning:hover,.sd-btn-outline-warning:focus{color:var(--sd-color-warning-text) !important;background-color:var(--sd-color-warning) !important;border-color:var(--sd-color-warning) !important;border-width:1px !important;border-style:solid !important}.sd-btn-warning:hover,.sd-btn-warning:focus{color:var(--sd-color-warning-text) !important;background-color:var(--sd-color-warning-highlight) !important;border-color:var(--sd-color-warning-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-warning{color:var(--sd-color-warning) !important;border-color:var(--sd-color-warning) !important;border-width:1px !important;border-style:solid !important}.sd-btn-danger,.sd-btn-outline-danger:hover,.sd-btn-outline-danger:focus{color:var(--sd-color-danger-text) !important;background-color:var(--sd-color-danger) !important;border-color:var(--sd-color-danger) !important;border-width:1px !important;border-style:solid !important}.sd-btn-danger:hover,.sd-btn-danger:focus{color:var(--sd-color-danger-text) !important;background-color:var(--sd-color-danger-highlight) !important;border-color:var(--sd-color-danger-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-danger{color:var(--sd-color-danger) !important;border-color:var(--sd-color-danger) !important;border-width:1px !important;border-style:solid !important}.sd-btn-light,.sd-btn-outline-light:hover,.sd-btn-outline-light:focus{color:var(--sd-color-light-text) !important;background-color:var(--sd-color-light) !important;border-color:var(--sd-color-light) !important;border-width:1px !important;border-style:solid !important}.sd-btn-light:hover,.sd-btn-light:focus{color:var(--sd-color-light-text) !important;background-color:var(--sd-color-light-highlight) !important;border-color:var(--sd-color-light-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-light{color:var(--sd-color-light) !important;border-color:var(--sd-color-light) !important;border-width:1px !important;border-style:solid !important}.sd-btn-muted,.sd-btn-outline-muted:hover,.sd-btn-outline-muted:focus{color:var(--sd-color-muted-text) !important;background-color:var(--sd-color-muted) !important;border-color:var(--sd-color-muted) !important;border-width:1px !important;border-style:solid !important}.sd-btn-muted:hover,.sd-btn-muted:focus{color:var(--sd-color-muted-text) !important;background-color:var(--sd-color-muted-highlight) !important;border-color:var(--sd-color-muted-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-muted{color:var(--sd-color-muted) !important;border-color:var(--sd-color-muted) !important;border-width:1px !important;border-style:solid !important}.sd-btn-dark,.sd-btn-outline-dark:hover,.sd-btn-outline-dark:focus{color:var(--sd-color-dark-text) !important;background-color:var(--sd-color-dark) !important;border-color:var(--sd-color-dark) !important;border-width:1px !important;border-style:solid !important}.sd-btn-dark:hover,.sd-btn-dark:focus{color:var(--sd-color-dark-text) !important;background-color:var(--sd-color-dark-highlight) !important;border-color:var(--sd-color-dark-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-dark{color:var(--sd-color-dark) !important;border-color:var(--sd-color-dark) !important;border-width:1px !important;border-style:solid !important}.sd-btn-black,.sd-btn-outline-black:hover,.sd-btn-outline-black:focus{color:var(--sd-color-black-text) !important;background-color:var(--sd-color-black) !important;border-color:var(--sd-color-black) !important;border-width:1px !important;border-style:solid !important}.sd-btn-black:hover,.sd-btn-black:focus{color:var(--sd-color-black-text) !important;background-color:var(--sd-color-black-highlight) !important;border-color:var(--sd-color-black-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-black{color:var(--sd-color-black) !important;border-color:var(--sd-color-black) !important;border-width:1px !important;border-style:solid !important}.sd-btn-white,.sd-btn-outline-white:hover,.sd-btn-outline-white:focus{color:var(--sd-color-white-text) !important;background-color:var(--sd-color-white) !important;border-color:var(--sd-color-white) !important;border-width:1px !important;border-style:solid !important}.sd-btn-white:hover,.sd-btn-white:focus{color:var(--sd-color-white-text) !important;background-color:var(--sd-color-white-highlight) !important;border-color:var(--sd-color-white-highlight) !important;border-width:1px !important;border-style:solid !important}.sd-btn-outline-white{color:var(--sd-color-white) !important;border-color:var(--sd-color-white) !important;border-width:1px !important;border-style:solid !important}.sd-stretched-link::after{position:absolute;top:0;right:0;bottom:0;left:0;z-index:1;content:""}.sd-hide-link-text{font-size:0}.sd-octicon,.sd-material-icon{display:inline-block;fill:currentColor;vertical-align:middle}.sd-avatar-xs{border-radius:50%;object-fit:cover;object-position:center;width:1rem;height:1rem}.sd-avatar-sm{border-radius:50%;object-fit:cover;object-position:center;width:3rem;height:3rem}.sd-avatar-md{border-radius:50%;object-fit:cover;object-position:center;width:5rem;height:5rem}.sd-avatar-lg{border-radius:50%;object-fit:cover;object-position:center;width:7rem;height:7rem}.sd-avatar-xl{border-radius:50%;object-fit:cover;object-position:center;width:10rem;height:10rem}.sd-avatar-inherit{border-radius:50%;object-fit:cover;object-position:center;width:inherit;height:inherit}.sd-avatar-initial{border-radius:50%;object-fit:cover;object-position:center;width:initial;height:initial}.sd-card{background-clip:border-box;background-color:var(--sd-color-card-background);border:1px solid var(--sd-color-card-border);border-radius:.25rem;color:var(--sd-color-card-text);display:-ms-flexbox;display:flex;-ms-flex-direction:column;flex-direction:column;min-width:0;position:relative;word-wrap:break-word}.sd-card>hr{margin-left:0;margin-right:0}.sd-card-hover:hover{border-color:var(--sd-color-card-border-hover);transform:scale(1.01)}.sd-card-body{-ms-flex:1 1 auto;flex:1 1 auto;padding:1rem 1rem}.sd-card-title{margin-bottom:.5rem}.sd-card-subtitle{margin-top:-0.25rem;margin-bottom:0}.sd-card-text:last-child{margin-bottom:0}.sd-card-link:hover{text-decoration:none}.sd-card-link+.card-link{margin-left:1rem}.sd-card-header{padding:.5rem 1rem;margin-bottom:0;background-color:var(--sd-color-card-header);border-bottom:1px solid var(--sd-color-card-border)}.sd-card-header:first-child{border-radius:calc(0.25rem - 1px) calc(0.25rem - 1px) 0 0}.sd-card-footer{padding:.5rem 1rem;background-color:var(--sd-color-card-footer);border-top:1px solid var(--sd-color-card-border)}.sd-card-footer:last-child{border-radius:0 0 calc(0.25rem - 1px) calc(0.25rem - 1px)}.sd-card-header-tabs{margin-right:-0.5rem;margin-bottom:-0.5rem;margin-left:-0.5rem;border-bottom:0}.sd-card-header-pills{margin-right:-0.5rem;margin-left:-0.5rem}.sd-card-img-overlay{position:absolute;top:0;right:0;bottom:0;left:0;padding:1rem;border-radius:calc(0.25rem - 1px)}.sd-card-img,.sd-card-img-bottom,.sd-card-img-top{width:100%}.sd-card-img,.sd-card-img-top{border-top-left-radius:calc(0.25rem - 1px);border-top-right-radius:calc(0.25rem - 1px)}.sd-card-img,.sd-card-img-bottom{border-bottom-left-radius:calc(0.25rem - 1px);border-bottom-right-radius:calc(0.25rem - 1px)}.sd-cards-carousel{width:100%;display:flex;flex-wrap:nowrap;-ms-flex-direction:row;flex-direction:row;overflow-x:hidden;scroll-snap-type:x mandatory}.sd-cards-carousel.sd-show-scrollbar{overflow-x:auto}.sd-cards-carousel:hover,.sd-cards-carousel:focus{overflow-x:auto}.sd-cards-carousel>.sd-card{flex-shrink:0;scroll-snap-align:start}.sd-cards-carousel>.sd-card:not(:last-child){margin-right:3px}.sd-card-cols-1>.sd-card{width:90%}.sd-card-cols-2>.sd-card{width:45%}.sd-card-cols-3>.sd-card{width:30%}.sd-card-cols-4>.sd-card{width:22.5%}.sd-card-cols-5>.sd-card{width:18%}.sd-card-cols-6>.sd-card{width:15%}.sd-card-cols-7>.sd-card{width:12.8571428571%}.sd-card-cols-8>.sd-card{width:11.25%}.sd-card-cols-9>.sd-card{width:10%}.sd-card-cols-10>.sd-card{width:9%}.sd-card-cols-11>.sd-card{width:8.1818181818%}.sd-card-cols-12>.sd-card{width:7.5%}.sd-container,.sd-container-fluid,.sd-container-lg,.sd-container-md,.sd-container-sm,.sd-container-xl{margin-left:auto;margin-right:auto;padding-left:var(--sd-gutter-x, 0.75rem);padding-right:var(--sd-gutter-x, 0.75rem);width:100%}@media(min-width: 576px){.sd-container-sm,.sd-container{max-width:540px}}@media(min-width: 768px){.sd-container-md,.sd-container-sm,.sd-container{max-width:720px}}@media(min-width: 992px){.sd-container-lg,.sd-container-md,.sd-container-sm,.sd-container{max-width:960px}}@media(min-width: 1200px){.sd-container-xl,.sd-container-lg,.sd-container-md,.sd-container-sm,.sd-container{max-width:1140px}}.sd-row{--sd-gutter-x: 1.5rem;--sd-gutter-y: 0;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;margin-top:calc(var(--sd-gutter-y) * -1);margin-right:calc(var(--sd-gutter-x) * -0.5);margin-left:calc(var(--sd-gutter-x) * -0.5)}.sd-row>*{box-sizing:border-box;flex-shrink:0;width:100%;max-width:100%;padding-right:calc(var(--sd-gutter-x) * 0.5);padding-left:calc(var(--sd-gutter-x) * 0.5);margin-top:var(--sd-gutter-y)}.sd-col{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-auto>*{flex:0 0 auto;width:auto}.sd-row-cols-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}@media(min-width: 576px){.sd-col-sm{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-sm-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-sm-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-sm-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-sm-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-sm-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-sm-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-sm-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-sm-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-sm-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-sm-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-sm-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-sm-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-sm-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}@media(min-width: 768px){.sd-col-md{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-md-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-md-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-md-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-md-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-md-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-md-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-md-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-md-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-md-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-md-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-md-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-md-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-md-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}@media(min-width: 992px){.sd-col-lg{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-lg-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-lg-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-lg-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-lg-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-lg-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-lg-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-lg-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-lg-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-lg-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-lg-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-lg-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-lg-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-lg-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}@media(min-width: 1200px){.sd-col-xl{flex:1 0 0%;-ms-flex:1 0 0%}.sd-row-cols-xl-auto{flex:1 0 auto;-ms-flex:1 0 auto;width:100%}.sd-row-cols-xl-1>*{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-row-cols-xl-2>*{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-row-cols-xl-3>*{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-row-cols-xl-4>*{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-row-cols-xl-5>*{flex:0 0 auto;-ms-flex:0 0 auto;width:20%}.sd-row-cols-xl-6>*{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-row-cols-xl-7>*{flex:0 0 auto;-ms-flex:0 0 auto;width:14.2857142857%}.sd-row-cols-xl-8>*{flex:0 0 auto;-ms-flex:0 0 auto;width:12.5%}.sd-row-cols-xl-9>*{flex:0 0 auto;-ms-flex:0 0 auto;width:11.1111111111%}.sd-row-cols-xl-10>*{flex:0 0 auto;-ms-flex:0 0 auto;width:10%}.sd-row-cols-xl-11>*{flex:0 0 auto;-ms-flex:0 0 auto;width:9.0909090909%}.sd-row-cols-xl-12>*{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}}.sd-col-auto{flex:0 0 auto;-ms-flex:0 0 auto;width:auto}.sd-col-1{flex:0 0 auto;-ms-flex:0 0 auto;width:8.3333333333%}.sd-col-2{flex:0 0 auto;-ms-flex:0 0 auto;width:16.6666666667%}.sd-col-3{flex:0 0 auto;-ms-flex:0 0 auto;width:25%}.sd-col-4{flex:0 0 auto;-ms-flex:0 0 auto;width:33.3333333333%}.sd-col-5{flex:0 0 auto;-ms-flex:0 0 auto;width:41.6666666667%}.sd-col-6{flex:0 0 auto;-ms-flex:0 0 auto;width:50%}.sd-col-7{flex:0 0 auto;-ms-flex:0 0 auto;width:58.3333333333%}.sd-col-8{flex:0 0 auto;-ms-flex:0 0 auto;width:66.6666666667%}.sd-col-9{flex:0 0 auto;-ms-flex:0 0 auto;width:75%}.sd-col-10{flex:0 0 auto;-ms-flex:0 0 auto;width:83.3333333333%}.sd-col-11{flex:0 0 auto;-ms-flex:0 0 auto;width:91.6666666667%}.sd-col-12{flex:0 0 auto;-ms-flex:0 0 auto;width:100%}.sd-g-0,.sd-gy-0{--sd-gutter-y: 0}.sd-g-0,.sd-gx-0{--sd-gutter-x: 0}.sd-g-1,.sd-gy-1{--sd-gutter-y: 0.25rem}.sd-g-1,.sd-gx-1{--sd-gutter-x: 0.25rem}.sd-g-2,.sd-gy-2{--sd-gutter-y: 0.5rem}.sd-g-2,.sd-gx-2{--sd-gutter-x: 0.5rem}.sd-g-3,.sd-gy-3{--sd-gutter-y: 1rem}.sd-g-3,.sd-gx-3{--sd-gutter-x: 1rem}.sd-g-4,.sd-gy-4{--sd-gutter-y: 1.5rem}.sd-g-4,.sd-gx-4{--sd-gutter-x: 1.5rem}.sd-g-5,.sd-gy-5{--sd-gutter-y: 3rem}.sd-g-5,.sd-gx-5{--sd-gutter-x: 3rem}@media(min-width: 576px){.sd-col-sm-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-sm-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-sm-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-sm-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-sm-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-sm-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-sm-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-sm-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-sm-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-sm-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-sm-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-sm-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-sm-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-sm-0,.sd-gy-sm-0{--sd-gutter-y: 0}.sd-g-sm-0,.sd-gx-sm-0{--sd-gutter-x: 0}.sd-g-sm-1,.sd-gy-sm-1{--sd-gutter-y: 0.25rem}.sd-g-sm-1,.sd-gx-sm-1{--sd-gutter-x: 0.25rem}.sd-g-sm-2,.sd-gy-sm-2{--sd-gutter-y: 0.5rem}.sd-g-sm-2,.sd-gx-sm-2{--sd-gutter-x: 0.5rem}.sd-g-sm-3,.sd-gy-sm-3{--sd-gutter-y: 1rem}.sd-g-sm-3,.sd-gx-sm-3{--sd-gutter-x: 1rem}.sd-g-sm-4,.sd-gy-sm-4{--sd-gutter-y: 1.5rem}.sd-g-sm-4,.sd-gx-sm-4{--sd-gutter-x: 1.5rem}.sd-g-sm-5,.sd-gy-sm-5{--sd-gutter-y: 3rem}.sd-g-sm-5,.sd-gx-sm-5{--sd-gutter-x: 3rem}}@media(min-width: 768px){.sd-col-md-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-md-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-md-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-md-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-md-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-md-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-md-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-md-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-md-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-md-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-md-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-md-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-md-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-md-0,.sd-gy-md-0{--sd-gutter-y: 0}.sd-g-md-0,.sd-gx-md-0{--sd-gutter-x: 0}.sd-g-md-1,.sd-gy-md-1{--sd-gutter-y: 0.25rem}.sd-g-md-1,.sd-gx-md-1{--sd-gutter-x: 0.25rem}.sd-g-md-2,.sd-gy-md-2{--sd-gutter-y: 0.5rem}.sd-g-md-2,.sd-gx-md-2{--sd-gutter-x: 0.5rem}.sd-g-md-3,.sd-gy-md-3{--sd-gutter-y: 1rem}.sd-g-md-3,.sd-gx-md-3{--sd-gutter-x: 1rem}.sd-g-md-4,.sd-gy-md-4{--sd-gutter-y: 1.5rem}.sd-g-md-4,.sd-gx-md-4{--sd-gutter-x: 1.5rem}.sd-g-md-5,.sd-gy-md-5{--sd-gutter-y: 3rem}.sd-g-md-5,.sd-gx-md-5{--sd-gutter-x: 3rem}}@media(min-width: 992px){.sd-col-lg-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-lg-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-lg-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-lg-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-lg-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-lg-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-lg-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-lg-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-lg-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-lg-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-lg-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-lg-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-lg-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-lg-0,.sd-gy-lg-0{--sd-gutter-y: 0}.sd-g-lg-0,.sd-gx-lg-0{--sd-gutter-x: 0}.sd-g-lg-1,.sd-gy-lg-1{--sd-gutter-y: 0.25rem}.sd-g-lg-1,.sd-gx-lg-1{--sd-gutter-x: 0.25rem}.sd-g-lg-2,.sd-gy-lg-2{--sd-gutter-y: 0.5rem}.sd-g-lg-2,.sd-gx-lg-2{--sd-gutter-x: 0.5rem}.sd-g-lg-3,.sd-gy-lg-3{--sd-gutter-y: 1rem}.sd-g-lg-3,.sd-gx-lg-3{--sd-gutter-x: 1rem}.sd-g-lg-4,.sd-gy-lg-4{--sd-gutter-y: 1.5rem}.sd-g-lg-4,.sd-gx-lg-4{--sd-gutter-x: 1.5rem}.sd-g-lg-5,.sd-gy-lg-5{--sd-gutter-y: 3rem}.sd-g-lg-5,.sd-gx-lg-5{--sd-gutter-x: 3rem}}@media(min-width: 1200px){.sd-col-xl-auto{-ms-flex:0 0 auto;flex:0 0 auto;width:auto}.sd-col-xl-1{-ms-flex:0 0 auto;flex:0 0 auto;width:8.3333333333%}.sd-col-xl-2{-ms-flex:0 0 auto;flex:0 0 auto;width:16.6666666667%}.sd-col-xl-3{-ms-flex:0 0 auto;flex:0 0 auto;width:25%}.sd-col-xl-4{-ms-flex:0 0 auto;flex:0 0 auto;width:33.3333333333%}.sd-col-xl-5{-ms-flex:0 0 auto;flex:0 0 auto;width:41.6666666667%}.sd-col-xl-6{-ms-flex:0 0 auto;flex:0 0 auto;width:50%}.sd-col-xl-7{-ms-flex:0 0 auto;flex:0 0 auto;width:58.3333333333%}.sd-col-xl-8{-ms-flex:0 0 auto;flex:0 0 auto;width:66.6666666667%}.sd-col-xl-9{-ms-flex:0 0 auto;flex:0 0 auto;width:75%}.sd-col-xl-10{-ms-flex:0 0 auto;flex:0 0 auto;width:83.3333333333%}.sd-col-xl-11{-ms-flex:0 0 auto;flex:0 0 auto;width:91.6666666667%}.sd-col-xl-12{-ms-flex:0 0 auto;flex:0 0 auto;width:100%}.sd-g-xl-0,.sd-gy-xl-0{--sd-gutter-y: 0}.sd-g-xl-0,.sd-gx-xl-0{--sd-gutter-x: 0}.sd-g-xl-1,.sd-gy-xl-1{--sd-gutter-y: 0.25rem}.sd-g-xl-1,.sd-gx-xl-1{--sd-gutter-x: 0.25rem}.sd-g-xl-2,.sd-gy-xl-2{--sd-gutter-y: 0.5rem}.sd-g-xl-2,.sd-gx-xl-2{--sd-gutter-x: 0.5rem}.sd-g-xl-3,.sd-gy-xl-3{--sd-gutter-y: 1rem}.sd-g-xl-3,.sd-gx-xl-3{--sd-gutter-x: 1rem}.sd-g-xl-4,.sd-gy-xl-4{--sd-gutter-y: 1.5rem}.sd-g-xl-4,.sd-gx-xl-4{--sd-gutter-x: 1.5rem}.sd-g-xl-5,.sd-gy-xl-5{--sd-gutter-y: 3rem}.sd-g-xl-5,.sd-gx-xl-5{--sd-gutter-x: 3rem}}.sd-flex-row-reverse{flex-direction:row-reverse !important}details.sd-dropdown{position:relative}details.sd-dropdown .sd-summary-title{font-weight:700;padding-right:3em !important;-moz-user-select:none;-ms-user-select:none;-webkit-user-select:none;user-select:none}details.sd-dropdown:hover{cursor:pointer}details.sd-dropdown .sd-summary-content{cursor:default}details.sd-dropdown summary{list-style:none;padding:1em}details.sd-dropdown summary .sd-octicon.no-title{vertical-align:middle}details.sd-dropdown[open] summary .sd-octicon.no-title{visibility:hidden}details.sd-dropdown summary::-webkit-details-marker{display:none}details.sd-dropdown summary:focus{outline:none}details.sd-dropdown .sd-summary-icon{margin-right:.5em}details.sd-dropdown .sd-summary-icon svg{opacity:.8}details.sd-dropdown summary:hover .sd-summary-up svg,details.sd-dropdown summary:hover .sd-summary-down svg{opacity:1;transform:scale(1.1)}details.sd-dropdown .sd-summary-up svg,details.sd-dropdown .sd-summary-down svg{display:block;opacity:.6}details.sd-dropdown .sd-summary-up,details.sd-dropdown .sd-summary-down{pointer-events:none;position:absolute;right:1em;top:1em}details.sd-dropdown[open]>.sd-summary-title .sd-summary-down{visibility:hidden}details.sd-dropdown:not([open])>.sd-summary-title .sd-summary-up{visibility:hidden}details.sd-dropdown:not([open]).sd-card{border:none}details.sd-dropdown:not([open])>.sd-card-header{border:1px solid var(--sd-color-card-border);border-radius:.25rem}details.sd-dropdown.sd-fade-in[open] summary~*{-moz-animation:sd-fade-in .5s ease-in-out;-webkit-animation:sd-fade-in .5s ease-in-out;animation:sd-fade-in .5s ease-in-out}details.sd-dropdown.sd-fade-in-slide-down[open] summary~*{-moz-animation:sd-fade-in .5s ease-in-out,sd-slide-down .5s ease-in-out;-webkit-animation:sd-fade-in .5s ease-in-out,sd-slide-down .5s ease-in-out;animation:sd-fade-in .5s ease-in-out,sd-slide-down .5s ease-in-out}.sd-col>.sd-dropdown{width:100%}.sd-summary-content>.sd-tab-set:first-child{margin-top:0}@keyframes sd-fade-in{0%{opacity:0}100%{opacity:1}}@keyframes sd-slide-down{0%{transform:translate(0, -10px)}100%{transform:translate(0, 0)}}.sd-tab-set{border-radius:.125rem;display:flex;flex-wrap:wrap;margin:1em 0;position:relative}.sd-tab-set>input{opacity:0;position:absolute}.sd-tab-set>input:checked+label{border-color:var(--sd-color-tabs-underline-active);color:var(--sd-color-tabs-label-active)}.sd-tab-set>input:checked+label+.sd-tab-content{display:block}.sd-tab-set>input:not(:checked)+label:hover{color:var(--sd-color-tabs-label-hover);border-color:var(--sd-color-tabs-underline-hover)}.sd-tab-set>input:focus+label{outline-style:auto}.sd-tab-set>input:not(.focus-visible)+label{outline:none;-webkit-tap-highlight-color:transparent}.sd-tab-set>label{border-bottom:.125rem solid transparent;margin-bottom:0;color:var(--sd-color-tabs-label-inactive);border-color:var(--sd-color-tabs-underline-inactive);cursor:pointer;font-size:var(--sd-fontsize-tabs-label);font-weight:700;padding:1em 1.25em .5em;transition:color 250ms;width:auto;z-index:1}html .sd-tab-set>label:hover{color:var(--sd-color-tabs-label-active)}.sd-col>.sd-tab-set{width:100%}.sd-tab-content{box-shadow:0 -0.0625rem var(--sd-color-tabs-overline),0 .0625rem var(--sd-color-tabs-underline);display:none;order:99;padding-bottom:.75rem;padding-top:.75rem;width:100%}.sd-tab-content>:first-child{margin-top:0 !important}.sd-tab-content>:last-child{margin-bottom:0 !important}.sd-tab-content>.sd-tab-set{margin:0}.sd-sphinx-override,.sd-sphinx-override *{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}.sd-sphinx-override p{margin-top:0}:root{--sd-color-primary: #0071bc;--sd-color-secondary: #6c757d;--sd-color-success: #28a745;--sd-color-info: #17a2b8;--sd-color-warning: #f0b37e;--sd-color-danger: #dc3545;--sd-color-light: #f8f9fa;--sd-color-muted: #6c757d;--sd-color-dark: #212529;--sd-color-black: black;--sd-color-white: white;--sd-color-primary-highlight: #0060a0;--sd-color-secondary-highlight: #5c636a;--sd-color-success-highlight: #228e3b;--sd-color-info-highlight: #148a9c;--sd-color-warning-highlight: #cc986b;--sd-color-danger-highlight: #bb2d3b;--sd-color-light-highlight: #d3d4d5;--sd-color-muted-highlight: #5c636a;--sd-color-dark-highlight: #1c1f23;--sd-color-black-highlight: black;--sd-color-white-highlight: #d9d9d9;--sd-color-primary-text: #fff;--sd-color-secondary-text: #fff;--sd-color-success-text: #fff;--sd-color-info-text: #fff;--sd-color-warning-text: #212529;--sd-color-danger-text: #fff;--sd-color-light-text: #212529;--sd-color-muted-text: #fff;--sd-color-dark-text: #fff;--sd-color-black-text: #fff;--sd-color-white-text: #212529;--sd-color-shadow: rgba(0, 0, 0, 0.15);--sd-color-card-border: rgba(0, 0, 0, 0.125);--sd-color-card-border-hover: hsla(231, 99%, 66%, 1);--sd-color-card-background: transparent;--sd-color-card-text: inherit;--sd-color-card-header: transparent;--sd-color-card-footer: transparent;--sd-color-tabs-label-active: hsla(231, 99%, 66%, 1);--sd-color-tabs-label-hover: hsla(231, 99%, 66%, 1);--sd-color-tabs-label-inactive: hsl(0, 0%, 66%);--sd-color-tabs-underline-active: hsla(231, 99%, 66%, 1);--sd-color-tabs-underline-hover: rgba(178, 206, 245, 0.62);--sd-color-tabs-underline-inactive: transparent;--sd-color-tabs-overline: rgb(222, 222, 222);--sd-color-tabs-underline: rgb(222, 222, 222);--sd-fontsize-tabs-label: 1rem} diff --git a/_static/design-tabs.js b/_static/design-tabs.js new file mode 100644 index 0000000..36b38cf --- /dev/null +++ b/_static/design-tabs.js @@ -0,0 +1,27 @@ +var sd_labels_by_text = {}; + +function ready() { + const li = document.getElementsByClassName("sd-tab-label"); + for (const label of li) { + syncId = label.getAttribute("data-sync-id"); + if (syncId) { + label.onclick = onLabelClick; + if (!sd_labels_by_text[syncId]) { + sd_labels_by_text[syncId] = []; + } + sd_labels_by_text[syncId].push(label); + } + } +} + +function onLabelClick() { + // Activate other inputs with the same sync id. + syncId = this.getAttribute("data-sync-id"); + for (label of sd_labels_by_text[syncId]) { + if (label === this) continue; + label.previousElementSibling.checked = true; + } + window.localStorage.setItem("sphinx-design-last-tab", syncId); +} + +document.addEventListener("DOMContentLoaded", ready, false); diff --git a/_static/doctools.js b/_static/doctools.js new file mode 100644 index 0000000..d06a71d --- /dev/null +++ b/_static/doctools.js @@ -0,0 +1,156 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Base JavaScript utilities for all Sphinx HTML documentation. + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([ + "TEXTAREA", + "INPUT", + "SELECT", + "BUTTON", +]); + +const _ready = (callback) => { + if (document.readyState !== "loading") { + callback(); + } else { + document.addEventListener("DOMContentLoaded", callback); + } +}; + +/** + * Small JavaScript module for the documentation. + */ +const Documentation = { + init: () => { + Documentation.initDomainIndexTable(); + Documentation.initOnKeyListeners(); + }, + + /** + * i18n support + */ + TRANSLATIONS: {}, + PLURAL_EXPR: (n) => (n === 1 ? 0 : 1), + LOCALE: "unknown", + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext: (string) => { + const translated = Documentation.TRANSLATIONS[string]; + switch (typeof translated) { + case "undefined": + return string; // no translation + case "string": + return translated; // translation exists + default: + return translated[0]; // (singular, plural) translation tuple exists + } + }, + + ngettext: (singular, plural, n) => { + const translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated !== "undefined") + return translated[Documentation.PLURAL_EXPR(n)]; + return n === 1 ? singular : plural; + }, + + addTranslations: (catalog) => { + Object.assign(Documentation.TRANSLATIONS, catalog.messages); + Documentation.PLURAL_EXPR = new Function( + "n", + `return (${catalog.plural_expr})` + ); + Documentation.LOCALE = catalog.locale; + }, + + /** + * helper function to focus on search bar + */ + focusSearchBar: () => { + document.querySelectorAll("input[name=q]")[0]?.focus(); + }, + + /** + * Initialise the domain index toggle buttons + */ + initDomainIndexTable: () => { + const toggler = (el) => { + const idNumber = el.id.substr(7); + const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`); + if (el.src.substr(-9) === "minus.png") { + el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`; + toggledRows.forEach((el) => (el.style.display = "none")); + } else { + el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`; + toggledRows.forEach((el) => (el.style.display = "")); + } + }; + + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); + }, + + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); + } + break; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); + } + break; + } + } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } + }); + }, +}; + +// quick alias for translations +const _ = Documentation.gettext; + +_ready(Documentation.init); diff --git a/_static/documentation_options.js b/_static/documentation_options.js new file mode 100644 index 0000000..dee837d --- /dev/null +++ b/_static/documentation_options.js @@ -0,0 +1,13 @@ +const DOCUMENTATION_OPTIONS = { + VERSION: '1.2.5', + LANGUAGE: 'en', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, +}; \ No newline at end of file diff --git a/_static/file.png b/_static/file.png new file mode 100644 index 0000000000000000000000000000000000000000..a858a410e4faa62ce324d814e4b816fff83a6fb3 GIT binary patch literal 286 zcmV+(0pb3MP)s`hMrGg#P~ix$^RISR_I47Y|r1 z_CyJOe}D1){SET-^Amu_i71Lt6eYfZjRyw@I6OQAIXXHDfiX^GbOlHe=Ae4>0m)d(f|Me07*qoM6N<$f}vM^LjV8( literal 0 HcmV?d00001 diff --git a/_static/language_data.js b/_static/language_data.js new file mode 100644 index 0000000..250f566 --- /dev/null +++ b/_static/language_data.js @@ -0,0 +1,199 @@ +/* + * language_data.js + * ~~~~~~~~~~~~~~~~ + * + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; + + +/* Non-minified version is copied as a separate JS file, is available */ + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + diff --git a/_static/minus.png b/_static/minus.png new file mode 100644 index 0000000000000000000000000000000000000000..d96755fdaf8bb2214971e0db9c1fd3077d7c419d GIT binary patch literal 90 zcmeAS@N?(olHy`uVBq!ia0vp^+#t*WBp7;*Yy1LIik>cxAr*|t7R?Mi>2?kWtu=nj kDsEF_5m^0CR;1wuP-*O&G^0G}KYk!hp00i_>zopr08q^qX#fBK literal 0 HcmV?d00001 diff --git a/_static/plus.png b/_static/plus.png new file mode 100644 index 0000000000000000000000000000000000000000..7107cec93a979b9a5f64843235a16651d563ce2d GIT binary patch literal 90 zcmeAS@N?(olHy`uVBq!ia0vp^+#t*WBp7;*Yy1LIik>cxAr*|t7R?Mi>2?kWtu>-2 m3q%Vub%g%s<8sJhVPMczOq}xhg9DJoz~JfX=d#Wzp$Pyb1r*Kz literal 0 HcmV?d00001 diff --git a/_static/pygments.css b/_static/pygments.css new file mode 100644 index 0000000..c2e07c7 --- /dev/null +++ b/_static/pygments.css @@ -0,0 +1,258 @@ +.highlight pre { line-height: 125%; } +.highlight td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +.highlight span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +.highlight td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #f8f8f8; } +.highlight .c { color: #8f5902; font-style: italic } /* Comment */ +.highlight .err { color: #a40000; border: 1px solid #ef2929 } /* Error */ +.highlight .g { color: #000000 } /* Generic */ +.highlight .k { color: #204a87; font-weight: bold } /* Keyword */ +.highlight .l { color: #000000 } /* Literal */ +.highlight .n { color: #000000 } /* Name */ +.highlight .o { color: #ce5c00; font-weight: bold } /* Operator */ +.highlight .x { color: #000000 } /* Other */ +.highlight .p { color: #000000; font-weight: bold } /* Punctuation */ +.highlight .ch { color: #8f5902; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #8f5902; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #8f5902; font-style: italic } /* Comment.Preproc */ +.highlight .cpf { color: #8f5902; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #8f5902; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #8f5902; font-style: italic } /* Comment.Special */ +.highlight .gd { color: #a40000 } /* Generic.Deleted */ +.highlight .ge { color: #000000; font-style: italic } /* Generic.Emph */ +.highlight .ges { color: #000000; font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #ef2929 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #000000; font-style: italic } /* Generic.Output */ +.highlight .gp { color: #8f5902 } /* Generic.Prompt */ +.highlight .gs { color: #000000; font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #a40000; font-weight: bold } /* Generic.Traceback */ +.highlight .kc { color: #204a87; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #204a87; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #204a87; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #204a87; font-weight: bold } /* Keyword.Pseudo */ +.highlight .kr { color: #204a87; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #204a87; font-weight: bold } /* Keyword.Type */ +.highlight .ld { color: #000000 } /* Literal.Date */ +.highlight .m { color: #0000cf; font-weight: bold } /* Literal.Number */ +.highlight .s { color: #4e9a06 } /* Literal.String */ +.highlight .na { color: #c4a000 } /* Name.Attribute */ +.highlight .nb { color: #204a87 } /* Name.Builtin */ +.highlight .nc { color: #000000 } /* Name.Class */ +.highlight .no { color: #000000 } /* Name.Constant */ +.highlight .nd { color: #5c35cc; font-weight: bold } /* Name.Decorator */ +.highlight .ni { color: #ce5c00 } /* Name.Entity */ +.highlight .ne { color: #cc0000; font-weight: bold } /* Name.Exception */ +.highlight .nf { color: #000000 } /* Name.Function */ +.highlight .nl { color: #f57900 } /* Name.Label */ +.highlight .nn { color: #000000 } /* Name.Namespace */ +.highlight .nx { color: #000000 } /* Name.Other */ +.highlight .py { color: #000000 } /* Name.Property */ +.highlight .nt { color: #204a87; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #000000 } /* Name.Variable */ +.highlight .ow { color: #204a87; font-weight: bold } /* Operator.Word */ +.highlight .pm { color: #000000; font-weight: bold } /* Punctuation.Marker */ +.highlight .w { color: #f8f8f8 } /* Text.Whitespace */ +.highlight .mb { color: #0000cf; font-weight: bold } /* Literal.Number.Bin */ +.highlight .mf { color: #0000cf; font-weight: bold } /* Literal.Number.Float */ +.highlight .mh { color: #0000cf; font-weight: bold } /* Literal.Number.Hex */ +.highlight .mi { color: #0000cf; font-weight: bold } /* Literal.Number.Integer */ +.highlight .mo { color: #0000cf; font-weight: bold } /* Literal.Number.Oct */ +.highlight .sa { color: #4e9a06 } /* Literal.String.Affix */ +.highlight .sb { color: #4e9a06 } /* Literal.String.Backtick */ +.highlight .sc { color: #4e9a06 } /* Literal.String.Char */ +.highlight .dl { color: #4e9a06 } /* Literal.String.Delimiter */ +.highlight .sd { color: #8f5902; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4e9a06 } /* Literal.String.Double */ +.highlight .se { color: #4e9a06 } /* Literal.String.Escape */ +.highlight .sh { color: #4e9a06 } /* Literal.String.Heredoc */ +.highlight .si { color: #4e9a06 } /* Literal.String.Interpol */ +.highlight .sx { color: #4e9a06 } /* Literal.String.Other */ +.highlight .sr { color: #4e9a06 } /* Literal.String.Regex */ +.highlight .s1 { color: #4e9a06 } /* Literal.String.Single */ +.highlight .ss { color: #4e9a06 } /* Literal.String.Symbol */ +.highlight .bp { color: #3465a4 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #000000 } /* Name.Function.Magic */ +.highlight .vc { color: #000000 } /* Name.Variable.Class */ +.highlight .vg { color: #000000 } /* Name.Variable.Global */ +.highlight .vi { color: #000000 } /* Name.Variable.Instance */ +.highlight .vm { color: #000000 } /* Name.Variable.Magic */ +.highlight .il { color: #0000cf; font-weight: bold } /* Literal.Number.Integer.Long */ +@media not print { +body[data-theme="dark"] .highlight pre { line-height: 125%; } +body[data-theme="dark"] .highlight td.linenos .normal { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; } +body[data-theme="dark"] .highlight span.linenos { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; } +body[data-theme="dark"] .highlight td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +body[data-theme="dark"] .highlight span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +body[data-theme="dark"] .highlight .hll { background-color: #404040 } +body[data-theme="dark"] .highlight { background: #202020; color: #d0d0d0 } +body[data-theme="dark"] .highlight .c { color: #ababab; font-style: italic } /* Comment */ +body[data-theme="dark"] .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */ +body[data-theme="dark"] .highlight .esc { color: #d0d0d0 } /* Escape */ +body[data-theme="dark"] .highlight .g { color: #d0d0d0 } /* Generic */ +body[data-theme="dark"] .highlight .k { color: #6ebf26; font-weight: bold } /* Keyword */ +body[data-theme="dark"] .highlight .l { color: #d0d0d0 } /* Literal */ +body[data-theme="dark"] .highlight .n { color: #d0d0d0 } /* Name */ +body[data-theme="dark"] .highlight .o { color: #d0d0d0 } /* Operator */ +body[data-theme="dark"] .highlight .x { color: #d0d0d0 } /* Other */ +body[data-theme="dark"] .highlight .p { color: #d0d0d0 } /* Punctuation */ +body[data-theme="dark"] .highlight .ch { color: #ababab; font-style: italic } /* Comment.Hashbang */ +body[data-theme="dark"] .highlight .cm { color: #ababab; font-style: italic } /* Comment.Multiline */ +body[data-theme="dark"] .highlight .cp { color: #ff3a3a; font-weight: bold } /* Comment.Preproc */ +body[data-theme="dark"] .highlight .cpf { color: #ababab; font-style: italic } /* Comment.PreprocFile */ +body[data-theme="dark"] .highlight .c1 { color: #ababab; font-style: italic } /* Comment.Single */ +body[data-theme="dark"] .highlight .cs { color: #e50808; font-weight: bold; background-color: #520000 } /* Comment.Special */ +body[data-theme="dark"] .highlight .gd { color: #d22323 } /* Generic.Deleted */ +body[data-theme="dark"] .highlight .ge { color: #d0d0d0; font-style: italic } /* Generic.Emph */ +body[data-theme="dark"] .highlight .ges { color: #d0d0d0; font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +body[data-theme="dark"] .highlight .gr { color: #d22323 } /* Generic.Error */ +body[data-theme="dark"] .highlight .gh { color: #ffffff; font-weight: bold } /* Generic.Heading */ +body[data-theme="dark"] .highlight .gi { color: #589819 } /* Generic.Inserted */ +body[data-theme="dark"] .highlight .go { color: #cccccc } /* Generic.Output */ +body[data-theme="dark"] .highlight .gp { color: #aaaaaa } /* Generic.Prompt */ +body[data-theme="dark"] .highlight .gs { color: #d0d0d0; font-weight: bold } /* Generic.Strong */ +body[data-theme="dark"] .highlight .gu { color: #ffffff; text-decoration: underline } /* Generic.Subheading */ +body[data-theme="dark"] .highlight .gt { color: #d22323 } /* Generic.Traceback */ +body[data-theme="dark"] .highlight .kc { color: #6ebf26; font-weight: bold } /* Keyword.Constant */ +body[data-theme="dark"] .highlight .kd { color: #6ebf26; font-weight: bold } /* Keyword.Declaration */ +body[data-theme="dark"] .highlight .kn { color: #6ebf26; font-weight: bold } /* Keyword.Namespace */ +body[data-theme="dark"] .highlight .kp { color: #6ebf26 } /* Keyword.Pseudo */ +body[data-theme="dark"] .highlight .kr { color: #6ebf26; font-weight: bold } /* Keyword.Reserved */ +body[data-theme="dark"] .highlight .kt { color: #6ebf26; font-weight: bold } /* Keyword.Type */ +body[data-theme="dark"] .highlight .ld { color: #d0d0d0 } /* Literal.Date */ +body[data-theme="dark"] .highlight .m { color: #51b2fd } /* Literal.Number */ +body[data-theme="dark"] .highlight .s { color: #ed9d13 } /* Literal.String */ +body[data-theme="dark"] .highlight .na { color: #bbbbbb } /* Name.Attribute */ +body[data-theme="dark"] .highlight .nb { color: #2fbccd } /* Name.Builtin */ +body[data-theme="dark"] .highlight .nc { color: #71adff; text-decoration: underline } /* Name.Class */ +body[data-theme="dark"] .highlight .no { color: #40ffff } /* Name.Constant */ +body[data-theme="dark"] .highlight .nd { color: #ffa500 } /* Name.Decorator */ +body[data-theme="dark"] .highlight .ni { color: #d0d0d0 } /* Name.Entity */ +body[data-theme="dark"] .highlight .ne { color: #bbbbbb } /* Name.Exception */ +body[data-theme="dark"] .highlight .nf { color: #71adff } /* Name.Function */ +body[data-theme="dark"] .highlight .nl { color: #d0d0d0 } /* Name.Label */ +body[data-theme="dark"] .highlight .nn { color: #71adff; text-decoration: underline } /* Name.Namespace */ +body[data-theme="dark"] .highlight .nx { color: #d0d0d0 } /* Name.Other */ +body[data-theme="dark"] .highlight .py { color: #d0d0d0 } /* Name.Property */ +body[data-theme="dark"] .highlight .nt { color: #6ebf26; font-weight: bold } /* Name.Tag */ +body[data-theme="dark"] .highlight .nv { color: #40ffff } /* Name.Variable */ +body[data-theme="dark"] .highlight .ow { color: #6ebf26; font-weight: bold } /* Operator.Word */ +body[data-theme="dark"] .highlight .pm { color: #d0d0d0 } /* Punctuation.Marker */ +body[data-theme="dark"] .highlight .w { color: #666666 } /* Text.Whitespace */ +body[data-theme="dark"] .highlight .mb { color: #51b2fd } /* Literal.Number.Bin */ +body[data-theme="dark"] .highlight .mf { color: #51b2fd } /* Literal.Number.Float */ +body[data-theme="dark"] .highlight .mh { color: #51b2fd } /* Literal.Number.Hex */ +body[data-theme="dark"] .highlight .mi { color: #51b2fd } /* Literal.Number.Integer */ +body[data-theme="dark"] .highlight .mo { color: #51b2fd } /* Literal.Number.Oct */ +body[data-theme="dark"] .highlight .sa { color: #ed9d13 } /* Literal.String.Affix */ +body[data-theme="dark"] .highlight .sb { color: #ed9d13 } /* Literal.String.Backtick */ +body[data-theme="dark"] .highlight .sc { color: #ed9d13 } /* Literal.String.Char */ +body[data-theme="dark"] .highlight .dl { color: #ed9d13 } /* Literal.String.Delimiter */ +body[data-theme="dark"] .highlight .sd { color: #ed9d13 } /* Literal.String.Doc */ +body[data-theme="dark"] .highlight .s2 { color: #ed9d13 } /* Literal.String.Double */ +body[data-theme="dark"] .highlight .se { color: #ed9d13 } /* Literal.String.Escape */ +body[data-theme="dark"] .highlight .sh { color: #ed9d13 } /* Literal.String.Heredoc */ +body[data-theme="dark"] .highlight .si { color: #ed9d13 } /* Literal.String.Interpol */ +body[data-theme="dark"] .highlight .sx { color: #ffa500 } /* Literal.String.Other */ +body[data-theme="dark"] .highlight .sr { color: #ed9d13 } /* Literal.String.Regex */ +body[data-theme="dark"] .highlight .s1 { color: #ed9d13 } /* Literal.String.Single */ +body[data-theme="dark"] .highlight .ss { color: #ed9d13 } /* Literal.String.Symbol */ +body[data-theme="dark"] .highlight .bp { color: #2fbccd } /* Name.Builtin.Pseudo */ +body[data-theme="dark"] .highlight .fm { color: #71adff } /* Name.Function.Magic */ +body[data-theme="dark"] .highlight .vc { color: #40ffff } /* Name.Variable.Class */ +body[data-theme="dark"] .highlight .vg { color: #40ffff } /* Name.Variable.Global */ +body[data-theme="dark"] .highlight .vi { color: #40ffff } /* Name.Variable.Instance */ +body[data-theme="dark"] .highlight .vm { color: #40ffff } /* Name.Variable.Magic */ +body[data-theme="dark"] .highlight .il { color: #51b2fd } /* Literal.Number.Integer.Long */ +@media (prefers-color-scheme: dark) { +body:not([data-theme="light"]) .highlight pre { line-height: 125%; } +body:not([data-theme="light"]) .highlight td.linenos .normal { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; } +body:not([data-theme="light"]) .highlight span.linenos { color: #aaaaaa; background-color: transparent; padding-left: 5px; padding-right: 5px; } +body:not([data-theme="light"]) .highlight td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +body:not([data-theme="light"]) .highlight span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +body:not([data-theme="light"]) .highlight .hll { background-color: #404040 } +body:not([data-theme="light"]) .highlight { background: #202020; color: #d0d0d0 } +body:not([data-theme="light"]) .highlight .c { color: #ababab; font-style: italic } /* Comment */ +body:not([data-theme="light"]) .highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */ +body:not([data-theme="light"]) .highlight .esc { color: #d0d0d0 } /* Escape */ +body:not([data-theme="light"]) .highlight .g { color: #d0d0d0 } /* Generic */ +body:not([data-theme="light"]) .highlight .k { color: #6ebf26; font-weight: bold } /* Keyword */ +body:not([data-theme="light"]) .highlight .l { color: #d0d0d0 } /* Literal */ +body:not([data-theme="light"]) .highlight .n { color: #d0d0d0 } /* Name */ +body:not([data-theme="light"]) .highlight .o { color: #d0d0d0 } /* Operator */ +body:not([data-theme="light"]) .highlight .x { color: #d0d0d0 } /* Other */ +body:not([data-theme="light"]) .highlight .p { color: #d0d0d0 } /* Punctuation */ +body:not([data-theme="light"]) .highlight .ch { color: #ababab; font-style: italic } /* Comment.Hashbang */ +body:not([data-theme="light"]) .highlight .cm { color: #ababab; font-style: italic } /* Comment.Multiline */ +body:not([data-theme="light"]) .highlight .cp { color: #ff3a3a; font-weight: bold } /* Comment.Preproc */ +body:not([data-theme="light"]) .highlight .cpf { color: #ababab; font-style: italic } /* Comment.PreprocFile */ +body:not([data-theme="light"]) .highlight .c1 { color: #ababab; font-style: italic } /* Comment.Single */ +body:not([data-theme="light"]) .highlight .cs { color: #e50808; font-weight: bold; background-color: #520000 } /* Comment.Special */ +body:not([data-theme="light"]) .highlight .gd { color: #d22323 } /* Generic.Deleted */ +body:not([data-theme="light"]) .highlight .ge { color: #d0d0d0; font-style: italic } /* Generic.Emph */ +body:not([data-theme="light"]) .highlight .ges { color: #d0d0d0; font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +body:not([data-theme="light"]) .highlight .gr { color: #d22323 } /* Generic.Error */ +body:not([data-theme="light"]) .highlight .gh { color: #ffffff; font-weight: bold } /* Generic.Heading */ +body:not([data-theme="light"]) .highlight .gi { color: #589819 } /* Generic.Inserted */ +body:not([data-theme="light"]) .highlight .go { color: #cccccc } /* Generic.Output */ +body:not([data-theme="light"]) .highlight .gp { color: #aaaaaa } /* Generic.Prompt */ +body:not([data-theme="light"]) .highlight .gs { color: #d0d0d0; font-weight: bold } /* Generic.Strong */ +body:not([data-theme="light"]) .highlight .gu { color: #ffffff; text-decoration: underline } /* Generic.Subheading */ +body:not([data-theme="light"]) .highlight .gt { color: #d22323 } /* Generic.Traceback */ +body:not([data-theme="light"]) .highlight .kc { color: #6ebf26; font-weight: bold } /* Keyword.Constant */ +body:not([data-theme="light"]) .highlight .kd { color: #6ebf26; font-weight: bold } /* Keyword.Declaration */ +body:not([data-theme="light"]) .highlight .kn { color: #6ebf26; font-weight: bold } /* Keyword.Namespace */ +body:not([data-theme="light"]) .highlight .kp { color: #6ebf26 } /* Keyword.Pseudo */ +body:not([data-theme="light"]) .highlight .kr { color: #6ebf26; font-weight: bold } /* Keyword.Reserved */ +body:not([data-theme="light"]) .highlight .kt { color: #6ebf26; font-weight: bold } /* Keyword.Type */ +body:not([data-theme="light"]) .highlight .ld { color: #d0d0d0 } /* Literal.Date */ +body:not([data-theme="light"]) .highlight .m { color: #51b2fd } /* Literal.Number */ +body:not([data-theme="light"]) .highlight .s { color: #ed9d13 } /* Literal.String */ +body:not([data-theme="light"]) .highlight .na { color: #bbbbbb } /* Name.Attribute */ +body:not([data-theme="light"]) .highlight .nb { color: #2fbccd } /* Name.Builtin */ +body:not([data-theme="light"]) .highlight .nc { color: #71adff; text-decoration: underline } /* Name.Class */ +body:not([data-theme="light"]) .highlight .no { color: #40ffff } /* Name.Constant */ +body:not([data-theme="light"]) .highlight .nd { color: #ffa500 } /* Name.Decorator */ +body:not([data-theme="light"]) .highlight .ni { color: #d0d0d0 } /* Name.Entity */ +body:not([data-theme="light"]) .highlight .ne { color: #bbbbbb } /* Name.Exception */ +body:not([data-theme="light"]) .highlight .nf { color: #71adff } /* Name.Function */ +body:not([data-theme="light"]) .highlight .nl { color: #d0d0d0 } /* Name.Label */ +body:not([data-theme="light"]) .highlight .nn { color: #71adff; text-decoration: underline } /* Name.Namespace */ +body:not([data-theme="light"]) .highlight .nx { color: #d0d0d0 } /* Name.Other */ +body:not([data-theme="light"]) .highlight .py { color: #d0d0d0 } /* Name.Property */ +body:not([data-theme="light"]) .highlight .nt { color: #6ebf26; font-weight: bold } /* Name.Tag */ +body:not([data-theme="light"]) .highlight .nv { color: #40ffff } /* Name.Variable */ +body:not([data-theme="light"]) .highlight .ow { color: #6ebf26; font-weight: bold } /* Operator.Word */ +body:not([data-theme="light"]) .highlight .pm { color: #d0d0d0 } /* Punctuation.Marker */ +body:not([data-theme="light"]) .highlight .w { color: #666666 } /* Text.Whitespace */ +body:not([data-theme="light"]) .highlight .mb { color: #51b2fd } /* Literal.Number.Bin */ +body:not([data-theme="light"]) .highlight .mf { color: #51b2fd } /* Literal.Number.Float */ +body:not([data-theme="light"]) .highlight .mh { color: #51b2fd } /* Literal.Number.Hex */ +body:not([data-theme="light"]) .highlight .mi { color: #51b2fd } /* Literal.Number.Integer */ +body:not([data-theme="light"]) .highlight .mo { color: #51b2fd } /* Literal.Number.Oct */ +body:not([data-theme="light"]) .highlight .sa { color: #ed9d13 } /* Literal.String.Affix */ +body:not([data-theme="light"]) .highlight .sb { color: #ed9d13 } /* Literal.String.Backtick */ +body:not([data-theme="light"]) .highlight .sc { color: #ed9d13 } /* Literal.String.Char */ +body:not([data-theme="light"]) .highlight .dl { color: #ed9d13 } /* Literal.String.Delimiter */ +body:not([data-theme="light"]) .highlight .sd { color: #ed9d13 } /* Literal.String.Doc */ +body:not([data-theme="light"]) .highlight .s2 { color: #ed9d13 } /* Literal.String.Double */ +body:not([data-theme="light"]) .highlight .se { color: #ed9d13 } /* Literal.String.Escape */ +body:not([data-theme="light"]) .highlight .sh { color: #ed9d13 } /* Literal.String.Heredoc */ +body:not([data-theme="light"]) .highlight .si { color: #ed9d13 } /* Literal.String.Interpol */ +body:not([data-theme="light"]) .highlight .sx { color: #ffa500 } /* Literal.String.Other */ +body:not([data-theme="light"]) .highlight .sr { color: #ed9d13 } /* Literal.String.Regex */ +body:not([data-theme="light"]) .highlight .s1 { color: #ed9d13 } /* Literal.String.Single */ +body:not([data-theme="light"]) .highlight .ss { color: #ed9d13 } /* Literal.String.Symbol */ +body:not([data-theme="light"]) .highlight .bp { color: #2fbccd } /* Name.Builtin.Pseudo */ +body:not([data-theme="light"]) .highlight .fm { color: #71adff } /* Name.Function.Magic */ +body:not([data-theme="light"]) .highlight .vc { color: #40ffff } /* Name.Variable.Class */ +body:not([data-theme="light"]) .highlight .vg { color: #40ffff } /* Name.Variable.Global */ +body:not([data-theme="light"]) .highlight .vi { color: #40ffff } /* Name.Variable.Instance */ +body:not([data-theme="light"]) .highlight .vm { color: #40ffff } /* Name.Variable.Magic */ +body:not([data-theme="light"]) .highlight .il { color: #51b2fd } /* Literal.Number.Integer.Long */ +} +} \ No newline at end of file diff --git a/_static/scripts/furo-extensions.js b/_static/scripts/furo-extensions.js new file mode 100644 index 0000000..e69de29 diff --git a/_static/scripts/furo.js b/_static/scripts/furo.js new file mode 100644 index 0000000..32e7c05 --- /dev/null +++ b/_static/scripts/furo.js @@ -0,0 +1,3 @@ +/*! For license information please see furo.js.LICENSE.txt */ +(()=>{var t={212:function(t,e,n){var o,r;r=void 0!==n.g?n.g:"undefined"!=typeof window?window:this,o=function(){return function(t){"use strict";var e={navClass:"active",contentClass:"active",nested:!1,nestedClass:"active",offset:0,reflow:!1,events:!0},n=function(t,e,n){if(n.settings.events){var o=new CustomEvent(t,{bubbles:!0,cancelable:!0,detail:n});e.dispatchEvent(o)}},o=function(t){var e=0;if(t.offsetParent)for(;t;)e+=t.offsetTop,t=t.offsetParent;return e>=0?e:0},r=function(t){t&&t.sort((function(t,e){return o(t.content)=Math.max(document.body.scrollHeight,document.documentElement.scrollHeight,document.body.offsetHeight,document.documentElement.offsetHeight,document.body.clientHeight,document.documentElement.clientHeight)},l=function(t,e){var n=t[t.length-1];if(function(t,e){return!(!s()||!c(t.content,e,!0))}(n,e))return n;for(var o=t.length-1;o>=0;o--)if(c(t[o].content,e))return t[o]},a=function(t,e){if(e.nested&&t.parentNode){var n=t.parentNode.closest("li");n&&(n.classList.remove(e.nestedClass),a(n,e))}},i=function(t,e){if(t){var o=t.nav.closest("li");o&&(o.classList.remove(e.navClass),t.content.classList.remove(e.contentClass),a(o,e),n("gumshoeDeactivate",o,{link:t.nav,content:t.content,settings:e}))}},u=function(t,e){if(e.nested){var n=t.parentNode.closest("li");n&&(n.classList.add(e.nestedClass),u(n,e))}};return function(o,c){var s,a,d,f,m,v={setup:function(){s=document.querySelectorAll(o),a=[],Array.prototype.forEach.call(s,(function(t){var e=document.getElementById(decodeURIComponent(t.hash.substr(1)));e&&a.push({nav:t,content:e})})),r(a)},detect:function(){var t=l(a,m);t?d&&t.content===d.content||(i(d,m),function(t,e){if(t){var o=t.nav.closest("li");o&&(o.classList.add(e.navClass),t.content.classList.add(e.contentClass),u(o,e),n("gumshoeActivate",o,{link:t.nav,content:t.content,settings:e}))}}(t,m),d=t):d&&(i(d,m),d=null)}},h=function(e){f&&t.cancelAnimationFrame(f),f=t.requestAnimationFrame(v.detect)},g=function(e){f&&t.cancelAnimationFrame(f),f=t.requestAnimationFrame((function(){r(a),v.detect()}))};return v.destroy=function(){d&&i(d,m),t.removeEventListener("scroll",h,!1),m.reflow&&t.removeEventListener("resize",g,!1),a=null,s=null,d=null,f=null,m=null},m=function(){var t={};return Array.prototype.forEach.call(arguments,(function(e){for(var n in e){if(!e.hasOwnProperty(n))return;t[n]=e[n]}})),t}(e,c||{}),v.setup(),v.detect(),t.addEventListener("scroll",h,!1),m.reflow&&t.addEventListener("resize",g,!1),v}}(r)}.apply(e,[]),void 0===o||(t.exports=o)}},e={};function n(o){var r=e[o];if(void 0!==r)return r.exports;var c=e[o]={exports:{}};return t[o].call(c.exports,c,c.exports,n),c.exports}n.n=t=>{var e=t&&t.__esModule?()=>t.default:()=>t;return n.d(e,{a:e}),e},n.d=(t,e)=>{for(var o in e)n.o(e,o)&&!n.o(t,o)&&Object.defineProperty(t,o,{enumerable:!0,get:e[o]})},n.g=function(){if("object"==typeof globalThis)return globalThis;try{return this||new Function("return this")()}catch(t){if("object"==typeof window)return window}}(),n.o=(t,e)=>Object.prototype.hasOwnProperty.call(t,e),(()=>{"use strict";var t=n(212),e=n.n(t),o=null,r=null,c=window.pageYOffset||document.documentElement.scrollTop;const s=64;function l(){const t=localStorage.getItem("theme")||"auto";var e;"light"!==(e=window.matchMedia("(prefers-color-scheme: dark)").matches?"auto"===t?"light":"light"==t?"dark":"auto":"auto"===t?"dark":"dark"==t?"light":"auto")&&"dark"!==e&&"auto"!==e&&(console.error(`Got invalid theme mode: ${e}. Resetting to auto.`),e="auto"),document.body.dataset.theme=e,localStorage.setItem("theme",e),console.log(`Changed to ${e} mode.`)}function a(){!function(){const t=document.getElementsByClassName("theme-toggle");Array.from(t).forEach((t=>{t.addEventListener("click",l)}))}(),function(){let t=0,e=!1;window.addEventListener("scroll",(function(n){t=window.scrollY,e||(window.requestAnimationFrame((function(){var n;n=t,0==Math.floor(r.getBoundingClientRect().top)?r.classList.add("scrolled"):r.classList.remove("scrolled"),function(t){tc&&document.documentElement.classList.remove("show-back-to-top"),c=t}(n),function(t){null!==o&&(0==t?o.scrollTo(0,0):Math.ceil(t)>=Math.floor(document.documentElement.scrollHeight-window.innerHeight)?o.scrollTo(0,o.scrollHeight):document.querySelector(".scroll-current"))}(n),e=!1})),e=!0)})),window.scroll()}(),null!==o&&new(e())(".toc-tree a",{reflow:!0,recursive:!0,navClass:"scroll-current",offset:()=>{let t=parseFloat(getComputedStyle(document.documentElement).fontSize);return r.getBoundingClientRect().height+.5*t+1}})}document.addEventListener("DOMContentLoaded",(function(){document.body.parentNode.classList.remove("no-js"),r=document.querySelector("header"),o=document.querySelector(".toc-scroll"),a()}))})()})(); +//# sourceMappingURL=furo.js.map \ No newline at end of file diff --git a/_static/scripts/furo.js.LICENSE.txt b/_static/scripts/furo.js.LICENSE.txt new file mode 100644 index 0000000..1632189 --- /dev/null +++ b/_static/scripts/furo.js.LICENSE.txt @@ -0,0 +1,7 @@ +/*! + * gumshoejs v5.1.2 (patched by @pradyunsg) + * A simple, framework-agnostic scrollspy script. + * (c) 2019 Chris Ferdinandi + * MIT License + * http://github.com/cferdinandi/gumshoe + */ diff --git a/_static/scripts/furo.js.map b/_static/scripts/furo.js.map new file mode 100644 index 0000000..4705302 --- /dev/null +++ b/_static/scripts/furo.js.map @@ -0,0 +1 @@ +{"version":3,"file":"scripts/furo.js","mappings":";iCAAA,MAQWA,SAWS,IAAX,EAAAC,EACH,EAAAA,EACkB,oBAAXC,OACLA,OACAC,KAbO,EAAF,WACP,OAaJ,SAAUD,GACR,aAMA,IAAIE,EAAW,CAEbC,SAAU,SACVC,aAAc,SAGdC,QAAQ,EACRC,YAAa,SAGbC,OAAQ,EACRC,QAAQ,EAGRC,QAAQ,GA6BNC,EAAY,SAAUC,EAAMC,EAAMC,GAEpC,GAAKA,EAAOC,SAASL,OAArB,CAGA,IAAIM,EAAQ,IAAIC,YAAYL,EAAM,CAChCM,SAAS,EACTC,YAAY,EACZL,OAAQA,IAIVD,EAAKO,cAAcJ,EAVgB,CAWrC,EAOIK,EAAe,SAAUR,GAC3B,IAAIS,EAAW,EACf,GAAIT,EAAKU,aACP,KAAOV,GACLS,GAAYT,EAAKW,UACjBX,EAAOA,EAAKU,aAGhB,OAAOD,GAAY,EAAIA,EAAW,CACpC,EAMIG,EAAe,SAAUC,GACvBA,GACFA,EAASC,MAAK,SAAUC,EAAOC,GAG7B,OAFcR,EAAaO,EAAME,SACnBT,EAAaQ,EAAMC,UACF,EACxB,CACT,GAEJ,EAwCIC,EAAW,SAAUlB,EAAME,EAAUiB,GACvC,IAAIC,EAASpB,EAAKqB,wBACd1B,EAnCU,SAAUO,GAExB,MAA+B,mBAApBA,EAASP,OACX2B,WAAWpB,EAASP,UAItB2B,WAAWpB,EAASP,OAC7B,CA2Be4B,CAAUrB,GACvB,OAAIiB,EAEAK,SAASJ,EAAOD,OAAQ,KACvB/B,EAAOqC,aAAeC,SAASC,gBAAgBC,cAG7CJ,SAASJ,EAAOS,IAAK,KAAOlC,CACrC,EAMImC,EAAa,WACf,OACEC,KAAKC,KAAK5C,EAAOqC,YAAcrC,EAAO6C,cAnCjCF,KAAKG,IACVR,SAASS,KAAKC,aACdV,SAASC,gBAAgBS,aACzBV,SAASS,KAAKE,aACdX,SAASC,gBAAgBU,aACzBX,SAASS,KAAKP,aACdF,SAASC,gBAAgBC,aAkC7B,EAmBIU,EAAY,SAAUzB,EAAUX,GAClC,IAAIqC,EAAO1B,EAASA,EAAS2B,OAAS,GACtC,GAbgB,SAAUC,EAAMvC,GAChC,SAAI4B,MAAgBZ,EAASuB,EAAKxB,QAASf,GAAU,GAEvD,CAUMwC,CAAYH,EAAMrC,GAAW,OAAOqC,EACxC,IAAK,IAAII,EAAI9B,EAAS2B,OAAS,EAAGG,GAAK,EAAGA,IACxC,GAAIzB,EAASL,EAAS8B,GAAG1B,QAASf,GAAW,OAAOW,EAAS8B,EAEjE,EAOIC,EAAmB,SAAUC,EAAK3C,GAEpC,GAAKA,EAAST,QAAWoD,EAAIC,WAA7B,CAGA,IAAIC,EAAKF,EAAIC,WAAWE,QAAQ,MAC3BD,IAGLA,EAAGE,UAAUC,OAAOhD,EAASR,aAG7BkD,EAAiBG,EAAI7C,GAV0B,CAWjD,EAOIiD,EAAa,SAAUC,EAAOlD,GAEhC,GAAKkD,EAAL,CAGA,IAAIL,EAAKK,EAAMP,IAAIG,QAAQ,MACtBD,IAGLA,EAAGE,UAAUC,OAAOhD,EAASX,UAC7B6D,EAAMnC,QAAQgC,UAAUC,OAAOhD,EAASV,cAGxCoD,EAAiBG,EAAI7C,GAGrBJ,EAAU,oBAAqBiD,EAAI,CACjCM,KAAMD,EAAMP,IACZ5B,QAASmC,EAAMnC,QACff,SAAUA,IAjBM,CAmBpB,EAOIoD,EAAiB,SAAUT,EAAK3C,GAElC,GAAKA,EAAST,OAAd,CAGA,IAAIsD,EAAKF,EAAIC,WAAWE,QAAQ,MAC3BD,IAGLA,EAAGE,UAAUM,IAAIrD,EAASR,aAG1B4D,EAAeP,EAAI7C,GAVS,CAW9B,EA6LA,OA1JkB,SAAUsD,EAAUC,GAKpC,IACIC,EAAU7C,EAAU8C,EAASC,EAAS1D,EADtC2D,EAAa,CAUjBA,MAAmB,WAEjBH,EAAWhC,SAASoC,iBAAiBN,GAGrC3C,EAAW,GAGXkD,MAAMC,UAAUC,QAAQC,KAAKR,GAAU,SAAUjB,GAE/C,IAAIxB,EAAUS,SAASyC,eACrBC,mBAAmB3B,EAAK4B,KAAKC,OAAO,KAEjCrD,GAGLJ,EAAS0D,KAAK,CACZ1B,IAAKJ,EACLxB,QAASA,GAEb,IAGAL,EAAaC,EACf,EAKAgD,OAAoB,WAElB,IAAIW,EAASlC,EAAUzB,EAAUX,GAG5BsE,EASDb,GAAWa,EAAOvD,UAAY0C,EAAQ1C,UAG1CkC,EAAWQ,EAASzD,GAzFT,SAAUkD,EAAOlD,GAE9B,GAAKkD,EAAL,CAGA,IAAIL,EAAKK,EAAMP,IAAIG,QAAQ,MACtBD,IAGLA,EAAGE,UAAUM,IAAIrD,EAASX,UAC1B6D,EAAMnC,QAAQgC,UAAUM,IAAIrD,EAASV,cAGrC8D,EAAeP,EAAI7C,GAGnBJ,EAAU,kBAAmBiD,EAAI,CAC/BM,KAAMD,EAAMP,IACZ5B,QAASmC,EAAMnC,QACff,SAAUA,IAjBM,CAmBpB,CAqEIuE,CAASD,EAAQtE,GAGjByD,EAAUa,GAfJb,IACFR,EAAWQ,EAASzD,GACpByD,EAAU,KAchB,GAMIe,EAAgB,SAAUvE,GAExByD,GACFxE,EAAOuF,qBAAqBf,GAI9BA,EAAUxE,EAAOwF,sBAAsBf,EAAWgB,OACpD,EAMIC,EAAgB,SAAU3E,GAExByD,GACFxE,EAAOuF,qBAAqBf,GAI9BA,EAAUxE,EAAOwF,uBAAsB,WACrChE,EAAaC,GACbgD,EAAWgB,QACb,GACF,EAkDA,OA7CAhB,EAAWkB,QAAU,WAEfpB,GACFR,EAAWQ,EAASzD,GAItBd,EAAO4F,oBAAoB,SAAUN,GAAe,GAChDxE,EAASN,QACXR,EAAO4F,oBAAoB,SAAUF,GAAe,GAItDjE,EAAW,KACX6C,EAAW,KACXC,EAAU,KACVC,EAAU,KACV1D,EAAW,IACb,EAOEA,EA3XS,WACX,IAAI+E,EAAS,CAAC,EAOd,OANAlB,MAAMC,UAAUC,QAAQC,KAAKgB,WAAW,SAAUC,GAChD,IAAK,IAAIC,KAAOD,EAAK,CACnB,IAAKA,EAAIE,eAAeD,GAAM,OAC9BH,EAAOG,GAAOD,EAAIC,EACpB,CACF,IACOH,CACT,CAkXeK,CAAOhG,EAAUmE,GAAW,CAAC,GAGxCI,EAAW0B,QAGX1B,EAAWgB,SAGXzF,EAAOoG,iBAAiB,SAAUd,GAAe,GAC7CxE,EAASN,QACXR,EAAOoG,iBAAiB,SAAUV,GAAe,GAS9CjB,CACT,CAOF,CArcW4B,CAAQvG,EAChB,UAFM,SAEN,uBCXDwG,EAA2B,CAAC,EAGhC,SAASC,EAAoBC,GAE5B,IAAIC,EAAeH,EAAyBE,GAC5C,QAAqBE,IAAjBD,EACH,OAAOA,EAAaE,QAGrB,IAAIC,EAASN,EAAyBE,GAAY,CAGjDG,QAAS,CAAC,GAOX,OAHAE,EAAoBL,GAAU1B,KAAK8B,EAAOD,QAASC,EAAQA,EAAOD,QAASJ,GAGpEK,EAAOD,OACf,CCrBAJ,EAAoBO,EAAKF,IACxB,IAAIG,EAASH,GAAUA,EAAOI,WAC7B,IAAOJ,EAAiB,QACxB,IAAM,EAEP,OADAL,EAAoBU,EAAEF,EAAQ,CAAEG,EAAGH,IAC5BA,CAAM,ECLdR,EAAoBU,EAAI,CAACN,EAASQ,KACjC,IAAI,IAAInB,KAAOmB,EACXZ,EAAoBa,EAAED,EAAYnB,KAASO,EAAoBa,EAAET,EAASX,IAC5EqB,OAAOC,eAAeX,EAASX,EAAK,CAAEuB,YAAY,EAAMC,IAAKL,EAAWnB,IAE1E,ECNDO,EAAoBxG,EAAI,WACvB,GAA0B,iBAAf0H,WAAyB,OAAOA,WAC3C,IACC,OAAOxH,MAAQ,IAAIyH,SAAS,cAAb,EAChB,CAAE,MAAOC,GACR,GAAsB,iBAAX3H,OAAqB,OAAOA,MACxC,CACA,CAPuB,GCAxBuG,EAAoBa,EAAI,CAACrB,EAAK6B,IAAUP,OAAOzC,UAAUqB,eAAenB,KAAKiB,EAAK6B,4CCK9EC,EAAY,KACZC,EAAS,KACTC,EAAgB/H,OAAO6C,aAAeP,SAASC,gBAAgByF,UACnE,MAAMC,EAAmB,GA2EzB,SAASC,IACP,MAAMC,EAAeC,aAAaC,QAAQ,UAAY,OAZxD,IAAkBC,EACH,WADGA,EAaItI,OAAOuI,WAAW,gCAAgCC,QAI/C,SAAjBL,EACO,QACgB,SAAhBA,EACA,OAEA,OAIU,SAAjBA,EACO,OACgB,QAAhBA,EACA,QAEA,SA9BoB,SAATG,GAA4B,SAATA,IACzCG,QAAQC,MAAM,2BAA2BJ,yBACzCA,EAAO,QAGThG,SAASS,KAAK4F,QAAQC,MAAQN,EAC9BF,aAAaS,QAAQ,QAASP,GAC9BG,QAAQK,IAAI,cAAcR,UA0B5B,CAkDA,SAASnC,KART,WAEE,MAAM4C,EAAUzG,SAAS0G,uBAAuB,gBAChDrE,MAAMsE,KAAKF,GAASlE,SAASqE,IAC3BA,EAAI9C,iBAAiB,QAAS8B,EAAe,GAEjD,CAGEiB,GA9CF,WAEE,IAAIC,EAA6B,EAC7BC,GAAU,EAEdrJ,OAAOoG,iBAAiB,UAAU,SAAUuB,GAC1CyB,EAA6BpJ,OAAOsJ,QAE/BD,IACHrJ,OAAOwF,uBAAsB,WAzDnC,IAAuB+D,IA0DDH,EA9GkC,GAAlDzG,KAAK6G,MAAM1B,EAAO7F,wBAAwBQ,KAC5CqF,EAAOjE,UAAUM,IAAI,YAErB2D,EAAOjE,UAAUC,OAAO,YAI5B,SAAmCyF,GAC7BA,EAAYtB,EACd3F,SAASC,gBAAgBsB,UAAUC,OAAO,oBAEtCyF,EAAYxB,EACdzF,SAASC,gBAAgBsB,UAAUM,IAAI,oBAC9BoF,EAAYxB,GACrBzF,SAASC,gBAAgBsB,UAAUC,OAAO,oBAG9CiE,EAAgBwB,CAClB,CAoCEE,CAA0BF,GAlC5B,SAA6BA,GACT,OAAd1B,IAKa,GAAb0B,EACF1B,EAAU6B,SAAS,EAAG,GAGtB/G,KAAKC,KAAK2G,IACV5G,KAAK6G,MAAMlH,SAASC,gBAAgBS,aAAehD,OAAOqC,aAE1DwF,EAAU6B,SAAS,EAAG7B,EAAU7E,cAGhBV,SAASqH,cAAc,mBAc3C,CAKEC,CAAoBL,GAwDdF,GAAU,CACZ,IAEAA,GAAU,EAEd,IACArJ,OAAO6J,QACT,CA6BEC,GA1BkB,OAAdjC,GAKJ,IAAI,IAAJ,CAAY,cAAe,CACzBrH,QAAQ,EACRuJ,WAAW,EACX5J,SAAU,iBACVI,OAAQ,KACN,IAAIyJ,EAAM9H,WAAW+H,iBAAiB3H,SAASC,iBAAiB2H,UAChE,OAAOpC,EAAO7F,wBAAwBkI,OAAS,GAAMH,EAAM,CAAC,GAiBlE,CAcA1H,SAAS8D,iBAAiB,oBAT1B,WACE9D,SAASS,KAAKW,WAAWG,UAAUC,OAAO,SAE1CgE,EAASxF,SAASqH,cAAc,UAChC9B,EAAYvF,SAASqH,cAAc,eAEnCxD,GACF","sources":["webpack:///./src/furo/assets/scripts/gumshoe-patched.js","webpack:///webpack/bootstrap","webpack:///webpack/runtime/compat get default export","webpack:///webpack/runtime/define property getters","webpack:///webpack/runtime/global","webpack:///webpack/runtime/hasOwnProperty shorthand","webpack:///./src/furo/assets/scripts/furo.js"],"sourcesContent":["/*!\n * gumshoejs v5.1.2 (patched by @pradyunsg)\n * A simple, framework-agnostic scrollspy script.\n * (c) 2019 Chris Ferdinandi\n * MIT License\n * http://github.com/cferdinandi/gumshoe\n */\n\n(function (root, factory) {\n if (typeof define === \"function\" && define.amd) {\n define([], function () {\n return factory(root);\n });\n } else if (typeof exports === \"object\") {\n module.exports = factory(root);\n } else {\n root.Gumshoe = factory(root);\n }\n})(\n typeof global !== \"undefined\"\n ? global\n : typeof window !== \"undefined\"\n ? window\n : this,\n function (window) {\n \"use strict\";\n\n //\n // Defaults\n //\n\n var defaults = {\n // Active classes\n navClass: \"active\",\n contentClass: \"active\",\n\n // Nested navigation\n nested: false,\n nestedClass: \"active\",\n\n // Offset & reflow\n offset: 0,\n reflow: false,\n\n // Event support\n events: true,\n };\n\n //\n // Methods\n //\n\n /**\n * Merge two or more objects together.\n * @param {Object} objects The objects to merge together\n * @returns {Object} Merged values of defaults and options\n */\n var extend = function () {\n var merged = {};\n Array.prototype.forEach.call(arguments, function (obj) {\n for (var key in obj) {\n if (!obj.hasOwnProperty(key)) return;\n merged[key] = obj[key];\n }\n });\n return merged;\n };\n\n /**\n * Emit a custom event\n * @param {String} type The event type\n * @param {Node} elem The element to attach the event to\n * @param {Object} detail Any details to pass along with the event\n */\n var emitEvent = function (type, elem, detail) {\n // Make sure events are enabled\n if (!detail.settings.events) return;\n\n // Create a new event\n var event = new CustomEvent(type, {\n bubbles: true,\n cancelable: true,\n detail: detail,\n });\n\n // Dispatch the event\n elem.dispatchEvent(event);\n };\n\n /**\n * Get an element's distance from the top of the Document.\n * @param {Node} elem The element\n * @return {Number} Distance from the top in pixels\n */\n var getOffsetTop = function (elem) {\n var location = 0;\n if (elem.offsetParent) {\n while (elem) {\n location += elem.offsetTop;\n elem = elem.offsetParent;\n }\n }\n return location >= 0 ? location : 0;\n };\n\n /**\n * Sort content from first to last in the DOM\n * @param {Array} contents The content areas\n */\n var sortContents = function (contents) {\n if (contents) {\n contents.sort(function (item1, item2) {\n var offset1 = getOffsetTop(item1.content);\n var offset2 = getOffsetTop(item2.content);\n if (offset1 < offset2) return -1;\n return 1;\n });\n }\n };\n\n /**\n * Get the offset to use for calculating position\n * @param {Object} settings The settings for this instantiation\n * @return {Float} The number of pixels to offset the calculations\n */\n var getOffset = function (settings) {\n // if the offset is a function run it\n if (typeof settings.offset === \"function\") {\n return parseFloat(settings.offset());\n }\n\n // Otherwise, return it as-is\n return parseFloat(settings.offset);\n };\n\n /**\n * Get the document element's height\n * @private\n * @returns {Number}\n */\n var getDocumentHeight = function () {\n return Math.max(\n document.body.scrollHeight,\n document.documentElement.scrollHeight,\n document.body.offsetHeight,\n document.documentElement.offsetHeight,\n document.body.clientHeight,\n document.documentElement.clientHeight,\n );\n };\n\n /**\n * Determine if an element is in view\n * @param {Node} elem The element\n * @param {Object} settings The settings for this instantiation\n * @param {Boolean} bottom If true, check if element is above bottom of viewport instead\n * @return {Boolean} Returns true if element is in the viewport\n */\n var isInView = function (elem, settings, bottom) {\n var bounds = elem.getBoundingClientRect();\n var offset = getOffset(settings);\n if (bottom) {\n return (\n parseInt(bounds.bottom, 10) <\n (window.innerHeight || document.documentElement.clientHeight)\n );\n }\n return parseInt(bounds.top, 10) <= offset;\n };\n\n /**\n * Check if at the bottom of the viewport\n * @return {Boolean} If true, page is at the bottom of the viewport\n */\n var isAtBottom = function () {\n if (\n Math.ceil(window.innerHeight + window.pageYOffset) >=\n getDocumentHeight()\n )\n return true;\n return false;\n };\n\n /**\n * Check if the last item should be used (even if not at the top of the page)\n * @param {Object} item The last item\n * @param {Object} settings The settings for this instantiation\n * @return {Boolean} If true, use the last item\n */\n var useLastItem = function (item, settings) {\n if (isAtBottom() && isInView(item.content, settings, true)) return true;\n return false;\n };\n\n /**\n * Get the active content\n * @param {Array} contents The content areas\n * @param {Object} settings The settings for this instantiation\n * @return {Object} The content area and matching navigation link\n */\n var getActive = function (contents, settings) {\n var last = contents[contents.length - 1];\n if (useLastItem(last, settings)) return last;\n for (var i = contents.length - 1; i >= 0; i--) {\n if (isInView(contents[i].content, settings)) return contents[i];\n }\n };\n\n /**\n * Deactivate parent navs in a nested navigation\n * @param {Node} nav The starting navigation element\n * @param {Object} settings The settings for this instantiation\n */\n var deactivateNested = function (nav, settings) {\n // If nesting isn't activated, bail\n if (!settings.nested || !nav.parentNode) return;\n\n // Get the parent navigation\n var li = nav.parentNode.closest(\"li\");\n if (!li) return;\n\n // Remove the active class\n li.classList.remove(settings.nestedClass);\n\n // Apply recursively to any parent navigation elements\n deactivateNested(li, settings);\n };\n\n /**\n * Deactivate a nav and content area\n * @param {Object} items The nav item and content to deactivate\n * @param {Object} settings The settings for this instantiation\n */\n var deactivate = function (items, settings) {\n // Make sure there are items to deactivate\n if (!items) return;\n\n // Get the parent list item\n var li = items.nav.closest(\"li\");\n if (!li) return;\n\n // Remove the active class from the nav and content\n li.classList.remove(settings.navClass);\n items.content.classList.remove(settings.contentClass);\n\n // Deactivate any parent navs in a nested navigation\n deactivateNested(li, settings);\n\n // Emit a custom event\n emitEvent(\"gumshoeDeactivate\", li, {\n link: items.nav,\n content: items.content,\n settings: settings,\n });\n };\n\n /**\n * Activate parent navs in a nested navigation\n * @param {Node} nav The starting navigation element\n * @param {Object} settings The settings for this instantiation\n */\n var activateNested = function (nav, settings) {\n // If nesting isn't activated, bail\n if (!settings.nested) return;\n\n // Get the parent navigation\n var li = nav.parentNode.closest(\"li\");\n if (!li) return;\n\n // Add the active class\n li.classList.add(settings.nestedClass);\n\n // Apply recursively to any parent navigation elements\n activateNested(li, settings);\n };\n\n /**\n * Activate a nav and content area\n * @param {Object} items The nav item and content to activate\n * @param {Object} settings The settings for this instantiation\n */\n var activate = function (items, settings) {\n // Make sure there are items to activate\n if (!items) return;\n\n // Get the parent list item\n var li = items.nav.closest(\"li\");\n if (!li) return;\n\n // Add the active class to the nav and content\n li.classList.add(settings.navClass);\n items.content.classList.add(settings.contentClass);\n\n // Activate any parent navs in a nested navigation\n activateNested(li, settings);\n\n // Emit a custom event\n emitEvent(\"gumshoeActivate\", li, {\n link: items.nav,\n content: items.content,\n settings: settings,\n });\n };\n\n /**\n * Create the Constructor object\n * @param {String} selector The selector to use for navigation items\n * @param {Object} options User options and settings\n */\n var Constructor = function (selector, options) {\n //\n // Variables\n //\n\n var publicAPIs = {};\n var navItems, contents, current, timeout, settings;\n\n //\n // Methods\n //\n\n /**\n * Set variables from DOM elements\n */\n publicAPIs.setup = function () {\n // Get all nav items\n navItems = document.querySelectorAll(selector);\n\n // Create contents array\n contents = [];\n\n // Loop through each item, get it's matching content, and push to the array\n Array.prototype.forEach.call(navItems, function (item) {\n // Get the content for the nav item\n var content = document.getElementById(\n decodeURIComponent(item.hash.substr(1)),\n );\n if (!content) return;\n\n // Push to the contents array\n contents.push({\n nav: item,\n content: content,\n });\n });\n\n // Sort contents by the order they appear in the DOM\n sortContents(contents);\n };\n\n /**\n * Detect which content is currently active\n */\n publicAPIs.detect = function () {\n // Get the active content\n var active = getActive(contents, settings);\n\n // if there's no active content, deactivate and bail\n if (!active) {\n if (current) {\n deactivate(current, settings);\n current = null;\n }\n return;\n }\n\n // If the active content is the one currently active, do nothing\n if (current && active.content === current.content) return;\n\n // Deactivate the current content and activate the new content\n deactivate(current, settings);\n activate(active, settings);\n\n // Update the currently active content\n current = active;\n };\n\n /**\n * Detect the active content on scroll\n * Debounced for performance\n */\n var scrollHandler = function (event) {\n // If there's a timer, cancel it\n if (timeout) {\n window.cancelAnimationFrame(timeout);\n }\n\n // Setup debounce callback\n timeout = window.requestAnimationFrame(publicAPIs.detect);\n };\n\n /**\n * Update content sorting on resize\n * Debounced for performance\n */\n var resizeHandler = function (event) {\n // If there's a timer, cancel it\n if (timeout) {\n window.cancelAnimationFrame(timeout);\n }\n\n // Setup debounce callback\n timeout = window.requestAnimationFrame(function () {\n sortContents(contents);\n publicAPIs.detect();\n });\n };\n\n /**\n * Destroy the current instantiation\n */\n publicAPIs.destroy = function () {\n // Undo DOM changes\n if (current) {\n deactivate(current, settings);\n }\n\n // Remove event listeners\n window.removeEventListener(\"scroll\", scrollHandler, false);\n if (settings.reflow) {\n window.removeEventListener(\"resize\", resizeHandler, false);\n }\n\n // Reset variables\n contents = null;\n navItems = null;\n current = null;\n timeout = null;\n settings = null;\n };\n\n /**\n * Initialize the current instantiation\n */\n var init = function () {\n // Merge user options into defaults\n settings = extend(defaults, options || {});\n\n // Setup variables based on the current DOM\n publicAPIs.setup();\n\n // Find the currently active content\n publicAPIs.detect();\n\n // Setup event listeners\n window.addEventListener(\"scroll\", scrollHandler, false);\n if (settings.reflow) {\n window.addEventListener(\"resize\", resizeHandler, false);\n }\n };\n\n //\n // Initialize and return the public APIs\n //\n\n init();\n return publicAPIs;\n };\n\n //\n // Return the Constructor\n //\n\n return Constructor;\n },\n);\n","// The module cache\nvar __webpack_module_cache__ = {};\n\n// The require function\nfunction __webpack_require__(moduleId) {\n\t// Check if module is in cache\n\tvar cachedModule = __webpack_module_cache__[moduleId];\n\tif (cachedModule !== undefined) {\n\t\treturn cachedModule.exports;\n\t}\n\t// Create a new module (and put it into the cache)\n\tvar module = __webpack_module_cache__[moduleId] = {\n\t\t// no module.id needed\n\t\t// no module.loaded needed\n\t\texports: {}\n\t};\n\n\t// Execute the module function\n\t__webpack_modules__[moduleId].call(module.exports, module, module.exports, __webpack_require__);\n\n\t// Return the exports of the module\n\treturn module.exports;\n}\n\n","// getDefaultExport function for compatibility with non-harmony modules\n__webpack_require__.n = (module) => {\n\tvar getter = module && module.__esModule ?\n\t\t() => (module['default']) :\n\t\t() => (module);\n\t__webpack_require__.d(getter, { a: getter });\n\treturn getter;\n};","// define getter functions for harmony exports\n__webpack_require__.d = (exports, definition) => {\n\tfor(var key in definition) {\n\t\tif(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n\t\t\tObject.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n\t\t}\n\t}\n};","__webpack_require__.g = (function() {\n\tif (typeof globalThis === 'object') return globalThis;\n\ttry {\n\t\treturn this || new Function('return this')();\n\t} catch (e) {\n\t\tif (typeof window === 'object') return window;\n\t}\n})();","__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))","import Gumshoe from \"./gumshoe-patched.js\";\n\n////////////////////////////////////////////////////////////////////////////////\n// Scroll Handling\n////////////////////////////////////////////////////////////////////////////////\nvar tocScroll = null;\nvar header = null;\nvar lastScrollTop = window.pageYOffset || document.documentElement.scrollTop;\nconst GO_TO_TOP_OFFSET = 64;\n\nfunction scrollHandlerForHeader() {\n if (Math.floor(header.getBoundingClientRect().top) == 0) {\n header.classList.add(\"scrolled\");\n } else {\n header.classList.remove(\"scrolled\");\n }\n}\n\nfunction scrollHandlerForBackToTop(positionY) {\n if (positionY < GO_TO_TOP_OFFSET) {\n document.documentElement.classList.remove(\"show-back-to-top\");\n } else {\n if (positionY < lastScrollTop) {\n document.documentElement.classList.add(\"show-back-to-top\");\n } else if (positionY > lastScrollTop) {\n document.documentElement.classList.remove(\"show-back-to-top\");\n }\n }\n lastScrollTop = positionY;\n}\n\nfunction scrollHandlerForTOC(positionY) {\n if (tocScroll === null) {\n return;\n }\n\n // top of page.\n if (positionY == 0) {\n tocScroll.scrollTo(0, 0);\n } else if (\n // bottom of page.\n Math.ceil(positionY) >=\n Math.floor(document.documentElement.scrollHeight - window.innerHeight)\n ) {\n tocScroll.scrollTo(0, tocScroll.scrollHeight);\n } else {\n // somewhere in the middle.\n const current = document.querySelector(\".scroll-current\");\n if (current == null) {\n return;\n }\n\n // https://github.com/pypa/pip/issues/9159 This breaks scroll behaviours.\n // // scroll the currently \"active\" heading in toc, into view.\n // const rect = current.getBoundingClientRect();\n // if (0 > rect.top) {\n // current.scrollIntoView(true); // the argument is \"alignTop\"\n // } else if (rect.bottom > window.innerHeight) {\n // current.scrollIntoView(false);\n // }\n }\n}\n\nfunction scrollHandler(positionY) {\n scrollHandlerForHeader();\n scrollHandlerForBackToTop(positionY);\n scrollHandlerForTOC(positionY);\n}\n\n////////////////////////////////////////////////////////////////////////////////\n// Theme Toggle\n////////////////////////////////////////////////////////////////////////////////\nfunction setTheme(mode) {\n if (mode !== \"light\" && mode !== \"dark\" && mode !== \"auto\") {\n console.error(`Got invalid theme mode: ${mode}. Resetting to auto.`);\n mode = \"auto\";\n }\n\n document.body.dataset.theme = mode;\n localStorage.setItem(\"theme\", mode);\n console.log(`Changed to ${mode} mode.`);\n}\n\nfunction cycleThemeOnce() {\n const currentTheme = localStorage.getItem(\"theme\") || \"auto\";\n const prefersDark = window.matchMedia(\"(prefers-color-scheme: dark)\").matches;\n\n if (prefersDark) {\n // Auto (dark) -> Light -> Dark\n if (currentTheme === \"auto\") {\n setTheme(\"light\");\n } else if (currentTheme == \"light\") {\n setTheme(\"dark\");\n } else {\n setTheme(\"auto\");\n }\n } else {\n // Auto (light) -> Dark -> Light\n if (currentTheme === \"auto\") {\n setTheme(\"dark\");\n } else if (currentTheme == \"dark\") {\n setTheme(\"light\");\n } else {\n setTheme(\"auto\");\n }\n }\n}\n\n////////////////////////////////////////////////////////////////////////////////\n// Setup\n////////////////////////////////////////////////////////////////////////////////\nfunction setupScrollHandler() {\n // Taken from https://developer.mozilla.org/en-US/docs/Web/API/Document/scroll_event\n let last_known_scroll_position = 0;\n let ticking = false;\n\n window.addEventListener(\"scroll\", function (e) {\n last_known_scroll_position = window.scrollY;\n\n if (!ticking) {\n window.requestAnimationFrame(function () {\n scrollHandler(last_known_scroll_position);\n ticking = false;\n });\n\n ticking = true;\n }\n });\n window.scroll();\n}\n\nfunction setupScrollSpy() {\n if (tocScroll === null) {\n return;\n }\n\n // Scrollspy -- highlight table on contents, based on scroll\n new Gumshoe(\".toc-tree a\", {\n reflow: true,\n recursive: true,\n navClass: \"scroll-current\",\n offset: () => {\n let rem = parseFloat(getComputedStyle(document.documentElement).fontSize);\n return header.getBoundingClientRect().height + 0.5 * rem + 1;\n },\n });\n}\n\nfunction setupTheme() {\n // Attach event handlers for toggling themes\n const buttons = document.getElementsByClassName(\"theme-toggle\");\n Array.from(buttons).forEach((btn) => {\n btn.addEventListener(\"click\", cycleThemeOnce);\n });\n}\n\nfunction setup() {\n setupTheme();\n setupScrollHandler();\n setupScrollSpy();\n}\n\n////////////////////////////////////////////////////////////////////////////////\n// Main entrypoint\n////////////////////////////////////////////////////////////////////////////////\nfunction main() {\n document.body.parentNode.classList.remove(\"no-js\");\n\n header = document.querySelector(\"header\");\n tocScroll = document.querySelector(\".toc-scroll\");\n\n setup();\n}\n\ndocument.addEventListener(\"DOMContentLoaded\", main);\n"],"names":["root","g","window","this","defaults","navClass","contentClass","nested","nestedClass","offset","reflow","events","emitEvent","type","elem","detail","settings","event","CustomEvent","bubbles","cancelable","dispatchEvent","getOffsetTop","location","offsetParent","offsetTop","sortContents","contents","sort","item1","item2","content","isInView","bottom","bounds","getBoundingClientRect","parseFloat","getOffset","parseInt","innerHeight","document","documentElement","clientHeight","top","isAtBottom","Math","ceil","pageYOffset","max","body","scrollHeight","offsetHeight","getActive","last","length","item","useLastItem","i","deactivateNested","nav","parentNode","li","closest","classList","remove","deactivate","items","link","activateNested","add","selector","options","navItems","current","timeout","publicAPIs","querySelectorAll","Array","prototype","forEach","call","getElementById","decodeURIComponent","hash","substr","push","active","activate","scrollHandler","cancelAnimationFrame","requestAnimationFrame","detect","resizeHandler","destroy","removeEventListener","merged","arguments","obj","key","hasOwnProperty","extend","setup","addEventListener","factory","__webpack_module_cache__","__webpack_require__","moduleId","cachedModule","undefined","exports","module","__webpack_modules__","n","getter","__esModule","d","a","definition","o","Object","defineProperty","enumerable","get","globalThis","Function","e","prop","tocScroll","header","lastScrollTop","scrollTop","GO_TO_TOP_OFFSET","cycleThemeOnce","currentTheme","localStorage","getItem","mode","matchMedia","matches","console","error","dataset","theme","setItem","log","buttons","getElementsByClassName","from","btn","setupTheme","last_known_scroll_position","ticking","scrollY","positionY","floor","scrollHandlerForBackToTop","scrollTo","querySelector","scrollHandlerForTOC","scroll","setupScrollHandler","recursive","rem","getComputedStyle","fontSize","height"],"sourceRoot":""} \ No newline at end of file diff --git a/_static/searchtools.js b/_static/searchtools.js new file mode 100644 index 0000000..7918c3f --- /dev/null +++ b/_static/searchtools.js @@ -0,0 +1,574 @@ +/* + * searchtools.js + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for the full-text search. + * + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ +"use strict"; + +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [docname, title, anchor, descr, score, filename] + // and returns the new score. + /* + score: result => { + const [docname, title, anchor, descr, score, filename] = result + return score + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename] = item; + + let listItem = document.createElement("li"); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; + } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = _( + `Search finished, found ${resultCount} page(s) matching the search query.` + ); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings +} + +/** + * Search Module + */ +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() }); + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent !== undefined) return docContent.textContent; + console.warn( + "Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template." + ); + return ""; + }, + + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); + }, + + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), + + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); + } + }, + + hasIndex: () => Search._index !== null, + + deferQuery: (query) => (Search._queued_query = query), + + stopPulse: () => (Search._pulse_status = -1), + + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { + Search._pulse_status = (Search._pulse_status + 1) % 4; + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: (query) => { + // create the required interface elements + const searchText = document.createElement("h2"); + searchText.textContent = _("Searching"); + const searchSummary = document.createElement("p"); + searchSummary.classList.add("search-summary"); + searchSummary.innerText = ""; + const searchList = document.createElement("ul"); + searchList.classList.add("search"); + + const out = document.getElementById("search-results"); + Search.title = out.appendChild(searchText); + Search.dots = Search.title.appendChild(document.createElement("span")); + Search.status = out.appendChild(searchSummary); + Search.output = out.appendChild(searchList); + + const searchProgress = document.getElementById("search-progress"); + // Some themes don't use the search progress node + if (searchProgress) { + searchProgress.innerText = _("Preparing search..."); + } + Search.startPulse(); + + // index already loaded, the browser was quick! + if (Search.hasIndex()) Search.query(query); + else Search.deferQuery(query); + }, + + /** + * execute search (requires search index to be loaded) + */ + query: (query) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + const allTitles = Search._index.alltitles; + const indexEntries = Search._index.indexentries; + + // stem the search terms and add them to the correct list + const stemmer = new Stemmer(); + const searchTerms = new Set(); + const excludedTerms = new Set(); + const highlightTerms = new Set(); + const objectTerms = new Set(splitQuery(query.toLowerCase().trim())); + splitQuery(query.trim()).forEach((queryTerm) => { + const queryTermLower = queryTerm.toLowerCase(); + + // maybe skip this "word" + // stopwords array is from language_data.js + if ( + stopwords.indexOf(queryTermLower) !== -1 || + queryTerm.match(/^\d+$/) + ) + return; + + // stem the word + let word = stemmer.stemWord(queryTermLower); + // select the correct list + if (word[0] === "-") excludedTerms.add(word.substr(1)); + else { + searchTerms.add(word); + highlightTerms.add(queryTermLower); + } + }); + + if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js + localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" ")) + } + + // console.debug("SEARCH: searching for:"); + // console.info("required: ", [...searchTerms]); + // console.info("excluded: ", [...excludedTerms]); + + // array of [docname, title, anchor, descr, score, filename] + let results = []; + _removeChildren(document.getElementById("search-progress")); + + const queryLower = query.toLowerCase(); + for (const [title, foundTitles] of Object.entries(allTitles)) { + if (title.toLowerCase().includes(queryLower) && (queryLower.length >= title.length/2)) { + for (const [file, id] of foundTitles) { + let score = Math.round(100 * queryLower.length / title.length) + results.push([ + docNames[file], + titles[file] !== title ? `${titles[file]} > ${title}` : title, + id !== null ? "#" + id : "", + null, + score, + filenames[file], + ]); + } + } + } + + // search for explicit entries in index directives + for (const [entry, foundEntries] of Object.entries(indexEntries)) { + if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) { + for (const [file, id] of foundEntries) { + let score = Math.round(100 * queryLower.length / entry.length) + results.push([ + docNames[file], + titles[file], + id ? "#" + id : "", + null, + score, + filenames[file], + ]); + } + } + } + + // lookup as object + objectTerms.forEach((term) => + results.push(...Search.performObjectSearch(term, objectTerms)) + ); + + // lookup as search terms in fulltext + results.push(...Search.performTermsSearch(searchTerms, excludedTerms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) results.forEach((item) => (item[4] = Scorer.score(item))); + + // now sort the results by score (in opposite order of appearance, since the + // display function below uses pop() to retrieve items) and then + // alphabetically + results.sort((a, b) => { + const leftScore = a[4]; + const rightScore = b[4]; + if (leftScore === rightScore) { + // same score: sort alphabetically + const leftTitle = a[1].toLowerCase(); + const rightTitle = b[1].toLowerCase(); + if (leftTitle === rightTitle) return 0; + return leftTitle > rightTitle ? -1 : 1; // inverted is intentional + } + return leftScore > rightScore ? 1 : -1; + }); + + // remove duplicate search results + // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept + let seen = new Set(); + results = results.reverse().reduce((acc, result) => { + let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(','); + if (!seen.has(resultStr)) { + acc.push(result); + seen.add(resultStr); + } + return acc; + }, []); + + results = results.reverse(); + + // for debugging + //Search.lastresults = results.slice(); // a copy + // console.info("search results:", Search.lastresults); + + // print the results + _displayNextItem(results, results.length, searchTerms, highlightTerms); + }, + + /** + * search for object names + */ + performObjectSearch: (object, objectTerms) => { + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const objects = Search._index.objects; + const objNames = Search._index.objnames; + const titles = Search._index.titles; + + const results = []; + + const objectSearchCallback = (prefix, match) => { + const name = match[4] + const fullname = (prefix ? prefix + "." : "") + name; + const fullnameLower = fullname.toLowerCase(); + if (fullnameLower.indexOf(object) < 0) return; + + let score = 0; + const parts = fullnameLower.split("."); + + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower === object || parts.slice(-1)[0] === object) + score += Scorer.objNameMatch; + else if (parts.slice(-1)[0].indexOf(object) > -1) + score += Scorer.objPartialMatch; // matches in last name + + const objName = objNames[match[1]][2]; + const title = titles[match[0]]; + + // If more than one term searched for, we require other words to be + // found in the name/title/description + const otherTerms = new Set(objectTerms); + otherTerms.delete(object); + if (otherTerms.size > 0) { + const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase(); + if ( + [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0) + ) + return; + } + + let anchor = match[3]; + if (anchor === "") anchor = fullname; + else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname; + + const descr = objName + _(", in ") + title; + + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) + score += Scorer.objPrio[match[2]]; + else score += Scorer.objPrioDefault; + + results.push([ + docNames[match[0]], + fullname, + "#" + anchor, + descr, + score, + filenames[match[0]], + ]); + }; + Object.keys(objects).forEach((prefix) => + objects[prefix].forEach((array) => + objectSearchCallback(prefix, array) + ) + ); + return results; + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch: (searchTerms, excludedTerms) => { + // prepare search + const terms = Search._index.terms; + const titleTerms = Search._index.titleterms; + const filenames = Search._index.filenames; + const docNames = Search._index.docnames; + const titles = Search._index.titles; + + const scoreMap = new Map(); + const fileMap = new Map(); + + // perform the search on the required terms + searchTerms.forEach((word) => { + const files = []; + const arr = [ + { files: terms[word], score: Scorer.term }, + { files: titleTerms[word], score: Scorer.title }, + ]; + // add support for partial matches + if (word.length > 2) { + const escapedWord = _escapeRegExp(word); + Object.keys(terms).forEach((term) => { + if (term.match(escapedWord) && !terms[word]) + arr.push({ files: terms[term], score: Scorer.partialTerm }); + }); + Object.keys(titleTerms).forEach((term) => { + if (term.match(escapedWord) && !titleTerms[word]) + arr.push({ files: titleTerms[word], score: Scorer.partialTitle }); + }); + } + + // no match but word was a required one + if (arr.every((record) => record.files === undefined)) return; + + // found search word in contents + arr.forEach((record) => { + if (record.files === undefined) return; + + let recordFiles = record.files; + if (recordFiles.length === undefined) recordFiles = [recordFiles]; + files.push(...recordFiles); + + // set score for the word in each file + recordFiles.forEach((file) => { + if (!scoreMap.has(file)) scoreMap.set(file, {}); + scoreMap.get(file)[word] = record.score; + }); + }); + + // create the mapping + files.forEach((file) => { + if (fileMap.has(file) && fileMap.get(file).indexOf(word) === -1) + fileMap.get(file).push(word); + else fileMap.set(file, [word]); + }); + }); + + // now check if the files don't contain excluded terms + const results = []; + for (const [file, wordList] of fileMap) { + // check if all requirements are matched + + // as search terms with length < 3 are discarded + const filteredTermCount = [...searchTerms].filter( + (term) => term.length > 2 + ).length; + if ( + wordList.length !== searchTerms.size && + wordList.length !== filteredTermCount + ) + continue; + + // ensure that none of the excluded terms is in the search result + if ( + [...excludedTerms].some( + (term) => + terms[term] === file || + titleTerms[term] === file || + (terms[term] || []).includes(file) || + (titleTerms[term] || []).includes(file) + ) + ) + break; + + // select one (max) score for the file. + const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + // add result to the result list + results.push([ + docNames[file], + titles[file], + "", + null, + score, + filenames[file], + ]); + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words. + */ + makeSearchSummary: (htmlText, keywords) => { + const text = Search.htmlToText(htmlText); + if (text === "") return null; + + const textLower = text.toLowerCase(); + const actualStartPosition = [...keywords] + .map((k) => textLower.indexOf(k.toLowerCase())) + .filter((i) => i > -1) + .slice(-1)[0]; + const startWithContext = Math.max(actualStartPosition - 120, 0); + + const top = startWithContext === 0 ? "" : "..."; + const tail = startWithContext + 240 < text.length ? "..." : ""; + + let summary = document.createElement("p"); + summary.classList.add("context"); + summary.textContent = top + text.substr(startWithContext, 240).trim() + tail; + + return summary; + }, +}; + +_ready(Search.init); diff --git a/_static/skeleton.css b/_static/skeleton.css new file mode 100644 index 0000000..467c878 --- /dev/null +++ b/_static/skeleton.css @@ -0,0 +1,296 @@ +/* Some sane resets. */ +html { + height: 100%; +} + +body { + margin: 0; + min-height: 100%; +} + +/* All the flexbox magic! */ +body, +.sb-announcement, +.sb-content, +.sb-main, +.sb-container, +.sb-container__inner, +.sb-article-container, +.sb-footer-content, +.sb-header, +.sb-header-secondary, +.sb-footer { + display: flex; +} + +/* These order things vertically */ +body, +.sb-main, +.sb-article-container { + flex-direction: column; +} + +/* Put elements in the center */ +.sb-header, +.sb-header-secondary, +.sb-container, +.sb-content, +.sb-footer, +.sb-footer-content { + justify-content: center; +} +/* Put elements at the ends */ +.sb-article-container { + justify-content: space-between; +} + +/* These elements grow. */ +.sb-main, +.sb-content, +.sb-container, +article { + flex-grow: 1; +} + +/* Because padding making this wider is not fun */ +article { + box-sizing: border-box; +} + +/* The announcements element should never be wider than the page. */ +.sb-announcement { + max-width: 100%; +} + +.sb-sidebar-primary, +.sb-sidebar-secondary { + flex-shrink: 0; + width: 17rem; +} + +.sb-announcement__inner { + justify-content: center; + + box-sizing: border-box; + height: 3rem; + + overflow-x: auto; + white-space: nowrap; +} + +/* Sidebars, with checkbox-based toggle */ +.sb-sidebar-primary, +.sb-sidebar-secondary { + position: fixed; + height: 100%; + top: 0; +} + +.sb-sidebar-primary { + left: -17rem; + transition: left 250ms ease-in-out; +} +.sb-sidebar-secondary { + right: -17rem; + transition: right 250ms ease-in-out; +} + +.sb-sidebar-toggle { + display: none; +} +.sb-sidebar-overlay { + position: fixed; + top: 0; + width: 0; + height: 0; + + transition: width 0ms ease 250ms, height 0ms ease 250ms, opacity 250ms ease; + + opacity: 0; + background-color: rgba(0, 0, 0, 0.54); +} + +#sb-sidebar-toggle--primary:checked + ~ .sb-sidebar-overlay[for="sb-sidebar-toggle--primary"], +#sb-sidebar-toggle--secondary:checked + ~ .sb-sidebar-overlay[for="sb-sidebar-toggle--secondary"] { + width: 100%; + height: 100%; + opacity: 1; + transition: width 0ms ease, height 0ms ease, opacity 250ms ease; +} + +#sb-sidebar-toggle--primary:checked ~ .sb-container .sb-sidebar-primary { + left: 0; +} +#sb-sidebar-toggle--secondary:checked ~ .sb-container .sb-sidebar-secondary { + right: 0; +} + +/* Full-width mode */ +.drop-secondary-sidebar-for-full-width-content + .hide-when-secondary-sidebar-shown { + display: none !important; +} +.drop-secondary-sidebar-for-full-width-content .sb-sidebar-secondary { + display: none !important; +} + +/* Mobile views */ +.sb-page-width { + width: 100%; +} + +.sb-article-container, +.sb-footer-content__inner, +.drop-secondary-sidebar-for-full-width-content .sb-article, +.drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 100vw; +} + +.sb-article, +.match-content-width { + padding: 0 1rem; + box-sizing: border-box; +} + +@media (min-width: 32rem) { + .sb-article, + .match-content-width { + padding: 0 2rem; + } +} + +/* Tablet views */ +@media (min-width: 42rem) { + .sb-article-container { + width: auto; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 42rem; + } + .sb-article, + .match-content-width { + width: 42rem; + } +} +@media (min-width: 46rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 46rem; + } + .sb-article, + .match-content-width { + width: 46rem; + } +} +@media (min-width: 50rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 50rem; + } + .sb-article, + .match-content-width { + width: 50rem; + } +} + +/* Tablet views */ +@media (min-width: 59rem) { + .sb-sidebar-secondary { + position: static; + } + .hide-when-secondary-sidebar-shown { + display: none !important; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 59rem; + } + .sb-article, + .match-content-width { + width: 42rem; + } +} +@media (min-width: 63rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 63rem; + } + .sb-article, + .match-content-width { + width: 46rem; + } +} +@media (min-width: 67rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 67rem; + } + .sb-article, + .match-content-width { + width: 50rem; + } +} + +/* Desktop views */ +@media (min-width: 76rem) { + .sb-sidebar-primary { + position: static; + } + .hide-when-primary-sidebar-shown { + display: none !important; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 59rem; + } + .sb-article, + .match-content-width { + width: 42rem; + } +} + +/* Full desktop views */ +@media (min-width: 80rem) { + .sb-article, + .match-content-width { + width: 46rem; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 63rem; + } +} + +@media (min-width: 84rem) { + .sb-article, + .match-content-width { + width: 50rem; + } + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 67rem; + } +} + +@media (min-width: 88rem) { + .sb-footer-content__inner, + .drop-secondary-sidebar-for-full-width-content .sb-article, + .drop-secondary-sidebar-for-full-width-content .match-content-width { + width: 67rem; + } + .sb-page-width { + width: 88rem; + } +} diff --git a/_static/sphinx_highlight.js b/_static/sphinx_highlight.js new file mode 100644 index 0000000..8a96c69 --- /dev/null +++ b/_static/sphinx_highlight.js @@ -0,0 +1,154 @@ +/* Highlighting utilities for Sphinx HTML documentation. */ +"use strict"; + +const SPHINX_HIGHLIGHT_ENABLED = true + +/** + * highlight a given string on a node by wrapping it in + * span elements with the given class name. + */ +const _highlight = (node, addItems, text, className) => { + if (node.nodeType === Node.TEXT_NODE) { + const val = node.nodeValue; + const parent = node.parentNode; + const pos = val.toLowerCase().indexOf(text); + if ( + pos >= 0 && + !parent.classList.contains(className) && + !parent.classList.contains("nohighlight") + ) { + let span; + + const closestNode = parent.closest("body, svg, foreignObject"); + const isInSVG = closestNode && closestNode.matches("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.classList.add(className); + } + + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + const rest = document.createTextNode(val.substr(pos + text.length)); + parent.insertBefore( + span, + parent.insertBefore( + rest, + node.nextSibling + ) + ); + node.nodeValue = val.substr(0, pos); + /* There may be more occurrences of search term in this node. So call this + * function recursively on the remaining fragment. + */ + _highlight(rest, addItems, text, className); + + if (isInSVG) { + const rect = document.createElementNS( + "http://www.w3.org/2000/svg", + "rect" + ); + const bbox = parent.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute("class", className); + addItems.push({ parent: parent, target: rect }); + } + } + } else if (node.matches && !node.matches("button, select, textarea")) { + node.childNodes.forEach((el) => _highlight(el, addItems, text, className)); + } +}; +const _highlightText = (thisNode, text, className) => { + let addItems = []; + _highlight(thisNode, addItems, text, className); + addItems.forEach((obj) => + obj.parent.insertAdjacentElement("beforebegin", obj.target) + ); +}; + +/** + * Small JavaScript module for the documentation. + */ +const SphinxHighlight = { + + /** + * highlight the search words provided in localstorage in the text + */ + highlightSearchWords: () => { + if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight + + // get and clear terms from localstorage + const url = new URL(window.location); + const highlight = + localStorage.getItem("sphinx_highlight_terms") + || url.searchParams.get("highlight") + || ""; + localStorage.removeItem("sphinx_highlight_terms") + url.searchParams.delete("highlight"); + window.history.replaceState({}, "", url); + + // get individual terms from highlight string + const terms = highlight.toLowerCase().split(/\s+/).filter(x => x); + if (terms.length === 0) return; // nothing to do + + // There should never be more than one element matching "div.body" + const divBody = document.querySelectorAll("div.body"); + const body = divBody.length ? divBody[0] : document.querySelector("body"); + window.setTimeout(() => { + terms.forEach((term) => _highlightText(body, term, "highlighted")); + }, 10); + + const searchBox = document.getElementById("searchbox"); + if (searchBox === null) return; + searchBox.appendChild( + document + .createRange() + .createContextualFragment( + '

' + + '' + + _("Hide Search Matches") + + "

" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/_static/styles/furo-extensions.css b/_static/styles/furo-extensions.css new file mode 100644 index 0000000..bc447f2 --- /dev/null +++ b/_static/styles/furo-extensions.css @@ -0,0 +1,2 @@ +#furo-sidebar-ad-placement{padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)}#furo-sidebar-ad-placement .ethical-sidebar{background:var(--color-background-secondary);border:none;box-shadow:none}#furo-sidebar-ad-placement .ethical-sidebar:hover{background:var(--color-background-hover)}#furo-sidebar-ad-placement .ethical-sidebar a{color:var(--color-foreground-primary)}#furo-sidebar-ad-placement .ethical-callout a{color:var(--color-foreground-secondary)!important}#furo-readthedocs-versions{background:transparent;display:block;position:static;width:100%}#furo-readthedocs-versions .rst-versions{background:#1a1c1e}#furo-readthedocs-versions .rst-current-version{background:var(--color-sidebar-item-background);cursor:unset}#furo-readthedocs-versions .rst-current-version:hover{background:var(--color-sidebar-item-background)}#furo-readthedocs-versions .rst-current-version .fa-book{color:var(--color-foreground-primary)}#furo-readthedocs-versions>.rst-other-versions{padding:0}#furo-readthedocs-versions>.rst-other-versions small{opacity:1}#furo-readthedocs-versions .injected .rst-versions{position:unset}#furo-readthedocs-versions:focus-within,#furo-readthedocs-versions:hover{box-shadow:0 0 0 1px var(--color-sidebar-background-border)}#furo-readthedocs-versions:focus-within .rst-current-version,#furo-readthedocs-versions:hover .rst-current-version{background:#1a1c1e;font-size:inherit;height:auto;line-height:inherit;padding:12px;text-align:right}#furo-readthedocs-versions:focus-within .rst-current-version .fa-book,#furo-readthedocs-versions:hover .rst-current-version .fa-book{color:#fff;float:left}#furo-readthedocs-versions:focus-within .fa-caret-down,#furo-readthedocs-versions:hover .fa-caret-down{display:none}#furo-readthedocs-versions:focus-within .injected,#furo-readthedocs-versions:focus-within .rst-current-version,#furo-readthedocs-versions:focus-within .rst-other-versions,#furo-readthedocs-versions:hover .injected,#furo-readthedocs-versions:hover .rst-current-version,#furo-readthedocs-versions:hover .rst-other-versions{display:block}#furo-readthedocs-versions:focus-within>.rst-current-version,#furo-readthedocs-versions:hover>.rst-current-version{display:none}.highlight:hover button.copybtn{color:var(--color-code-foreground)}.highlight button.copybtn{align-items:center;background-color:var(--color-code-background);border:none;color:var(--color-background-item);cursor:pointer;height:1.25em;opacity:1;right:.5rem;top:.625rem;transition:color .3s,opacity .3s;width:1.25em}.highlight button.copybtn:hover{background-color:var(--color-code-background);color:var(--color-brand-content)}.highlight button.copybtn:after{background-color:transparent;color:var(--color-code-foreground);display:none}.highlight button.copybtn.success{color:#22863a;transition:color 0ms}.highlight button.copybtn.success:after{display:block}.highlight button.copybtn svg{padding:0}body{--sd-color-primary:var(--color-brand-primary);--sd-color-primary-highlight:var(--color-brand-content);--sd-color-primary-text:var(--color-background-primary);--sd-color-shadow:rgba(0,0,0,.05);--sd-color-card-border:var(--color-card-border);--sd-color-card-border-hover:var(--color-brand-content);--sd-color-card-background:var(--color-card-background);--sd-color-card-text:var(--color-foreground-primary);--sd-color-card-header:var(--color-card-marginals-background);--sd-color-card-footer:var(--color-card-marginals-background);--sd-color-tabs-label-active:var(--color-brand-content);--sd-color-tabs-label-hover:var(--color-foreground-muted);--sd-color-tabs-label-inactive:var(--color-foreground-muted);--sd-color-tabs-underline-active:var(--color-brand-content);--sd-color-tabs-underline-hover:var(--color-foreground-border);--sd-color-tabs-underline-inactive:var(--color-background-border);--sd-color-tabs-overline:var(--color-background-border);--sd-color-tabs-underline:var(--color-background-border)}.sd-tab-content{box-shadow:0 -2px var(--sd-color-tabs-overline),0 1px var(--sd-color-tabs-underline)}.sd-card{box-shadow:0 .1rem .25rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)}.sd-shadow-sm{box-shadow:0 .1rem .25rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-shadow-md{box-shadow:0 .3rem .75rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-shadow-lg{box-shadow:0 .6rem 1.5rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-card-hover:hover{transform:none}.sd-cards-carousel{gap:.25rem;padding:.25rem}body{--tabs--label-text:var(--color-foreground-muted);--tabs--label-text--hover:var(--color-foreground-muted);--tabs--label-text--active:var(--color-brand-content);--tabs--label-text--active--hover:var(--color-brand-content);--tabs--label-background:transparent;--tabs--label-background--hover:transparent;--tabs--label-background--active:transparent;--tabs--label-background--active--hover:transparent;--tabs--padding-x:0.25em;--tabs--margin-x:1em;--tabs--border:var(--color-background-border);--tabs--label-border:transparent;--tabs--label-border--hover:var(--color-foreground-muted);--tabs--label-border--active:var(--color-brand-content);--tabs--label-border--active--hover:var(--color-brand-content)}[role=main] .container{max-width:none;padding-left:0;padding-right:0}.shadow.docutils{border:none;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1)!important}.sphinx-bs .card{background-color:var(--color-background-secondary);color:var(--color-foreground)} +/*# sourceMappingURL=furo-extensions.css.map*/ \ No newline at end of file diff --git a/_static/styles/furo-extensions.css.map b/_static/styles/furo-extensions.css.map new file mode 100644 index 0000000..9ba5637 --- /dev/null +++ b/_static/styles/furo-extensions.css.map @@ -0,0 +1 @@ +{"version":3,"file":"styles/furo-extensions.css","mappings":"AAGA,2BACE,oFACA,4CAKE,6CAHA,YACA,eAEA,CACA,kDACE,yCAEF,8CACE,sCAEJ,8CACE,kDAEJ,2BAGE,uBACA,cAHA,gBACA,UAEA,CAGA,yCACE,mBAEF,gDAEE,gDADA,YACA,CACA,sDACE,gDACF,yDACE,sCAEJ,+CACE,UACA,qDACE,UAGF,mDACE,eAEJ,yEAEE,4DAEA,mHASE,mBAPA,kBAEA,YADA,oBAGA,aADA,gBAIA,CAEA,qIAEE,WADA,UACA,CAEJ,uGACE,aAEF,iUAGE,cAEF,mHACE,aC1EJ,gCACE,mCAEF,0BAKE,mBAUA,8CACA,YAFA,mCAKA,eAZA,cALA,UASA,YADA,YAYA,iCAdA,YAcA,CAEA,gCAEE,8CADA,gCACA,CAEF,gCAGE,6BADA,mCADA,YAEA,CAEF,kCAEE,cADA,oBACA,CACA,wCACE,cAEJ,8BACE,UC5CN,KAEE,6CAA8C,CAC9C,uDAAwD,CACxD,uDAAwD,CAGxD,iCAAsC,CAGtC,+CAAgD,CAChD,uDAAwD,CACxD,uDAAwD,CACxD,oDAAqD,CACrD,6DAA8D,CAC9D,6DAA8D,CAG9D,uDAAwD,CACxD,yDAA0D,CAC1D,4DAA6D,CAC7D,2DAA4D,CAC5D,8DAA+D,CAC/D,iEAAkE,CAClE,uDAAwD,CACxD,wDAAyD,CAG3D,gBACE,qFAGF,SACE,6EAEF,cACE,uFAEF,cACE,uFAEF,cACE,uFAGF,qBACE,eAEF,mBACE,WACA,eChDF,KACE,gDAAiD,CACjD,uDAAwD,CACxD,qDAAsD,CACtD,4DAA6D,CAC7D,oCAAqC,CACrC,2CAA4C,CAC5C,4CAA6C,CAC7C,mDAAoD,CACpD,wBAAyB,CACzB,oBAAqB,CACrB,6CAA8C,CAC9C,gCAAiC,CACjC,yDAA0D,CAC1D,uDAAwD,CACxD,8DAA+D,CCbjE,uBACE,eACA,eACA,gBAGF,iBACE,YACA,+EAGF,iBACE,mDACA","sources":["webpack:///./src/furo/assets/styles/extensions/_readthedocs.sass","webpack:///./src/furo/assets/styles/extensions/_copybutton.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-design.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-inline-tabs.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-panels.sass"],"sourcesContent":["// This file contains the styles used for tweaking how ReadTheDoc's embedded\n// contents would show up inside the theme.\n\n#furo-sidebar-ad-placement\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n .ethical-sidebar\n // Remove the border and box-shadow.\n border: none\n box-shadow: none\n // Manage the background colors.\n background: var(--color-background-secondary)\n &:hover\n background: var(--color-background-hover)\n // Ensure the text is legible.\n a\n color: var(--color-foreground-primary)\n\n .ethical-callout a\n color: var(--color-foreground-secondary) !important\n\n#furo-readthedocs-versions\n position: static\n width: 100%\n background: transparent\n display: block\n\n // Make the background color fit with the theme's aesthetic.\n .rst-versions\n background: rgb(26, 28, 30)\n\n .rst-current-version\n cursor: unset\n background: var(--color-sidebar-item-background)\n &:hover\n background: var(--color-sidebar-item-background)\n .fa-book\n color: var(--color-foreground-primary)\n\n > .rst-other-versions\n padding: 0\n small\n opacity: 1\n\n .injected\n .rst-versions\n position: unset\n\n &:hover,\n &:focus-within\n box-shadow: 0 0 0 1px var(--color-sidebar-background-border)\n\n .rst-current-version\n // Undo the tweaks done in RTD's CSS\n font-size: inherit\n line-height: inherit\n height: auto\n text-align: right\n padding: 12px\n\n // Match the rest of the body\n background: #1a1c1e\n\n .fa-book\n float: left\n color: white\n\n .fa-caret-down\n display: none\n\n .rst-current-version,\n .rst-other-versions,\n .injected\n display: block\n\n > .rst-current-version\n display: none\n",".highlight\n &:hover button.copybtn\n color: var(--color-code-foreground)\n\n button.copybtn\n // Make it visible\n opacity: 1\n\n // Align things correctly\n align-items: center\n\n height: 1.25em\n width: 1.25em\n\n top: 0.625rem // $code-spacing-vertical\n right: 0.5rem\n\n // Make it look better\n color: var(--color-background-item)\n background-color: var(--color-code-background)\n border: none\n\n // Change to cursor to make it obvious that you can click on it\n cursor: pointer\n\n // Transition smoothly, for aesthetics\n transition: color 300ms, opacity 300ms\n\n &:hover\n color: var(--color-brand-content)\n background-color: var(--color-code-background)\n\n &::after\n display: none\n color: var(--color-code-foreground)\n background-color: transparent\n\n &.success\n transition: color 0ms\n color: #22863a\n &::after\n display: block\n\n svg\n padding: 0\n","body\n // Colors\n --sd-color-primary: var(--color-brand-primary)\n --sd-color-primary-highlight: var(--color-brand-content)\n --sd-color-primary-text: var(--color-background-primary)\n\n // Shadows\n --sd-color-shadow: rgba(0, 0, 0, 0.05)\n\n // Cards\n --sd-color-card-border: var(--color-card-border)\n --sd-color-card-border-hover: var(--color-brand-content)\n --sd-color-card-background: var(--color-card-background)\n --sd-color-card-text: var(--color-foreground-primary)\n --sd-color-card-header: var(--color-card-marginals-background)\n --sd-color-card-footer: var(--color-card-marginals-background)\n\n // Tabs\n --sd-color-tabs-label-active: var(--color-brand-content)\n --sd-color-tabs-label-hover: var(--color-foreground-muted)\n --sd-color-tabs-label-inactive: var(--color-foreground-muted)\n --sd-color-tabs-underline-active: var(--color-brand-content)\n --sd-color-tabs-underline-hover: var(--color-foreground-border)\n --sd-color-tabs-underline-inactive: var(--color-background-border)\n --sd-color-tabs-overline: var(--color-background-border)\n --sd-color-tabs-underline: var(--color-background-border)\n\n// Tabs\n.sd-tab-content\n box-shadow: 0 -2px var(--sd-color-tabs-overline), 0 1px var(--sd-color-tabs-underline)\n\n// Shadows\n.sd-card // Have a shadow by default\n box-shadow: 0 0.1rem 0.25rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1)\n\n.sd-shadow-sm\n box-shadow: 0 0.1rem 0.25rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n.sd-shadow-md\n box-shadow: 0 0.3rem 0.75rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n.sd-shadow-lg\n box-shadow: 0 0.6rem 1.5rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n// Cards\n.sd-card-hover:hover // Don't change scale on hover\n transform: none\n\n.sd-cards-carousel // Have a bit of gap in the carousel by default\n gap: 0.25rem\n padding: 0.25rem\n","// This file contains styles to tweak sphinx-inline-tabs to work well with Furo.\n\nbody\n --tabs--label-text: var(--color-foreground-muted)\n --tabs--label-text--hover: var(--color-foreground-muted)\n --tabs--label-text--active: var(--color-brand-content)\n --tabs--label-text--active--hover: var(--color-brand-content)\n --tabs--label-background: transparent\n --tabs--label-background--hover: transparent\n --tabs--label-background--active: transparent\n --tabs--label-background--active--hover: transparent\n --tabs--padding-x: 0.25em\n --tabs--margin-x: 1em\n --tabs--border: var(--color-background-border)\n --tabs--label-border: transparent\n --tabs--label-border--hover: var(--color-foreground-muted)\n --tabs--label-border--active: var(--color-brand-content)\n --tabs--label-border--active--hover: var(--color-brand-content)\n","// This file contains styles to tweak sphinx-panels to work well with Furo.\n\n// sphinx-panels includes Bootstrap 4, which uses .container which can conflict\n// with docutils' `.. container::` directive.\n[role=\"main\"] .container\n max-width: initial\n padding-left: initial\n padding-right: initial\n\n// Make the panels look nicer!\n.shadow.docutils\n border: none\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n// Make panel colors respond to dark mode\n.sphinx-bs .card\n background-color: var(--color-background-secondary)\n color: var(--color-foreground)\n"],"names":[],"sourceRoot":""} \ No newline at end of file diff --git a/_static/styles/furo.css b/_static/styles/furo.css new file mode 100644 index 0000000..3d29a21 --- /dev/null +++ b/_static/styles/furo.css @@ -0,0 +1,2 @@ +/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */html{-webkit-text-size-adjust:100%;line-height:1.15}body{margin:0}main{display:block}h1{font-size:2em;margin:.67em 0}hr{box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace,monospace;font-size:1em}a{background-color:transparent}abbr[title]{border-bottom:none;text-decoration:underline;text-decoration:underline dotted}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace,monospace;font-size:1em}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}[type=button],[type=reset],[type=submit],button{-webkit-appearance:button}[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner,button::-moz-focus-inner{border-style:none;padding:0}[type=button]:-moz-focusring,[type=reset]:-moz-focusring,[type=submit]:-moz-focusring,button:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:.35em .75em .625em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type=checkbox],[type=radio]{box-sizing:border-box;padding:0}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}[type=search]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details{display:block}summary{display:list-item}[hidden],template{display:none}@media print{.content-icon-container,.headerlink,.mobile-header,.related-pages{display:none!important}.highlight{border:.1pt solid var(--color-foreground-border)}a,blockquote,dl,ol,pre,table,ul{page-break-inside:avoid}caption,figure,h1,h2,h3,h4,h5,h6,img{page-break-after:avoid;page-break-inside:avoid}dl,ol,ul{page-break-before:avoid}}.visually-hidden{clip:rect(0,0,0,0)!important;border:0!important;height:1px!important;margin:-1px!important;overflow:hidden!important;padding:0!important;position:absolute!important;white-space:nowrap!important;width:1px!important}:-moz-focusring{outline:auto}body{--font-stack:-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif,Apple Color Emoji,Segoe UI Emoji;--font-stack--monospace:"SFMono-Regular",Menlo,Consolas,Monaco,Liberation Mono,Lucida Console,monospace;--font-size--normal:100%;--font-size--small:87.5%;--font-size--small--2:81.25%;--font-size--small--3:75%;--font-size--small--4:62.5%;--sidebar-caption-font-size:var(--font-size--small--2);--sidebar-item-font-size:var(--font-size--small);--sidebar-search-input-font-size:var(--font-size--small);--toc-font-size:var(--font-size--small--3);--toc-font-size--mobile:var(--font-size--normal);--toc-title-font-size:var(--font-size--small--4);--admonition-font-size:0.8125rem;--admonition-title-font-size:0.8125rem;--code-font-size:var(--font-size--small--2);--api-font-size:var(--font-size--small);--header-height:calc(var(--sidebar-item-line-height) + var(--sidebar-item-spacing-vertical)*4);--header-padding:0.5rem;--sidebar-tree-space-above:1.5rem;--sidebar-caption-space-above:1rem;--sidebar-item-line-height:1rem;--sidebar-item-spacing-vertical:0.5rem;--sidebar-item-spacing-horizontal:1rem;--sidebar-item-height:calc(var(--sidebar-item-line-height) + var(--sidebar-item-spacing-vertical)*2);--sidebar-expander-width:var(--sidebar-item-height);--sidebar-search-space-above:0.5rem;--sidebar-search-input-spacing-vertical:0.5rem;--sidebar-search-input-spacing-horizontal:0.5rem;--sidebar-search-input-height:1rem;--sidebar-search-icon-size:var(--sidebar-search-input-height);--toc-title-padding:0.25rem 0;--toc-spacing-vertical:1.5rem;--toc-spacing-horizontal:1.5rem;--toc-item-spacing-vertical:0.4rem;--toc-item-spacing-horizontal:1rem;--icon-search:url('data:image/svg+xml;charset=utf-8,');--icon-pencil:url('data:image/svg+xml;charset=utf-8,');--icon-abstract:url('data:image/svg+xml;charset=utf-8,');--icon-info:url('data:image/svg+xml;charset=utf-8,');--icon-flame:url('data:image/svg+xml;charset=utf-8,');--icon-question:url('data:image/svg+xml;charset=utf-8,');--icon-warning:url('data:image/svg+xml;charset=utf-8,');--icon-failure:url('data:image/svg+xml;charset=utf-8,');--icon-spark:url('data:image/svg+xml;charset=utf-8,');--color-admonition-title--caution:#ff9100;--color-admonition-title-background--caution:rgba(255,145,0,.2);--color-admonition-title--warning:#ff9100;--color-admonition-title-background--warning:rgba(255,145,0,.2);--color-admonition-title--danger:#ff5252;--color-admonition-title-background--danger:rgba(255,82,82,.2);--color-admonition-title--attention:#ff5252;--color-admonition-title-background--attention:rgba(255,82,82,.2);--color-admonition-title--error:#ff5252;--color-admonition-title-background--error:rgba(255,82,82,.2);--color-admonition-title--hint:#00c852;--color-admonition-title-background--hint:rgba(0,200,82,.2);--color-admonition-title--tip:#00c852;--color-admonition-title-background--tip:rgba(0,200,82,.2);--color-admonition-title--important:#00bfa5;--color-admonition-title-background--important:rgba(0,191,165,.2);--color-admonition-title--note:#00b0ff;--color-admonition-title-background--note:rgba(0,176,255,.2);--color-admonition-title--seealso:#448aff;--color-admonition-title-background--seealso:rgba(68,138,255,.2);--color-admonition-title--admonition-todo:grey;--color-admonition-title-background--admonition-todo:hsla(0,0%,50%,.2);--color-admonition-title:#651fff;--color-admonition-title-background:rgba(101,31,255,.2);--icon-admonition-default:var(--icon-abstract);--color-topic-title:#14b8a6;--color-topic-title-background:rgba(20,184,166,.2);--icon-topic-default:var(--icon-pencil);--color-problematic:#b30000;--color-foreground-primary:#000;--color-foreground-secondary:#5a5c63;--color-foreground-muted:#646776;--color-foreground-border:#878787;--color-background-primary:#fff;--color-background-secondary:#f8f9fb;--color-background-hover:#efeff4;--color-background-hover--transparent:#efeff400;--color-background-border:#eeebee;--color-background-item:#ccc;--color-announcement-background:#000000dd;--color-announcement-text:#eeebee;--color-brand-primary:#2962ff;--color-brand-content:#2a5adf;--color-api-background:var(--color-background-hover--transparent);--color-api-background-hover:var(--color-background-hover);--color-api-overall:var(--color-foreground-secondary);--color-api-name:var(--color-problematic);--color-api-pre-name:var(--color-problematic);--color-api-paren:var(--color-foreground-secondary);--color-api-keyword:var(--color-foreground-primary);--color-highlight-on-target:#ffc;--color-inline-code-background:var(--color-background-secondary);--color-highlighted-background:#def;--color-highlighted-text:var(--color-foreground-primary);--color-guilabel-background:#ddeeff80;--color-guilabel-border:#bedaf580;--color-guilabel-text:var(--color-foreground-primary);--color-admonition-background:transparent;--color-table-header-background:var(--color-background-secondary);--color-table-border:var(--color-background-border);--color-card-border:var(--color-background-secondary);--color-card-background:transparent;--color-card-marginals-background:var(--color-background-secondary);--color-header-background:var(--color-background-primary);--color-header-border:var(--color-background-border);--color-header-text:var(--color-foreground-primary);--color-sidebar-background:var(--color-background-secondary);--color-sidebar-background-border:var(--color-background-border);--color-sidebar-brand-text:var(--color-foreground-primary);--color-sidebar-caption-text:var(--color-foreground-muted);--color-sidebar-link-text:var(--color-foreground-secondary);--color-sidebar-link-text--top-level:var(--color-brand-primary);--color-sidebar-item-background:var(--color-sidebar-background);--color-sidebar-item-background--current:var( --color-sidebar-item-background );--color-sidebar-item-background--hover:linear-gradient(90deg,var(--color-background-hover--transparent) 0%,var(--color-background-hover) var(--sidebar-item-spacing-horizontal),var(--color-background-hover) 100%);--color-sidebar-item-expander-background:transparent;--color-sidebar-item-expander-background--hover:var( --color-background-hover );--color-sidebar-search-text:var(--color-foreground-primary);--color-sidebar-search-background:var(--color-background-secondary);--color-sidebar-search-background--focus:var(--color-background-primary);--color-sidebar-search-border:var(--color-background-border);--color-sidebar-search-icon:var(--color-foreground-muted);--color-toc-background:var(--color-background-primary);--color-toc-title-text:var(--color-foreground-muted);--color-toc-item-text:var(--color-foreground-secondary);--color-toc-item-text--hover:var(--color-foreground-primary);--color-toc-item-text--active:var(--color-brand-primary);--color-content-foreground:var(--color-foreground-primary);--color-content-background:transparent;--color-link:var(--color-brand-content);--color-link--hover:var(--color-brand-content);--color-link-underline:var(--color-background-border);--color-link-underline--hover:var(--color-foreground-border)}.only-light{display:block!important}html body .only-dark{display:none!important}@media not print{body[data-theme=dark]{--color-problematic:#ee5151;--color-foreground-primary:#ffffffcc;--color-foreground-secondary:#9ca0a5;--color-foreground-muted:#81868d;--color-foreground-border:#666;--color-background-primary:#131416;--color-background-secondary:#1a1c1e;--color-background-hover:#1e2124;--color-background-hover--transparent:#1e212400;--color-background-border:#303335;--color-background-item:#444;--color-announcement-background:#000000dd;--color-announcement-text:#eeebee;--color-brand-primary:#2b8cee;--color-brand-content:#368ce2;--color-highlighted-background:#083563;--color-guilabel-background:#08356380;--color-guilabel-border:#13395f80;--color-api-keyword:var(--color-foreground-secondary);--color-highlight-on-target:#330;--color-admonition-background:#18181a;--color-card-border:var(--color-background-secondary);--color-card-background:#18181a;--color-card-marginals-background:var(--color-background-hover)}html body[data-theme=dark] .only-light{display:none!important}body[data-theme=dark] .only-dark{display:block!important}@media(prefers-color-scheme:dark){body:not([data-theme=light]){--color-problematic:#ee5151;--color-foreground-primary:#ffffffcc;--color-foreground-secondary:#9ca0a5;--color-foreground-muted:#81868d;--color-foreground-border:#666;--color-background-primary:#131416;--color-background-secondary:#1a1c1e;--color-background-hover:#1e2124;--color-background-hover--transparent:#1e212400;--color-background-border:#303335;--color-background-item:#444;--color-announcement-background:#000000dd;--color-announcement-text:#eeebee;--color-brand-primary:#2b8cee;--color-brand-content:#368ce2;--color-highlighted-background:#083563;--color-guilabel-background:#08356380;--color-guilabel-border:#13395f80;--color-api-keyword:var(--color-foreground-secondary);--color-highlight-on-target:#330;--color-admonition-background:#18181a;--color-card-border:var(--color-background-secondary);--color-card-background:#18181a;--color-card-marginals-background:var(--color-background-hover)}html body:not([data-theme=light]) .only-light{display:none!important}body:not([data-theme=light]) .only-dark{display:block!important}}}body[data-theme=auto] .theme-toggle svg.theme-icon-when-auto,body[data-theme=dark] .theme-toggle svg.theme-icon-when-dark,body[data-theme=light] .theme-toggle svg.theme-icon-when-light{display:block}body{font-family:var(--font-stack)}code,kbd,pre,samp{font-family:var(--font-stack--monospace)}body{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}article{line-height:1.5}h1,h2,h3,h4,h5,h6{border-radius:.5rem;font-weight:700;line-height:1.25;margin:.5rem -.5rem;padding-left:.5rem;padding-right:.5rem}h1+p,h2+p,h3+p,h4+p,h5+p,h6+p{margin-top:0}h1{font-size:2.5em;margin-bottom:1rem}h1,h2{margin-top:1.75rem}h2{font-size:2em}h3{font-size:1.5em}h4{font-size:1.25em}h5{font-size:1.125em}h6{font-size:1em}small{font-size:80%;opacity:75%}p{margin-bottom:.75rem;margin-top:.5rem}hr.docutils{background-color:var(--color-background-border);border:0;height:1px;margin:2rem 0;padding:0}.centered{text-align:center}a{color:var(--color-link);text-decoration:underline;text-decoration-color:var(--color-link-underline)}a:hover{color:var(--color-link--hover);text-decoration-color:var(--color-link-underline--hover)}a.muted-link{color:inherit}a.muted-link:hover{color:var(--color-link);text-decoration-color:var(--color-link-underline--hover)}html{overflow-x:hidden;overflow-y:scroll;scroll-behavior:smooth}.sidebar-scroll,.toc-scroll,article[role=main] *{scrollbar-color:var(--color-foreground-border) transparent;scrollbar-width:thin}.sidebar-scroll::-webkit-scrollbar,.toc-scroll::-webkit-scrollbar,article[role=main] ::-webkit-scrollbar{height:.25rem;width:.25rem}.sidebar-scroll::-webkit-scrollbar-thumb,.toc-scroll::-webkit-scrollbar-thumb,article[role=main] ::-webkit-scrollbar-thumb{background-color:var(--color-foreground-border);border-radius:.125rem}body,html{background:var(--color-background-primary);color:var(--color-foreground-primary);height:100%}article{background:var(--color-content-background);color:var(--color-content-foreground);overflow-wrap:break-word}.page{display:flex;min-height:100%}.mobile-header{background-color:var(--color-header-background);border-bottom:1px solid var(--color-header-border);color:var(--color-header-text);display:none;height:var(--header-height);width:100%;z-index:10}.mobile-header.scrolled{border-bottom:none;box-shadow:0 0 .2rem rgba(0,0,0,.1),0 .2rem .4rem rgba(0,0,0,.2)}.mobile-header .header-center a{color:var(--color-header-text);text-decoration:none}.main{display:flex;flex:1}.sidebar-drawer{background:var(--color-sidebar-background);border-right:1px solid var(--color-sidebar-background-border);box-sizing:border-box;display:flex;justify-content:flex-end;min-width:15em;width:calc(50% - 26em)}.sidebar-container,.toc-drawer{box-sizing:border-box;width:15em}.toc-drawer{background:var(--color-toc-background);padding-right:1rem}.sidebar-sticky,.toc-sticky{display:flex;flex-direction:column;height:min(100%,100vh);height:100vh;position:sticky;top:0}.sidebar-scroll,.toc-scroll{flex-grow:1;flex-shrink:1;overflow:auto;scroll-behavior:smooth}.content{display:flex;flex-direction:column;justify-content:space-between;padding:0 3em;width:46em}.icon{display:inline-block;height:1rem;width:1rem}.icon svg{height:100%;width:100%}.announcement{align-items:center;background-color:var(--color-announcement-background);color:var(--color-announcement-text);display:flex;height:var(--header-height);overflow-x:auto}.announcement+.page{min-height:calc(100% - var(--header-height))}.announcement-content{box-sizing:border-box;min-width:100%;padding:.5rem;text-align:center;white-space:nowrap}.announcement-content a{color:var(--color-announcement-text);text-decoration-color:var(--color-announcement-text)}.announcement-content a:hover{color:var(--color-announcement-text);text-decoration-color:var(--color-link--hover)}.no-js .theme-toggle-container{display:none}.theme-toggle-container{vertical-align:middle}.theme-toggle{background:transparent;border:none;cursor:pointer;padding:0}.theme-toggle svg{color:var(--color-foreground-primary);display:none;height:1rem;vertical-align:middle;width:1rem}.theme-toggle-header{float:left;padding:1rem .5rem}.nav-overlay-icon,.toc-overlay-icon{cursor:pointer;display:none}.nav-overlay-icon .icon,.toc-overlay-icon .icon{color:var(--color-foreground-secondary);height:1rem;width:1rem}.nav-overlay-icon,.toc-header-icon{align-items:center;justify-content:center}.toc-content-icon{height:1.5rem;width:1.5rem}.content-icon-container{display:flex;float:right;gap:.5rem;margin-bottom:1rem;margin-left:1rem;margin-top:1.5rem}.content-icon-container .edit-this-page svg{color:inherit;height:1rem;width:1rem}.sidebar-toggle{display:none;position:absolute}.sidebar-toggle[name=__toc]{left:20px}.sidebar-toggle:checked{left:40px}.overlay{background-color:rgba(0,0,0,.54);height:0;opacity:0;position:fixed;top:0;transition:width 0ms,height 0ms,opacity .25s ease-out;width:0}.sidebar-overlay{z-index:20}.toc-overlay{z-index:40}.sidebar-drawer{transition:left .25s ease-in-out;z-index:30}.toc-drawer{transition:right .25s ease-in-out;z-index:50}#__navigation:checked~.sidebar-overlay{height:100%;opacity:1;width:100%}#__navigation:checked~.page .sidebar-drawer{left:0;top:0}#__toc:checked~.toc-overlay{height:100%;opacity:1;width:100%}#__toc:checked~.page .toc-drawer{right:0;top:0}.back-to-top{background:var(--color-background-primary);border-radius:1rem;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 1px 0 hsla(220,9%,46%,.502);display:none;font-size:.8125rem;left:0;margin-left:50%;padding:.5rem .75rem .5rem .5rem;position:fixed;text-decoration:none;top:1rem;transform:translateX(-50%);z-index:10}.back-to-top svg{fill:currentColor;display:inline-block;height:1rem;width:1rem}.back-to-top span{margin-left:.25rem}.show-back-to-top .back-to-top{align-items:center;display:flex}@media(min-width:97em){html{font-size:110%}}@media(max-width:82em){.toc-content-icon{display:flex}.toc-drawer{border-left:1px solid var(--color-background-muted);height:100vh;position:fixed;right:-15em;top:0}.toc-tree{border-left:none;font-size:var(--toc-font-size--mobile)}.sidebar-drawer{width:calc(50% - 18.5em)}}@media(max-width:67em){.nav-overlay-icon{display:flex}.sidebar-drawer{height:100vh;left:-15em;position:fixed;top:0;width:15em}.toc-header-icon{display:flex}.theme-toggle-content,.toc-content-icon{display:none}.theme-toggle-header{display:block}.mobile-header{align-items:center;display:flex;justify-content:space-between;position:sticky;top:0}.mobile-header .header-left,.mobile-header .header-right{display:flex;height:var(--header-height);padding:0 var(--header-padding)}.mobile-header .header-left label,.mobile-header .header-right label{height:100%;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:100%}.nav-overlay-icon .icon,.theme-toggle svg{height:1.25rem;width:1.25rem}:target{scroll-margin-top:var(--header-height)}.back-to-top{top:calc(var(--header-height) + .5rem)}.page{flex-direction:column;justify-content:center}.content{margin-left:auto;margin-right:auto}}@media(max-width:52em){.content{overflow-x:auto;width:100%}}@media(max-width:46em){.content{padding:0 1em}article aside.sidebar{float:none;margin:1rem 0;width:100%}}.admonition,.topic{background:var(--color-admonition-background);border-radius:.2rem;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1);font-size:var(--admonition-font-size);margin:1rem auto;overflow:hidden;padding:0 .5rem .5rem;page-break-inside:avoid}.admonition>:nth-child(2),.topic>:nth-child(2){margin-top:0}.admonition>:last-child,.topic>:last-child{margin-bottom:0}.admonition p.admonition-title,p.topic-title{font-size:var(--admonition-title-font-size);font-weight:500;line-height:1.3;margin:0 -.5rem .5rem;padding:.4rem .5rem .4rem 2rem;position:relative}.admonition p.admonition-title:before,p.topic-title:before{content:"";height:1rem;left:.5rem;position:absolute;width:1rem}p.admonition-title{background-color:var(--color-admonition-title-background)}p.admonition-title:before{background-color:var(--color-admonition-title);-webkit-mask-image:var(--icon-admonition-default);mask-image:var(--icon-admonition-default);-webkit-mask-repeat:no-repeat;mask-repeat:no-repeat}p.topic-title{background-color:var(--color-topic-title-background)}p.topic-title:before{background-color:var(--color-topic-title);-webkit-mask-image:var(--icon-topic-default);mask-image:var(--icon-topic-default);-webkit-mask-repeat:no-repeat;mask-repeat:no-repeat}.admonition{border-left:.2rem solid var(--color-admonition-title)}.admonition.caution{border-left-color:var(--color-admonition-title--caution)}.admonition.caution>.admonition-title{background-color:var(--color-admonition-title-background--caution)}.admonition.caution>.admonition-title:before{background-color:var(--color-admonition-title--caution);-webkit-mask-image:var(--icon-spark);mask-image:var(--icon-spark)}.admonition.warning{border-left-color:var(--color-admonition-title--warning)}.admonition.warning>.admonition-title{background-color:var(--color-admonition-title-background--warning)}.admonition.warning>.admonition-title:before{background-color:var(--color-admonition-title--warning);-webkit-mask-image:var(--icon-warning);mask-image:var(--icon-warning)}.admonition.danger{border-left-color:var(--color-admonition-title--danger)}.admonition.danger>.admonition-title{background-color:var(--color-admonition-title-background--danger)}.admonition.danger>.admonition-title:before{background-color:var(--color-admonition-title--danger);-webkit-mask-image:var(--icon-spark);mask-image:var(--icon-spark)}.admonition.attention{border-left-color:var(--color-admonition-title--attention)}.admonition.attention>.admonition-title{background-color:var(--color-admonition-title-background--attention)}.admonition.attention>.admonition-title:before{background-color:var(--color-admonition-title--attention);-webkit-mask-image:var(--icon-warning);mask-image:var(--icon-warning)}.admonition.error{border-left-color:var(--color-admonition-title--error)}.admonition.error>.admonition-title{background-color:var(--color-admonition-title-background--error)}.admonition.error>.admonition-title:before{background-color:var(--color-admonition-title--error);-webkit-mask-image:var(--icon-failure);mask-image:var(--icon-failure)}.admonition.hint{border-left-color:var(--color-admonition-title--hint)}.admonition.hint>.admonition-title{background-color:var(--color-admonition-title-background--hint)}.admonition.hint>.admonition-title:before{background-color:var(--color-admonition-title--hint);-webkit-mask-image:var(--icon-question);mask-image:var(--icon-question)}.admonition.tip{border-left-color:var(--color-admonition-title--tip)}.admonition.tip>.admonition-title{background-color:var(--color-admonition-title-background--tip)}.admonition.tip>.admonition-title:before{background-color:var(--color-admonition-title--tip);-webkit-mask-image:var(--icon-info);mask-image:var(--icon-info)}.admonition.important{border-left-color:var(--color-admonition-title--important)}.admonition.important>.admonition-title{background-color:var(--color-admonition-title-background--important)}.admonition.important>.admonition-title:before{background-color:var(--color-admonition-title--important);-webkit-mask-image:var(--icon-flame);mask-image:var(--icon-flame)}.admonition.note{border-left-color:var(--color-admonition-title--note)}.admonition.note>.admonition-title{background-color:var(--color-admonition-title-background--note)}.admonition.note>.admonition-title:before{background-color:var(--color-admonition-title--note);-webkit-mask-image:var(--icon-pencil);mask-image:var(--icon-pencil)}.admonition.seealso{border-left-color:var(--color-admonition-title--seealso)}.admonition.seealso>.admonition-title{background-color:var(--color-admonition-title-background--seealso)}.admonition.seealso>.admonition-title:before{background-color:var(--color-admonition-title--seealso);-webkit-mask-image:var(--icon-info);mask-image:var(--icon-info)}.admonition.admonition-todo{border-left-color:var(--color-admonition-title--admonition-todo)}.admonition.admonition-todo>.admonition-title{background-color:var(--color-admonition-title-background--admonition-todo)}.admonition.admonition-todo>.admonition-title:before{background-color:var(--color-admonition-title--admonition-todo);-webkit-mask-image:var(--icon-pencil);mask-image:var(--icon-pencil)}.admonition-todo>.admonition-title{text-transform:uppercase}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd{margin-left:2rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd>:first-child{margin-top:.125rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list,dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd>:last-child{margin-bottom:.75rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list>dt{font-size:var(--font-size--small);text-transform:uppercase}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd:empty{margin-bottom:.5rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd>ul{margin-left:-1.2rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd>ul>li>p:nth-child(2){margin-top:0}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd>ul>li>p+p:last-child:empty{margin-bottom:0;margin-top:0}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt{color:var(--color-api-overall)}.sig:not(.sig-inline){background:var(--color-api-background);border-radius:.25rem;font-family:var(--font-stack--monospace);font-size:var(--api-font-size);font-weight:700;margin-left:-.25rem;margin-right:-.25rem;padding:.25rem .5rem .25rem 3em;text-indent:-2.5em;transition:background .1s ease-out}.sig:not(.sig-inline):hover{background:var(--color-api-background-hover)}.sig:not(.sig-inline) a.reference .viewcode-link{font-weight:400;width:3.5rem}em.property{font-style:normal}em.property:first-child{color:var(--color-api-keyword)}.sig-name{color:var(--color-api-name)}.sig-prename{color:var(--color-api-pre-name);font-weight:400}.sig-paren{color:var(--color-api-paren)}.sig-param{font-style:normal}.versionmodified{font-style:italic}div.deprecated p,div.versionadded p,div.versionchanged p{margin-bottom:.125rem;margin-top:.125rem}.viewcode-back,.viewcode-link{float:right;text-align:right}.line-block{margin-bottom:.75rem;margin-top:.5rem}.line-block .line-block{margin-bottom:0;margin-top:0;padding-left:1rem}.code-block-caption,article p.caption,table>caption{font-size:var(--font-size--small);text-align:center}.toctree-wrapper.compound .caption,.toctree-wrapper.compound :not(.caption)>.caption-text{font-size:var(--font-size--small);margin-bottom:0;text-align:initial;text-transform:uppercase}.toctree-wrapper.compound>ul{margin-bottom:0;margin-top:0}.sig-inline,code.literal{background:var(--color-inline-code-background);border-radius:.2em;font-size:var(--font-size--small--2);padding:.1em .2em}pre.literal-block .sig-inline,pre.literal-block code.literal{font-size:inherit;padding:0}p .sig-inline,p code.literal{border:1px solid var(--color-background-border)}.sig-inline{font-family:var(--font-stack--monospace)}div[class*=" highlight-"],div[class^=highlight-]{display:flex;margin:1em 0}div[class*=" highlight-"] .table-wrapper,div[class^=highlight-] .table-wrapper,pre{margin:0;padding:0}pre{overflow:auto}article[role=main] .highlight pre{line-height:1.5}.highlight pre,pre.literal-block{font-size:var(--code-font-size);padding:.625rem .875rem}pre.literal-block{background-color:var(--color-code-background);border-radius:.2rem;color:var(--color-code-foreground);margin-bottom:1rem;margin-top:1rem}.highlight{border-radius:.2rem;width:100%}.highlight .gp,.highlight span.linenos{pointer-events:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}.highlight .hll{display:block;margin-left:-.875rem;margin-right:-.875rem;padding-left:.875rem;padding-right:.875rem}.code-block-caption{background-color:var(--color-code-background);border-bottom:1px solid;border-radius:.25rem;border-bottom-left-radius:0;border-bottom-right-radius:0;border-color:var(--color-background-border);color:var(--color-code-foreground);display:flex;font-weight:300;padding:.625rem .875rem}.code-block-caption+div[class]{margin-top:0}.code-block-caption+div[class] pre{border-top-left-radius:0;border-top-right-radius:0}.highlighttable{display:block;width:100%}.highlighttable tbody{display:block}.highlighttable tr{display:flex}.highlighttable td.linenos{background-color:var(--color-code-background);border-bottom-left-radius:.2rem;border-top-left-radius:.2rem;color:var(--color-code-foreground);padding:.625rem 0 .625rem .875rem}.highlighttable .linenodiv{box-shadow:-.0625rem 0 var(--color-foreground-border) inset;font-size:var(--code-font-size);padding-right:.875rem}.highlighttable td.code{display:block;flex:1;overflow:hidden;padding:0}.highlighttable td.code .highlight{border-bottom-left-radius:0;border-top-left-radius:0}.highlight span.linenos{box-shadow:-.0625rem 0 var(--color-foreground-border) inset;display:inline-block;margin-right:.875rem;padding-left:0;padding-right:.875rem}.footnote-reference{font-size:var(--font-size--small--4);vertical-align:super}dl.footnote.brackets{color:var(--color-foreground-secondary);display:grid;font-size:var(--font-size--small);grid-template-columns:max-content auto}dl.footnote.brackets dt{margin:0}dl.footnote.brackets dt>.fn-backref{margin-left:.25rem}dl.footnote.brackets dt:after{content:":"}dl.footnote.brackets dt .brackets:before{content:"["}dl.footnote.brackets dt .brackets:after{content:"]"}dl.footnote.brackets dd{margin:0;padding:0 1rem}aside.footnote{color:var(--color-foreground-secondary);font-size:var(--font-size--small)}aside.footnote>span,div.citation>span{float:left;font-weight:500;padding-right:.25rem}aside.footnote>p,div.citation>p{margin-left:2rem}img{box-sizing:border-box;height:auto;max-width:100%}article .figure,article figure{border-radius:.2rem;margin:0}article .figure :last-child,article figure :last-child{margin-bottom:0}article .align-left{clear:left;float:left;margin:0 1rem 1rem}article .align-right{clear:right;float:right;margin:0 1rem 1rem}article .align-center,article .align-default{display:block;margin-left:auto;margin-right:auto;text-align:center}article table.align-default{display:table;text-align:initial}.domainindex-jumpbox,.genindex-jumpbox{border-bottom:1px solid var(--color-background-border);border-top:1px solid var(--color-background-border);padding:.25rem}.domainindex-section h2,.genindex-section h2{margin-bottom:.5rem;margin-top:.75rem}.domainindex-section ul,.genindex-section ul{margin-bottom:0;margin-top:0}ol,ul{margin-bottom:1rem;margin-top:1rem;padding-left:1.2rem}ol li>p:first-child,ul li>p:first-child{margin-bottom:.25rem;margin-top:.25rem}ol li>p:last-child,ul li>p:last-child{margin-top:.25rem}ol li>ol,ol li>ul,ul li>ol,ul li>ul{margin-bottom:.5rem;margin-top:.5rem}ol.arabic{list-style:decimal}ol.loweralpha{list-style:lower-alpha}ol.upperalpha{list-style:upper-alpha}ol.lowerroman{list-style:lower-roman}ol.upperroman{list-style:upper-roman}.simple li>ol,.simple li>ul,.toctree-wrapper li>ol,.toctree-wrapper li>ul{margin-bottom:0;margin-top:0}.field-list dt,.option-list dt,dl.footnote dt,dl.glossary dt,dl.simple dt,dl:not([class]) dt{font-weight:500;margin-top:.25rem}.field-list dt+dt,.option-list dt+dt,dl.footnote dt+dt,dl.glossary dt+dt,dl.simple dt+dt,dl:not([class]) dt+dt{margin-top:0}.field-list dt .classifier:before,.option-list dt .classifier:before,dl.footnote dt .classifier:before,dl.glossary dt .classifier:before,dl.simple dt .classifier:before,dl:not([class]) dt .classifier:before{content:":";margin-left:.2rem;margin-right:.2rem}.field-list dd ul,.field-list dd>p:first-child,.option-list dd ul,.option-list dd>p:first-child,dl.footnote dd ul,dl.footnote dd>p:first-child,dl.glossary dd ul,dl.glossary dd>p:first-child,dl.simple dd ul,dl.simple dd>p:first-child,dl:not([class]) dd ul,dl:not([class]) dd>p:first-child{margin-top:.125rem}.field-list dd ul,.option-list dd ul,dl.footnote dd ul,dl.glossary dd ul,dl.simple dd ul,dl:not([class]) dd ul{margin-bottom:.125rem}.math-wrapper{overflow-x:auto;width:100%}div.math{position:relative;text-align:center}div.math .headerlink,div.math:focus .headerlink{display:none}div.math:hover .headerlink{display:inline-block}div.math span.eqno{position:absolute;right:.5rem;top:50%;transform:translateY(-50%);z-index:1}abbr[title]{cursor:help}.problematic{color:var(--color-problematic)}kbd:not(.compound){background-color:var(--color-background-secondary);border:1px solid var(--color-foreground-border);border-radius:.2rem;box-shadow:0 .0625rem 0 rgba(0,0,0,.2),inset 0 0 0 .125rem var(--color-background-primary);color:var(--color-foreground-primary);display:inline-block;font-size:var(--font-size--small--3);margin:0 .2rem;padding:0 .2rem;vertical-align:text-bottom}blockquote{background:var(--color-background-secondary);border-left:4px solid var(--color-background-border);margin-left:0;margin-right:0;padding:.5rem 1rem}blockquote .attribution{font-weight:600;text-align:right}blockquote.highlights,blockquote.pull-quote{font-size:1.25em}blockquote.epigraph,blockquote.pull-quote{border-left-width:0;border-radius:.5rem}blockquote.highlights{background:transparent;border-left-width:0}p .reference img{vertical-align:middle}p.rubric{font-size:1.125em;font-weight:700;line-height:1.25}dd p.rubric{font-size:var(--font-size--small);font-weight:inherit;line-height:inherit;text-transform:uppercase}article .sidebar{background-color:var(--color-background-secondary);border:1px solid var(--color-background-border);border-radius:.2rem;clear:right;float:right;margin-left:1rem;margin-right:0;width:30%}article .sidebar>*{padding-left:1rem;padding-right:1rem}article .sidebar>ol,article .sidebar>ul{padding-left:2.2rem}article .sidebar .sidebar-title{border-bottom:1px solid var(--color-background-border);font-weight:500;margin:0;padding:.5rem 1rem}.table-wrapper{margin-bottom:.5rem;margin-top:1rem;overflow-x:auto;padding:.2rem .2rem .75rem;width:100%}table.docutils{border-collapse:collapse;border-radius:.2rem;border-spacing:0;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1)}table.docutils th{background:var(--color-table-header-background)}table.docutils td,table.docutils th{border-bottom:1px solid var(--color-table-border);border-left:1px solid var(--color-table-border);border-right:1px solid var(--color-table-border);padding:0 .25rem}table.docutils td p,table.docutils th p{margin:.25rem}table.docutils td:first-child,table.docutils th:first-child{border-left:none}table.docutils td:last-child,table.docutils th:last-child{border-right:none}table.docutils td.text-left,table.docutils th.text-left{text-align:left}table.docutils td.text-right,table.docutils th.text-right{text-align:right}table.docutils td.text-center,table.docutils th.text-center{text-align:center}:target{scroll-margin-top:.5rem}@media(max-width:67em){:target{scroll-margin-top:calc(.5rem + var(--header-height))}section>span:target{scroll-margin-top:calc(.8rem + var(--header-height))}}.headerlink{font-weight:100;-webkit-user-select:none;-moz-user-select:none;user-select:none}.code-block-caption>.headerlink,dl dt>.headerlink,figcaption p>.headerlink,h1>.headerlink,h2>.headerlink,h3>.headerlink,h4>.headerlink,h5>.headerlink,h6>.headerlink,p.caption>.headerlink,table>caption>.headerlink{margin-left:.5rem;visibility:hidden}.code-block-caption:hover>.headerlink,dl dt:hover>.headerlink,figcaption p:hover>.headerlink,h1:hover>.headerlink,h2:hover>.headerlink,h3:hover>.headerlink,h4:hover>.headerlink,h5:hover>.headerlink,h6:hover>.headerlink,p.caption:hover>.headerlink,table>caption:hover>.headerlink{visibility:visible}.code-block-caption>.toc-backref,dl dt>.toc-backref,figcaption p>.toc-backref,h1>.toc-backref,h2>.toc-backref,h3>.toc-backref,h4>.toc-backref,h5>.toc-backref,h6>.toc-backref,p.caption>.toc-backref,table>caption>.toc-backref{color:inherit;text-decoration-line:none}figure:hover>figcaption>p>.headerlink,table:hover>caption>.headerlink{visibility:visible}:target>h1:first-of-type,:target>h2:first-of-type,:target>h3:first-of-type,:target>h4:first-of-type,:target>h5:first-of-type,:target>h6:first-of-type,span:target~h1:first-of-type,span:target~h2:first-of-type,span:target~h3:first-of-type,span:target~h4:first-of-type,span:target~h5:first-of-type,span:target~h6:first-of-type{background-color:var(--color-highlight-on-target)}:target>h1:first-of-type code.literal,:target>h2:first-of-type code.literal,:target>h3:first-of-type code.literal,:target>h4:first-of-type code.literal,:target>h5:first-of-type code.literal,:target>h6:first-of-type code.literal,span:target~h1:first-of-type code.literal,span:target~h2:first-of-type code.literal,span:target~h3:first-of-type code.literal,span:target~h4:first-of-type code.literal,span:target~h5:first-of-type code.literal,span:target~h6:first-of-type code.literal{background-color:transparent}.literal-block-wrapper:target .code-block-caption,.this-will-duplicate-information-and-it-is-still-useful-here li :target,figure:target,table:target>caption{background-color:var(--color-highlight-on-target)}dt:target{background-color:var(--color-highlight-on-target)!important}.footnote-reference:target,.footnote>dt:target+dd{background-color:var(--color-highlight-on-target)}.guilabel{background-color:var(--color-guilabel-background);border:1px solid var(--color-guilabel-border);border-radius:.5em;color:var(--color-guilabel-text);font-size:.9em;padding:0 .3em}footer{display:flex;flex-direction:column;font-size:var(--font-size--small);margin-top:2rem}.bottom-of-page{align-items:center;border-top:1px solid var(--color-background-border);color:var(--color-foreground-secondary);display:flex;justify-content:space-between;line-height:1.5;margin-top:1rem;padding-bottom:1rem;padding-top:1rem}@media(max-width:46em){.bottom-of-page{flex-direction:column-reverse;gap:.25rem;text-align:center}}.bottom-of-page .left-details{font-size:var(--font-size--small)}.bottom-of-page .right-details{display:flex;flex-direction:column;gap:.25rem;text-align:right}.bottom-of-page .icons{display:flex;font-size:1rem;gap:.25rem;justify-content:flex-end}.bottom-of-page .icons a{text-decoration:none}.bottom-of-page .icons img,.bottom-of-page .icons svg{font-size:1.125rem;height:1em;width:1em}.related-pages a{align-items:center;display:flex;text-decoration:none}.related-pages a:hover .page-info .title{color:var(--color-link);text-decoration:underline;text-decoration-color:var(--color-link-underline)}.related-pages a svg.furo-related-icon,.related-pages a svg.furo-related-icon>use{color:var(--color-foreground-border);flex-shrink:0;height:.75rem;margin:0 .5rem;width:.75rem}.related-pages a.next-page{clear:right;float:right;max-width:50%;text-align:right}.related-pages a.prev-page{clear:left;float:left;max-width:50%}.related-pages a.prev-page svg{transform:rotate(180deg)}.page-info{display:flex;flex-direction:column;overflow-wrap:anywhere}.next-page .page-info{align-items:flex-end}.page-info .context{align-items:center;color:var(--color-foreground-muted);display:flex;font-size:var(--font-size--small);padding-bottom:.1rem;text-decoration:none}ul.search{list-style:none;padding-left:0}ul.search li{border-bottom:1px solid var(--color-background-border);padding:1rem 0}[role=main] .highlighted{background-color:var(--color-highlighted-background);color:var(--color-highlighted-text)}.sidebar-brand{display:flex;flex-direction:column;flex-shrink:0;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);text-decoration:none}.sidebar-brand-text{color:var(--color-sidebar-brand-text);font-size:1.5rem;overflow-wrap:break-word}.sidebar-brand-text,.sidebar-logo-container{margin:var(--sidebar-item-spacing-vertical) 0}.sidebar-logo{display:block;margin:0 auto;max-width:100%}.sidebar-search-container{align-items:center;background:var(--color-sidebar-search-background);display:flex;margin-top:var(--sidebar-search-space-above);position:relative}.sidebar-search-container:focus-within,.sidebar-search-container:hover{background:var(--color-sidebar-search-background--focus)}.sidebar-search-container:before{background-color:var(--color-sidebar-search-icon);content:"";height:var(--sidebar-search-icon-size);left:var(--sidebar-item-spacing-horizontal);-webkit-mask-image:var(--icon-search);mask-image:var(--icon-search);position:absolute;width:var(--sidebar-search-icon-size)}.sidebar-search{background:transparent;border:none;border-bottom:1px solid var(--color-sidebar-search-border);border-top:1px solid var(--color-sidebar-search-border);box-sizing:border-box;color:var(--color-sidebar-search-foreground);padding:var(--sidebar-search-input-spacing-vertical) var(--sidebar-search-input-spacing-horizontal) var(--sidebar-search-input-spacing-vertical) calc(var(--sidebar-item-spacing-horizontal) + var(--sidebar-search-input-spacing-horizontal) + var(--sidebar-search-icon-size));width:100%;z-index:10}.sidebar-search:focus{outline:none}.sidebar-search::-moz-placeholder{font-size:var(--sidebar-search-input-font-size)}.sidebar-search::placeholder{font-size:var(--sidebar-search-input-font-size)}#searchbox .highlight-link{margin:0;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal) 0;text-align:center}#searchbox .highlight-link a{color:var(--color-sidebar-search-icon);font-size:var(--font-size--small--2)}.sidebar-tree{font-size:var(--sidebar-item-font-size);margin-bottom:var(--sidebar-item-spacing-vertical);margin-top:var(--sidebar-tree-space-above)}.sidebar-tree ul{display:flex;flex-direction:column;list-style:none;margin-bottom:0;margin-top:0;padding:0}.sidebar-tree li{margin:0;position:relative}.sidebar-tree li>ul{margin-left:var(--sidebar-item-spacing-horizontal)}.sidebar-tree .icon,.sidebar-tree .reference{color:var(--color-sidebar-link-text)}.sidebar-tree .reference{box-sizing:border-box;display:inline-block;height:100%;line-height:var(--sidebar-item-line-height);overflow-wrap:anywhere;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);text-decoration:none;width:100%}.sidebar-tree .reference:hover{background:var(--color-sidebar-item-background--hover)}.sidebar-tree .reference.external:after{color:var(--color-sidebar-link-text);content:url("data:image/svg+xml;charset=utf-8,%3Csvg width='12' height='12' xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' stroke-width='1.5' stroke='%23607D8B' fill='none' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M0 0h24v24H0z' stroke='none'/%3E%3Cpath d='M11 7H6a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h9a2 2 0 0 0 2-2v-5M10 14 20 4M15 4h5v5'/%3E%3C/svg%3E");margin:0 .25rem;vertical-align:middle}.sidebar-tree .current-page>.reference{font-weight:700}.sidebar-tree label{align-items:center;cursor:pointer;display:flex;height:var(--sidebar-item-height);justify-content:center;position:absolute;right:0;top:0;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:var(--sidebar-expander-width)}.sidebar-tree .caption,.sidebar-tree :not(.caption)>.caption-text{color:var(--color-sidebar-caption-text);font-size:var(--sidebar-caption-font-size);font-weight:700;margin:var(--sidebar-caption-space-above) 0 0 0;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);text-transform:uppercase}.sidebar-tree li.has-children>.reference{padding-right:var(--sidebar-expander-width)}.sidebar-tree .toctree-l1>.reference,.sidebar-tree .toctree-l1>label .icon{color:var(--color-sidebar-link-text--top-level)}.sidebar-tree label{background:var(--color-sidebar-item-expander-background)}.sidebar-tree label:hover{background:var(--color-sidebar-item-expander-background--hover)}.sidebar-tree .current>.reference{background:var(--color-sidebar-item-background--current)}.sidebar-tree .current>.reference:hover{background:var(--color-sidebar-item-background--hover)}.toctree-checkbox{display:none;position:absolute}.toctree-checkbox~ul{display:none}.toctree-checkbox~label .icon svg{transform:rotate(90deg)}.toctree-checkbox:checked~ul{display:block}.toctree-checkbox:checked~label .icon svg{transform:rotate(-90deg)}.toc-title-container{padding:var(--toc-title-padding);padding-top:var(--toc-spacing-vertical)}.toc-title{color:var(--color-toc-title-text);font-size:var(--toc-title-font-size);padding-left:var(--toc-spacing-horizontal);text-transform:uppercase}.no-toc{display:none}.toc-tree-container{padding-bottom:var(--toc-spacing-vertical)}.toc-tree{border-left:1px solid var(--color-background-border);font-size:var(--toc-font-size);line-height:1.3;padding-left:calc(var(--toc-spacing-horizontal) - var(--toc-item-spacing-horizontal))}.toc-tree>ul>li:first-child{padding-top:0}.toc-tree>ul>li:first-child>ul{padding-left:0}.toc-tree>ul>li:first-child>a{display:none}.toc-tree ul{list-style-type:none;margin-bottom:0;margin-top:0;padding-left:var(--toc-item-spacing-horizontal)}.toc-tree li{padding-top:var(--toc-item-spacing-vertical)}.toc-tree li.scroll-current>.reference{color:var(--color-toc-item-text--active);font-weight:700}.toc-tree .reference{color:var(--color-toc-item-text);overflow-wrap:anywhere;text-decoration:none}.toc-scroll{max-height:100vh;overflow-y:scroll}.contents:not(.this-will-duplicate-information-and-it-is-still-useful-here){background:rgba(255,0,0,.25);color:var(--color-problematic)}.contents:not(.this-will-duplicate-information-and-it-is-still-useful-here):before{content:"ERROR: Adding a table of contents in Furo-based documentation is unnecessary, and does not work well with existing styling.Add a 'this-will-duplicate-information-and-it-is-still-useful-here' class, if you want an escape hatch."}.text-align\:left>p{text-align:left}.text-align\:center>p{text-align:center}.text-align\:right>p{text-align:right} +/*# sourceMappingURL=furo.css.map*/ \ No newline at end of file diff --git a/_static/styles/furo.css.map b/_static/styles/furo.css.map new file mode 100644 index 0000000..1924b33 --- /dev/null +++ b/_static/styles/furo.css.map @@ -0,0 +1 @@ +{"version":3,"file":"styles/furo.css","mappings":"AAAA,2EAA2E,CAU3E,KAEE,6BAA8B,CAD9B,gBAEF,CASA,KACE,QACF,CAMA,KACE,aACF,CAOA,GACE,aAAc,CACd,cACF,CAUA,GACE,sBAAuB,CACvB,QAAS,CACT,gBACF,CAOA,IACE,+BAAiC,CACjC,aACF,CASA,EACE,4BACF,CAOA,YACE,kBAAmB,CACnB,yBAA0B,CAC1B,gCACF,CAMA,SAEE,kBACF,CAOA,cAGE,+BAAiC,CACjC,aACF,CAeA,QAEE,aAAc,CACd,aAAc,CACd,iBAAkB,CAClB,uBACF,CAEA,IACE,aACF,CAEA,IACE,SACF,CASA,IACE,iBACF,CAUA,sCAKE,mBAAoB,CACpB,cAAe,CACf,gBAAiB,CACjB,QACF,CAOA,aAEE,gBACF,CAOA,cAEE,mBACF,CAMA,gDAIE,yBACF,CAMA,wHAIE,iBAAkB,CAClB,SACF,CAMA,4GAIE,6BACF,CAMA,SACE,0BACF,CASA,OACE,qBAAsB,CACtB,aAAc,CACd,aAAc,CACd,cAAe,CACf,SAAU,CACV,kBACF,CAMA,SACE,uBACF,CAMA,SACE,aACF,CAOA,6BAEE,qBAAsB,CACtB,SACF,CAMA,kFAEE,WACF,CAOA,cACE,4BAA6B,CAC7B,mBACF,CAMA,yCACE,uBACF,CAOA,6BACE,yBAA0B,CAC1B,YACF,CASA,QACE,aACF,CAMA,QACE,iBACF,CAiBA,kBACE,YACF,CCvVA,aAcE,kEACE,uBAOF,WACE,iDAMF,gCACE,wBAEF,qCAEE,uBADA,uBACA,CAEF,SACE,wBAtBA,CCpBJ,iBAOE,6BAEA,mBANA,qBAEA,sBACA,0BAFA,oBAHA,4BAOA,6BANA,mBAOA,CAEF,gBACE,aCPF,KCGE,mHAEA,wGAGA,wBAAyB,CACzB,wBAAyB,CACzB,4BAA6B,CAC7B,yBAA0B,CAC1B,2BAA4B,CAG5B,sDAAuD,CACvD,gDAAiD,CACjD,wDAAyD,CAGzD,0CAA2C,CAC3C,gDAAiD,CACjD,gDAAiD,CAKjD,gCAAiC,CACjC,sCAAuC,CAGvC,2CAA4C,CAG5C,uCAAwC,CChCxC,+FAGA,uBAAwB,CAGxB,iCAAkC,CAClC,kCAAmC,CAEnC,+BAAgC,CAChC,sCAAuC,CACvC,sCAAuC,CACvC,qGAIA,mDAAoD,CAEpD,mCAAoC,CACpC,8CAA+C,CAC/C,gDAAiD,CACjD,kCAAmC,CACnC,6DAA8D,CAG9D,6BAA8B,CAC9B,6BAA8B,CAC9B,+BAAgC,CAChC,kCAAmC,CACnC,kCAAmC,CCPjC,ukBCYA,srCAZF,kaCVA,mLAOA,oTAWA,2UAaA,0CACA,gEACA,0CAGA,gEAUA,yCACA,+DAGA,4CACA,CACA,iEAGA,sGACA,uCACA,4DAGA,sCACA,2DAEA,4CACA,kEACA,oGACA,CAEA,0GACA,+CAGA,+MAOA,+EACA,wCAIA,4DACA,sEACA,kEACA,sEACA,gDAGA,+DACA,0CACA,gEACA,gGACA,CAGA,2DACA,qDAGA,0CACA,8CACA,oDACA,oDL7GF,iCAEA,iEAME,oCKyGA,yDAIA,sCACA,kCACA,sDAGA,0CACA,kEACA,oDAEA,sDAGA,oCACA,oEAIA,CAGA,yDAGA,qDACA,oDAGA,6DAIA,iEAGA,2DAEA,2DL9IE,4DAEA,gEAIF,gEKgGA,gFAIA,oNAOA,qDAEA,gFAIA,4DAIA,oEAMA,yEAIA,6DACA,0DAGA,uDAGA,qDAEA,wDLpII,6DAEA,yDACE,2DAMN,uCAIA,yCACE,8CAGF,sDMjDA,6DAKA,oCAIA,4CACA,kBAGF,sBAMA,2BAME,qCAGA,qCAEA,iCAEA,+BAEA,mCAEA,qCAIA,CACA,gCACA,gDAKA,kCAIA,6BAEA,0CAQA,kCAIF,8BAGE,8BACA,uCAGF,sCAKE,kCAEA,sDAGA,iCACE,CACA,2FAGA,gCACE,CACA,+DCzEJ,wCAEA,sBAEF,yDAEE,mCACA,wDAGA,2GAGA,wIACE,gDAMJ,kCAGE,6BACA,0CAGA,gEACA,8BACA,uCAKA,sCAIA,kCACA,sDACA,iCACA,sCAOA,sDAKE,gGAIE,+CAGN,sBAEE,yCAMA,0BAOA,yLAKA,aACA,MAEF,6BACE,mBAEA,wCAEF,wCAIE,kCAGA,SACA,kCAKA,mBAGA,CAJA,eACA,CAHF,gBAEE,CAWA,mBACA,mBACA,mDAIA,YACA,mBACA,CAEE,kBAMF,OAPE,kBAOF,oCACA,yCAEA,wBAEA,cADA,WACA,GACA,oBACA,CAFA,gBAEA,aAGF,+CAEE,UAJE,wBAEJ,CAFI,SAIF,CACA,2BACA,GAGA,uBACE,CAJF,yBAGA,CACE,iDACA,uCAEA,yDACE,cACA,wDAKN,yDAIE,uBAEF,kBACE,uBAEA,kDAKA,0DAEA,CAHA,oBAIA,0GAWA,aAEA,CAHA,YAGA,4HAKF,+CAGE,sBAEF,WAKE,0CAGA,CANA,qCAGA,CAJA,WAOA,SAIA,0CACE,CALF,qCAIA,CACE,wBAEA,mBAEJ,gBACE,gBAIA,+CAKF,CAIE,kDAEA,CANF,8BAIE,CAEA,YAGA,CAfF,2BACE,CAHA,UAEF,CAYE,UAGA,2CACF,iEAOE,iCACA,8BAGA,wCAIA,wBAMI,0CAKF,CATA,6DAGA,CALF,qBAEE,CASA,YACA,yBAGA,CAEE,cAKN,CAPI,sBAOJ,gCAGE,qBAEA,WACA,aACA,sCAEA,mBACA,6BAGA,uEADA,qBACA,6BAIA,yBACA,qCAEE,UAEA,YACA,sBAEF,8BAGA,CAPE,aACA,WAMF,4BACE,sBACA,WAMJ,uBACE,cAYE,mBAXA,qDAKA,qCAGA,CAEA,YACA,CAHA,2BAEA,CACA,oCAEA,4CACA,uBAIA,sBAEJ,eAFI,cAIF,iBACE,CAHJ,kBAGI,yBAEA,oCAIA,qDAMF,mEAGE,+CAKA,gCAEA,qCAGA,oCAGE,sBACA,CAJF,WAEE,CAFF,eAEE,SAEA,mBACA,qCACE,aACA,CAFF,YADA,qBACA,WAEE,sBACA,kEAEN,cAEE,CAFF,YAEE,iDAKA,uCAIA,2DAKA,kBAEA,CAHA,sBAGA,mBACA,0BAEJ,yBAII,aADA,WACA,CAMF,UAFE,kBAEF,CAJF,gBAEI,CAFJ,iBAIE,6CC9ZF,yBACE,WACA,iBAEA,aAFA,iBAEA,6BAEA,kCACA,mBAKA,gCAGA,CARA,QAEA,CAGA,UALA,qBAEA,qDAGA,CALA,OAQA,4BACE,cAGF,2BACE,gCAEJ,CAHE,UAGF,8CAGE,CAHF,UAGE,wCAGA,qBACA,CAFA,UAEA,6CAGA,yCAIA,sBAHA,UAGA,kCACE,OACA,CADA,KACA,cAQF,0CACE,CAFF,kBACA,CACE,wEACA,CARA,YACA,CAKF,mBAFF,MACE,CAIE,gBAJF,iCAJE,cAGJ,CANI,oBAEA,CAKF,SAIE,2BADA,UACA,kBAGF,sCACA,CAFF,WACE,WACA,mBACE,kDACA,0EACA,uDAKJ,aACE,mDAII,CAJJ,6CAII,4BACA,sCACE,kEACA,+CACE,aACA,WADA,+BACA,uEANN,YACE,mDAEE,mBADF,0CACE,CADF,qBACE,0DACA,YACE,4DACA,sEANN,YACE,8CACA,kBADA,UACA,2CACE,2EACA,cACE,kEACA,mEANN,yBACE,4DACA,sBACE,+EAEE,iEACA,qEANN,sCACE,CAGE,iBAHF,gBAGE,qBACE,CAJJ,uBACA,gDACE,wDACA,6DAHF,2CACA,CADA,gBACA,eACE,CAGE,sBANN,8BACE,CAII,iBAFF,4DACA,WACE,YADF,uCACE,6EACA,2BANN,8CACE,kDACA,0CACE,8BACA,yFACE,sBACA,sFALJ,mEACA,sBACE,kEACA,6EACE,uCACA,kEALJ,qGAEE,kEACA,6EACE,uCACA,kEALJ,8CACA,uDACE,sEACA,2EACE,sCACA,iEALJ,mGACA,qCACE,oDACA,0DACE,6GACA,gDAGR,yDCrEA,sEACE,CACA,6GACE,gEACF,iGAIF,wFACE,qDAGA,mGAEE,2CAEF,4FACE,gCACF,wGACE,8DAEE,6FAIA,iJAKN,6GACE,gDAKF,yDACA,qCAGA,6BACA,kBACA,qDAKA,oCAEA,+DAGA,2CAGE,oDAIA,oEAEE,qBAGJ,wDAEE,uCAEF,kEAGA,8CAEA,uDAKA,oCAEA,yDAEE,gEAKF,+CC5FA,0EAGE,CACA,qDCLJ,+DAIE,sCAIA,kEACE,yBACA,2FAMA,gBACA,yGCbF,mBAOA,2MAIA,4HAYA,0DACE,8GAYF,8HAQE,mBAEA,6HAOF,YAGA,mIAME,eACA,CAFF,YAEE,4FAMJ,8BAEE,uBAYA,sCAEE,CAJF,oBAEA,CARA,wCAEA,CAHA,8BACA,CAFA,eACA,CAGA,wCAEA,CAEA,mDAIE,kCACE,6BACA,4CAKJ,kDAIA,eACE,aAGF,8BACE,uDACA,sCACA,cAEA,+BACA,CAFA,eAEA,wCAEF,YACE,iBACA,mCACA,0DAGF,qBAEE,CAFF,kBAEE,+BAIA,yCAEE,qBADA,gBACA,yBAKF,eACA,CAFF,YACE,CACA,iBACA,qDAEA,mDCvIJ,2FAOE,iCACA,CAEA,eACA,CAHA,kBAEA,CAFA,wBAGA,8BACA,eACE,CAFF,YAEE,0BACA,8CAGA,oBACE,oCAGA,kBACE,8DAEA,iBAEN,UACE,8BAIJ,+CAEE,qDAEF,kDAIE,YAEF,CAFE,YAEF,CCjCE,mFAJA,QACA,UAIE,CADF,iBACE,mCAGA,iDACE,+BAGF,wBAEA,mBAKA,6CAEF,CAHE,mBACA,CAEF,kCAIE,CARA,kBACA,CAFF,eASE,YACA,mBAGF,CAJE,UAIF,wCCjCA,oBDmCE,wBCpCJ,uCACE,8BACA,4CACA,oBAGA,2CCAA,6CAGE,CAPF,uBAIA,CDGA,gDACE,6BCVJ,CAWM,2CAEF,CAJA,kCAEE,CDJF,aCLF,gBDKE,uBCMA,gCAGA,gDAGE,wBAGJ,0BAEA,iBACE,aACF,CADE,UACF,uBACE,aACF,oBACE,YACF,4BACE,6CAMA,CAYF,6DAZE,mCAGE,iCASJ,4BAGE,4DADA,+BACA,CAFA,qBAEA,yBACE,aAEF,wBAHA,SAGA,iHACE,2DAKF,CANA,yCACE,CADF,oCAMA,uSAIA,sGACE,oDChEJ,WAEF,yBACE,QACA,eAEA,gBAEE,uCAGA,CALF,iCAKE,uCAGA,0BACA,CACA,oBACA,iCClBJ,gBACE,KAGF,qBACE,YAGF,CAHE,cAGF,gCAEE,mBACA,iEAEA,oCACA,wCAEA,sBACA,WAEA,CAFA,YAEA,8EAEA,mCAFA,iBAEA,6BAIA,wEAKA,sDAIE,CARF,mDAIA,CAIE,cAEF,8CAIA,oBAFE,iBAEF,8CAGE,eAEF,CAFE,YAEF,OAEE,kBAGJ,CAJI,eACA,CAFF,mBAKF,yCCjDE,oBACA,CAFA,iBAEA,uCAKE,iBACA,qCAGA,mBCZJ,CDWI,gBCXJ,6BAEE,eACA,sBAGA,eAEA,sBACA,oDACA,iGAMA,gBAFE,YAEF,8FAME,iJClBF,YACA,gNAUE,6BAEF,oTAcI,kBACF,gHAIA,qBACE,eACF,qDACE,kBACF,6DACE,4BCxCJ,oBAEF,qCAEI,+CAGF,uBACE,uDAGJ,oBAkBE,mDAhBA,+CAaA,CAbA,oBAaA,0FAEE,CAFF,gGAbA,+BAaA,0BAGA,mQAIA,oNAEE,iBAGJ,CAHI,gBADA,gBAIJ,8CAYI,CAZJ,wCAYI,sVACE,iCAGA,uEAHA,QAGA,qXAKJ,iDAGF,CARM,+CACE,iDAIN,CALI,gBAQN,mHACE,gBAGF,2DACE,0EAOA,0EAKA,6EC/EA,iDACA,gCACA,oDAGA,qBACA,oDCFA,cACA,eAEA,yBAGF,sBAEE,iBACA,sNAWA,iBACE,kBACA,wRAgBA,kBAEA,iOAgBA,uCACE,uEAEA,kBAEF,qUAuBE,iDAIJ,CACA,geCxFF,4BAEE,CAQA,6JACA,iDAIA,sEAGA,mDAOF,iDAGE,4DAIA,8CACA,qDAEE,eAFF,cAEE,oBAEF,uBAFE,kCAGA,eACA,iBACA,mBAIA,mDACA,CAHA,uCAEA,CAJA,0CACA,CAIA,gBAJA,gBACA,oBADA,gBAIA,wBAEJ,gBAGE,6BACA,YAHA,iBAGA,gCACA,iEAEA,6CACA,sDACA,0BADA,wBACA,0BACA,oIAIA,mBAFA,YAEA,qBACA,0CAIE,uBAEF,CAHA,yBACE,CAEF,iDACE,mFAKJ,oCACE,CANE,aAKJ,CACE,qEAIA,YAFA,WAEA,CAHA,aACA,CAEA,gBACE,4BACA,sBADA,aACA,gCAMF,oCACA,yDACA,2CAEA,qBAGE,kBAEA,CACA,mCAIF,CARE,YACA,CAOF,iCAEE,CAPA,oBACA,CAQA,oBACE,uDAEJ,sDAGA,CAHA,cAGA,0BACE,oDAIA,oCACA,4BACA,sBAGA,cAEA,oFAGA,sBAEA,yDACE,CAIA,iBAJA,wBAIA,6CAJA,6CAOA,4BAGJ,CAHI,cAGJ,yCAGA,kBACE,CAIA,iDAEA,CATA,YAEF,CACE,4CAGA,kBAIA,wEAEA,wDAIF,kCAOE,iDACA,CARF,WAIE,sCAGA,CANA,2CACA,CAMA,oEARF,iBACE,CACA,qCAMA,iBAuBE,uBAlBF,YAKA,2DALA,uDAKA,CALA,sBAiBA,4CACE,CALA,gRAIF,YACE,UAEN,uBACE,YACA,mCAOE,+CAGA,8BAGF,+CAGA,4BCjNA,SDiNA,qFCjNA,gDAGA,sCACA,qCACA,sDAIF,CAIE,kDAGA,CAPF,0CAOE,kBAEA,kDAEA,CAHA,eACA,CAFA,YACA,CADA,SAIA,mHAIE,CAGA,6CAFA,oCAeE,CAbF,yBACE,qBAEJ,CAGE,oBACA,CAEA,YAFA,2CACF,CACE,uBAEA,mFAEE,CALJ,oBACE,CAEA,UAEE,gCAGF,sDAEA,yCC7CJ,oCAGA,CD6CE,yXAQE,sCCrDJ,wCAGA,oCACE","sources":["webpack:///./node_modules/normalize.css/normalize.css","webpack:///./src/furo/assets/styles/base/_print.sass","webpack:///./src/furo/assets/styles/base/_screen-readers.sass","webpack:///./src/furo/assets/styles/base/_theme.sass","webpack:///./src/furo/assets/styles/variables/_fonts.scss","webpack:///./src/furo/assets/styles/variables/_spacing.scss","webpack:///./src/furo/assets/styles/variables/_icons.scss","webpack:///./src/furo/assets/styles/variables/_admonitions.scss","webpack:///./src/furo/assets/styles/variables/_colors.scss","webpack:///./src/furo/assets/styles/base/_typography.sass","webpack:///./src/furo/assets/styles/_scaffold.sass","webpack:///./src/furo/assets/styles/content/_admonitions.sass","webpack:///./src/furo/assets/styles/content/_api.sass","webpack:///./src/furo/assets/styles/content/_blocks.sass","webpack:///./src/furo/assets/styles/content/_captions.sass","webpack:///./src/furo/assets/styles/content/_code.sass","webpack:///./src/furo/assets/styles/content/_footnotes.sass","webpack:///./src/furo/assets/styles/content/_images.sass","webpack:///./src/furo/assets/styles/content/_indexes.sass","webpack:///./src/furo/assets/styles/content/_lists.sass","webpack:///./src/furo/assets/styles/content/_math.sass","webpack:///./src/furo/assets/styles/content/_misc.sass","webpack:///./src/furo/assets/styles/content/_rubrics.sass","webpack:///./src/furo/assets/styles/content/_sidebar.sass","webpack:///./src/furo/assets/styles/content/_tables.sass","webpack:///./src/furo/assets/styles/content/_target.sass","webpack:///./src/furo/assets/styles/content/_gui-labels.sass","webpack:///./src/furo/assets/styles/components/_footer.sass","webpack:///./src/furo/assets/styles/components/_sidebar.sass","webpack:///./src/furo/assets/styles/components/_table_of_contents.sass","webpack:///./src/furo/assets/styles/_shame.sass"],"sourcesContent":["/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */\n\n/* Document\n ========================================================================== */\n\n/**\n * 1. Correct the line height in all browsers.\n * 2. Prevent adjustments of font size after orientation changes in iOS.\n */\n\nhtml {\n line-height: 1.15; /* 1 */\n -webkit-text-size-adjust: 100%; /* 2 */\n}\n\n/* Sections\n ========================================================================== */\n\n/**\n * Remove the margin in all browsers.\n */\n\nbody {\n margin: 0;\n}\n\n/**\n * Render the `main` element consistently in IE.\n */\n\nmain {\n display: block;\n}\n\n/**\n * Correct the font size and margin on `h1` elements within `section` and\n * `article` contexts in Chrome, Firefox, and Safari.\n */\n\nh1 {\n font-size: 2em;\n margin: 0.67em 0;\n}\n\n/* Grouping content\n ========================================================================== */\n\n/**\n * 1. Add the correct box sizing in Firefox.\n * 2. Show the overflow in Edge and IE.\n */\n\nhr {\n box-sizing: content-box; /* 1 */\n height: 0; /* 1 */\n overflow: visible; /* 2 */\n}\n\n/**\n * 1. Correct the inheritance and scaling of font size in all browsers.\n * 2. Correct the odd `em` font sizing in all browsers.\n */\n\npre {\n font-family: monospace, monospace; /* 1 */\n font-size: 1em; /* 2 */\n}\n\n/* Text-level semantics\n ========================================================================== */\n\n/**\n * Remove the gray background on active links in IE 10.\n */\n\na {\n background-color: transparent;\n}\n\n/**\n * 1. Remove the bottom border in Chrome 57-\n * 2. Add the correct text decoration in Chrome, Edge, IE, Opera, and Safari.\n */\n\nabbr[title] {\n border-bottom: none; /* 1 */\n text-decoration: underline; /* 2 */\n text-decoration: underline dotted; /* 2 */\n}\n\n/**\n * Add the correct font weight in Chrome, Edge, and Safari.\n */\n\nb,\nstrong {\n font-weight: bolder;\n}\n\n/**\n * 1. Correct the inheritance and scaling of font size in all browsers.\n * 2. Correct the odd `em` font sizing in all browsers.\n */\n\ncode,\nkbd,\nsamp {\n font-family: monospace, monospace; /* 1 */\n font-size: 1em; /* 2 */\n}\n\n/**\n * Add the correct font size in all browsers.\n */\n\nsmall {\n font-size: 80%;\n}\n\n/**\n * Prevent `sub` and `sup` elements from affecting the line height in\n * all browsers.\n */\n\nsub,\nsup {\n font-size: 75%;\n line-height: 0;\n position: relative;\n vertical-align: baseline;\n}\n\nsub {\n bottom: -0.25em;\n}\n\nsup {\n top: -0.5em;\n}\n\n/* Embedded content\n ========================================================================== */\n\n/**\n * Remove the border on images inside links in IE 10.\n */\n\nimg {\n border-style: none;\n}\n\n/* Forms\n ========================================================================== */\n\n/**\n * 1. Change the font styles in all browsers.\n * 2. Remove the margin in Firefox and Safari.\n */\n\nbutton,\ninput,\noptgroup,\nselect,\ntextarea {\n font-family: inherit; /* 1 */\n font-size: 100%; /* 1 */\n line-height: 1.15; /* 1 */\n margin: 0; /* 2 */\n}\n\n/**\n * Show the overflow in IE.\n * 1. Show the overflow in Edge.\n */\n\nbutton,\ninput { /* 1 */\n overflow: visible;\n}\n\n/**\n * Remove the inheritance of text transform in Edge, Firefox, and IE.\n * 1. Remove the inheritance of text transform in Firefox.\n */\n\nbutton,\nselect { /* 1 */\n text-transform: none;\n}\n\n/**\n * Correct the inability to style clickable types in iOS and Safari.\n */\n\nbutton,\n[type=\"button\"],\n[type=\"reset\"],\n[type=\"submit\"] {\n -webkit-appearance: button;\n}\n\n/**\n * Remove the inner border and padding in Firefox.\n */\n\nbutton::-moz-focus-inner,\n[type=\"button\"]::-moz-focus-inner,\n[type=\"reset\"]::-moz-focus-inner,\n[type=\"submit\"]::-moz-focus-inner {\n border-style: none;\n padding: 0;\n}\n\n/**\n * Restore the focus styles unset by the previous rule.\n */\n\nbutton:-moz-focusring,\n[type=\"button\"]:-moz-focusring,\n[type=\"reset\"]:-moz-focusring,\n[type=\"submit\"]:-moz-focusring {\n outline: 1px dotted ButtonText;\n}\n\n/**\n * Correct the padding in Firefox.\n */\n\nfieldset {\n padding: 0.35em 0.75em 0.625em;\n}\n\n/**\n * 1. Correct the text wrapping in Edge and IE.\n * 2. Correct the color inheritance from `fieldset` elements in IE.\n * 3. Remove the padding so developers are not caught out when they zero out\n * `fieldset` elements in all browsers.\n */\n\nlegend {\n box-sizing: border-box; /* 1 */\n color: inherit; /* 2 */\n display: table; /* 1 */\n max-width: 100%; /* 1 */\n padding: 0; /* 3 */\n white-space: normal; /* 1 */\n}\n\n/**\n * Add the correct vertical alignment in Chrome, Firefox, and Opera.\n */\n\nprogress {\n vertical-align: baseline;\n}\n\n/**\n * Remove the default vertical scrollbar in IE 10+.\n */\n\ntextarea {\n overflow: auto;\n}\n\n/**\n * 1. Add the correct box sizing in IE 10.\n * 2. Remove the padding in IE 10.\n */\n\n[type=\"checkbox\"],\n[type=\"radio\"] {\n box-sizing: border-box; /* 1 */\n padding: 0; /* 2 */\n}\n\n/**\n * Correct the cursor style of increment and decrement buttons in Chrome.\n */\n\n[type=\"number\"]::-webkit-inner-spin-button,\n[type=\"number\"]::-webkit-outer-spin-button {\n height: auto;\n}\n\n/**\n * 1. Correct the odd appearance in Chrome and Safari.\n * 2. Correct the outline style in Safari.\n */\n\n[type=\"search\"] {\n -webkit-appearance: textfield; /* 1 */\n outline-offset: -2px; /* 2 */\n}\n\n/**\n * Remove the inner padding in Chrome and Safari on macOS.\n */\n\n[type=\"search\"]::-webkit-search-decoration {\n -webkit-appearance: none;\n}\n\n/**\n * 1. Correct the inability to style clickable types in iOS and Safari.\n * 2. Change font properties to `inherit` in Safari.\n */\n\n::-webkit-file-upload-button {\n -webkit-appearance: button; /* 1 */\n font: inherit; /* 2 */\n}\n\n/* Interactive\n ========================================================================== */\n\n/*\n * Add the correct display in Edge, IE 10+, and Firefox.\n */\n\ndetails {\n display: block;\n}\n\n/*\n * Add the correct display in all browsers.\n */\n\nsummary {\n display: list-item;\n}\n\n/* Misc\n ========================================================================== */\n\n/**\n * Add the correct display in IE 10+.\n */\n\ntemplate {\n display: none;\n}\n\n/**\n * Add the correct display in IE 10.\n */\n\n[hidden] {\n display: none;\n}\n","// This file contains styles for managing print media.\n\n////////////////////////////////////////////////////////////////////////////////\n// Hide elements not relevant to print media.\n////////////////////////////////////////////////////////////////////////////////\n@media print\n // Hide icon container.\n .content-icon-container\n display: none !important\n\n // Hide showing header links if hovering over when printing.\n .headerlink\n display: none !important\n\n // Hide mobile header.\n .mobile-header\n display: none !important\n\n // Hide navigation links.\n .related-pages\n display: none !important\n\n////////////////////////////////////////////////////////////////////////////////\n// Tweaks related to decolorization.\n////////////////////////////////////////////////////////////////////////////////\n@media print\n // Apply a border around code which no longer have a color background.\n .highlight\n border: 0.1pt solid var(--color-foreground-border)\n\n////////////////////////////////////////////////////////////////////////////////\n// Avoid page break in some relevant cases.\n////////////////////////////////////////////////////////////////////////////////\n@media print\n ul, ol, dl, a, table, pre, blockquote\n page-break-inside: avoid\n\n h1, h2, h3, h4, h5, h6, img, figure, caption\n page-break-inside: avoid\n page-break-after: avoid\n\n ul, ol, dl\n page-break-before: avoid\n",".visually-hidden\n position: absolute !important\n width: 1px !important\n height: 1px !important\n padding: 0 !important\n margin: -1px !important\n overflow: hidden !important\n clip: rect(0,0,0,0) !important\n white-space: nowrap !important\n border: 0 !important\n\n:-moz-focusring\n outline: auto\n","// This file serves as the \"skeleton\" of the theming logic.\n//\n// This contains the bulk of the logic for handling dark mode, color scheme\n// toggling and the handling of color-scheme-specific hiding of elements.\n\nbody\n @include fonts\n @include spacing\n @include icons\n @include admonitions\n @include default-admonition(#651fff, \"abstract\")\n @include default-topic(#14B8A6, \"pencil\")\n\n @include colors\n\n.only-light\n display: block !important\nhtml body .only-dark\n display: none !important\n\n// Ignore dark-mode hints if print media.\n@media not print\n // Enable dark-mode, if requested.\n body[data-theme=\"dark\"]\n @include colors-dark\n\n html & .only-light\n display: none !important\n .only-dark\n display: block !important\n\n // Enable dark mode, unless explicitly told to avoid.\n @media (prefers-color-scheme: dark)\n body:not([data-theme=\"light\"])\n @include colors-dark\n\n html & .only-light\n display: none !important\n .only-dark\n display: block !important\n\n//\n// Theme toggle presentation\n//\nbody[data-theme=\"auto\"]\n .theme-toggle svg.theme-icon-when-auto\n display: block\n\nbody[data-theme=\"dark\"]\n .theme-toggle svg.theme-icon-when-dark\n display: block\n\nbody[data-theme=\"light\"]\n .theme-toggle svg.theme-icon-when-light\n display: block\n","// Fonts used by this theme.\n//\n// There are basically two things here -- using the system font stack and\n// defining sizes for various elements in %ages. We could have also used `em`\n// but %age is easier to reason about for me.\n\n@mixin fonts {\n // These are adapted from https://systemfontstack.com/\n --font-stack: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial,\n sans-serif, Apple Color Emoji, Segoe UI Emoji;\n --font-stack--monospace: \"SFMono-Regular\", Menlo, Consolas, Monaco,\n Liberation Mono, Lucida Console, monospace;\n\n --font-size--normal: 100%;\n --font-size--small: 87.5%;\n --font-size--small--2: 81.25%;\n --font-size--small--3: 75%;\n --font-size--small--4: 62.5%;\n\n // Sidebar\n --sidebar-caption-font-size: var(--font-size--small--2);\n --sidebar-item-font-size: var(--font-size--small);\n --sidebar-search-input-font-size: var(--font-size--small);\n\n // Table of Contents\n --toc-font-size: var(--font-size--small--3);\n --toc-font-size--mobile: var(--font-size--normal);\n --toc-title-font-size: var(--font-size--small--4);\n\n // Admonitions\n //\n // These aren't defined in terms of %ages, since nesting these is permitted.\n --admonition-font-size: 0.8125rem;\n --admonition-title-font-size: 0.8125rem;\n\n // Code\n --code-font-size: var(--font-size--small--2);\n\n // API\n --api-font-size: var(--font-size--small);\n}\n","// Spacing for various elements on the page\n//\n// If the user wants to tweak things in a certain way, they are permitted to.\n// They also have to deal with the consequences though!\n\n@mixin spacing {\n // Header!\n --header-height: calc(\n var(--sidebar-item-line-height) + 4 * #{var(--sidebar-item-spacing-vertical)}\n );\n --header-padding: 0.5rem;\n\n // Sidebar\n --sidebar-tree-space-above: 1.5rem;\n --sidebar-caption-space-above: 1rem;\n\n --sidebar-item-line-height: 1rem;\n --sidebar-item-spacing-vertical: 0.5rem;\n --sidebar-item-spacing-horizontal: 1rem;\n --sidebar-item-height: calc(\n var(--sidebar-item-line-height) + 2 *#{var(--sidebar-item-spacing-vertical)}\n );\n\n --sidebar-expander-width: var(--sidebar-item-height); // be square\n\n --sidebar-search-space-above: 0.5rem;\n --sidebar-search-input-spacing-vertical: 0.5rem;\n --sidebar-search-input-spacing-horizontal: 0.5rem;\n --sidebar-search-input-height: 1rem;\n --sidebar-search-icon-size: var(--sidebar-search-input-height);\n\n // Table of Contents\n --toc-title-padding: 0.25rem 0;\n --toc-spacing-vertical: 1.5rem;\n --toc-spacing-horizontal: 1.5rem;\n --toc-item-spacing-vertical: 0.4rem;\n --toc-item-spacing-horizontal: 1rem;\n}\n","// Expose theme icons as CSS variables.\n\n$icons: (\n // Adapted from tabler-icons\n // url: https://tablericons.com/\n \"search\":\n url('data:image/svg+xml;charset=utf-8,'),\n // Factored out from mkdocs-material on 24-Aug-2020.\n // url: https://squidfunk.github.io/mkdocs-material/reference/admonitions/\n \"pencil\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"abstract\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"info\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"flame\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"question\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"warning\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"failure\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"spark\":\n url('data:image/svg+xml;charset=utf-8,')\n);\n\n@mixin icons {\n @each $name, $glyph in $icons {\n --icon-#{$name}: #{$glyph};\n }\n}\n","// Admonitions\n\n// Structure of these is:\n// admonition-class: color \"icon-name\";\n//\n// The colors are translated into CSS variables below. The icons are\n// used directly in the main declarations to set the `mask-image` in\n// the title.\n\n// prettier-ignore\n$admonitions: (\n // Each of these has an reST directives for it.\n \"caution\": #ff9100 \"spark\",\n \"warning\": #ff9100 \"warning\",\n \"danger\": #ff5252 \"spark\",\n \"attention\": #ff5252 \"warning\",\n \"error\": #ff5252 \"failure\",\n \"hint\": #00c852 \"question\",\n \"tip\": #00c852 \"info\",\n \"important\": #00bfa5 \"flame\",\n \"note\": #00b0ff \"pencil\",\n \"seealso\": #448aff \"info\",\n \"admonition-todo\": #808080 \"pencil\"\n);\n\n@mixin default-admonition($color, $icon-name) {\n --color-admonition-title: #{$color};\n --color-admonition-title-background: #{rgba($color, 0.2)};\n\n --icon-admonition-default: var(--icon-#{$icon-name});\n}\n\n@mixin default-topic($color, $icon-name) {\n --color-topic-title: #{$color};\n --color-topic-title-background: #{rgba($color, 0.2)};\n\n --icon-topic-default: var(--icon-#{$icon-name});\n}\n\n@mixin admonitions {\n @each $name, $values in $admonitions {\n --color-admonition-title--#{$name}: #{nth($values, 1)};\n --color-admonition-title-background--#{$name}: #{rgba(\n nth($values, 1),\n 0.2\n )};\n }\n}\n","// Colors used throughout this theme.\n//\n// The aim is to give the user more control. Thus, instead of hard-coding colors\n// in various parts of the stylesheet, the approach taken is to define all\n// colors as CSS variables and reusing them in all the places.\n//\n// `colors-dark` depends on `colors` being included at a lower specificity.\n\n@mixin colors {\n --color-problematic: #b30000;\n\n // Base Colors\n --color-foreground-primary: black; // for main text and headings\n --color-foreground-secondary: #5a5c63; // for secondary text\n --color-foreground-muted: #646776; // for muted text\n --color-foreground-border: #878787; // for content borders\n\n --color-background-primary: white; // for content\n --color-background-secondary: #f8f9fb; // for navigation + ToC\n --color-background-hover: #efeff4ff; // for navigation-item hover\n --color-background-hover--transparent: #efeff400;\n --color-background-border: #eeebee; // for UI borders\n --color-background-item: #ccc; // for \"background\" items (eg: copybutton)\n\n // Announcements\n --color-announcement-background: #000000dd;\n --color-announcement-text: #eeebee;\n\n // Brand colors\n --color-brand-primary: #2962ff;\n --color-brand-content: #2a5adf;\n\n // API documentation\n --color-api-background: var(--color-background-hover--transparent);\n --color-api-background-hover: var(--color-background-hover);\n --color-api-overall: var(--color-foreground-secondary);\n --color-api-name: var(--color-problematic);\n --color-api-pre-name: var(--color-problematic);\n --color-api-paren: var(--color-foreground-secondary);\n --color-api-keyword: var(--color-foreground-primary);\n --color-highlight-on-target: #ffffcc;\n\n // Inline code background\n --color-inline-code-background: var(--color-background-secondary);\n\n // Highlighted text (search)\n --color-highlighted-background: #ddeeff;\n --color-highlighted-text: var(--color-foreground-primary);\n\n // GUI Labels\n --color-guilabel-background: #ddeeff80;\n --color-guilabel-border: #bedaf580;\n --color-guilabel-text: var(--color-foreground-primary);\n\n // Admonitions!\n --color-admonition-background: transparent;\n\n //////////////////////////////////////////////////////////////////////////////\n // Everything below this should be one of:\n // - var(...)\n // - *-gradient(...)\n // - special literal values (eg: transparent, none)\n //////////////////////////////////////////////////////////////////////////////\n\n // Tables\n --color-table-header-background: var(--color-background-secondary);\n --color-table-border: var(--color-background-border);\n\n // Cards\n --color-card-border: var(--color-background-secondary);\n --color-card-background: transparent;\n --color-card-marginals-background: var(--color-background-secondary);\n\n // Header\n --color-header-background: var(--color-background-primary);\n --color-header-border: var(--color-background-border);\n --color-header-text: var(--color-foreground-primary);\n\n // Sidebar (left)\n --color-sidebar-background: var(--color-background-secondary);\n --color-sidebar-background-border: var(--color-background-border);\n\n --color-sidebar-brand-text: var(--color-foreground-primary);\n --color-sidebar-caption-text: var(--color-foreground-muted);\n --color-sidebar-link-text: var(--color-foreground-secondary);\n --color-sidebar-link-text--top-level: var(--color-brand-primary);\n\n --color-sidebar-item-background: var(--color-sidebar-background);\n --color-sidebar-item-background--current: var(\n --color-sidebar-item-background\n );\n --color-sidebar-item-background--hover: linear-gradient(\n 90deg,\n var(--color-background-hover--transparent) 0%,\n var(--color-background-hover) var(--sidebar-item-spacing-horizontal),\n var(--color-background-hover) 100%\n );\n\n --color-sidebar-item-expander-background: transparent;\n --color-sidebar-item-expander-background--hover: var(\n --color-background-hover\n );\n\n --color-sidebar-search-text: var(--color-foreground-primary);\n --color-sidebar-search-background: var(--color-background-secondary);\n --color-sidebar-search-background--focus: var(--color-background-primary);\n --color-sidebar-search-border: var(--color-background-border);\n --color-sidebar-search-icon: var(--color-foreground-muted);\n\n // Table of Contents (right)\n --color-toc-background: var(--color-background-primary);\n --color-toc-title-text: var(--color-foreground-muted);\n --color-toc-item-text: var(--color-foreground-secondary);\n --color-toc-item-text--hover: var(--color-foreground-primary);\n --color-toc-item-text--active: var(--color-brand-primary);\n\n // Actual page contents\n --color-content-foreground: var(--color-foreground-primary);\n --color-content-background: transparent;\n\n // Links\n --color-link: var(--color-brand-content);\n --color-link--hover: var(--color-brand-content);\n --color-link-underline: var(--color-background-border);\n --color-link-underline--hover: var(--color-foreground-border);\n}\n\n@mixin colors-dark {\n --color-problematic: #ee5151;\n\n // Base Colors\n --color-foreground-primary: #ffffffcc; // for main text and headings\n --color-foreground-secondary: #9ca0a5; // for secondary text\n --color-foreground-muted: #81868d; // for muted text\n --color-foreground-border: #666666; // for content borders\n\n --color-background-primary: #131416; // for content\n --color-background-secondary: #1a1c1e; // for navigation + ToC\n --color-background-hover: #1e2124ff; // for navigation-item hover\n --color-background-hover--transparent: #1e212400;\n --color-background-border: #303335; // for UI borders\n --color-background-item: #444; // for \"background\" items (eg: copybutton)\n\n // Announcements\n --color-announcement-background: #000000dd;\n --color-announcement-text: #eeebee;\n\n // Brand colors\n --color-brand-primary: #2b8cee;\n --color-brand-content: #368ce2;\n\n // Highlighted text (search)\n --color-highlighted-background: #083563;\n\n // GUI Labels\n --color-guilabel-background: #08356380;\n --color-guilabel-border: #13395f80;\n\n // API documentation\n --color-api-keyword: var(--color-foreground-secondary);\n --color-highlight-on-target: #333300;\n\n // Admonitions\n --color-admonition-background: #18181a;\n\n // Cards\n --color-card-border: var(--color-background-secondary);\n --color-card-background: #18181a;\n --color-card-marginals-background: var(--color-background-hover);\n}\n","// This file contains the styling for making the content throughout the page,\n// including fonts, paragraphs, headings and spacing among these elements.\n\nbody\n font-family: var(--font-stack)\npre,\ncode,\nkbd,\nsamp\n font-family: var(--font-stack--monospace)\n\n// Make fonts look slightly nicer.\nbody\n -webkit-font-smoothing: antialiased\n -moz-osx-font-smoothing: grayscale\n\n// Line height from Bootstrap 4.1\narticle\n line-height: 1.5\n\n//\n// Headings\n//\nh1,\nh2,\nh3,\nh4,\nh5,\nh6\n line-height: 1.25\n font-weight: bold\n\n border-radius: 0.5rem\n margin-top: 0.5rem\n margin-bottom: 0.5rem\n margin-left: -0.5rem\n margin-right: -0.5rem\n padding-left: 0.5rem\n padding-right: 0.5rem\n\n + p\n margin-top: 0\n\nh1\n font-size: 2.5em\n margin-top: 1.75rem\n margin-bottom: 1rem\nh2\n font-size: 2em\n margin-top: 1.75rem\nh3\n font-size: 1.5em\nh4\n font-size: 1.25em\nh5\n font-size: 1.125em\nh6\n font-size: 1em\n\nsmall\n opacity: 75%\n font-size: 80%\n\n// Paragraph\np\n margin-top: 0.5rem\n margin-bottom: 0.75rem\n\n// Horizontal rules\nhr.docutils\n height: 1px\n padding: 0\n margin: 2rem 0\n background-color: var(--color-background-border)\n border: 0\n\n.centered\n text-align: center\n\n// Links\na\n text-decoration: underline\n\n color: var(--color-link)\n text-decoration-color: var(--color-link-underline)\n\n &:hover\n color: var(--color-link--hover)\n text-decoration-color: var(--color-link-underline--hover)\n &.muted-link\n color: inherit\n &:hover\n color: var(--color-link)\n text-decoration-color: var(--color-link-underline--hover)\n","// This file contains the styles for the overall layouting of the documentation\n// skeleton, including the responsive changes as well as sidebar toggles.\n//\n// This is implemented as a mobile-last design, which isn't ideal, but it is\n// reasonably good-enough and I got pretty tired by the time I'd finished this\n// to move the rules around to fix this. Shouldn't take more than 3-4 hours,\n// if you know what you're doing tho.\n\n// HACK: Not all browsers account for the scrollbar width in media queries.\n// This results in horizontal scrollbars in the breakpoint where we go\n// from displaying everything to hiding the ToC. We accomodate for this by\n// adding a bit of padding to the TOC drawer, disabling the horizontal\n// scrollbar and allowing the scrollbars to cover the padding.\n// https://www.456bereastreet.com/archive/201301/media_query_width_and_vertical_scrollbars/\n\n// HACK: Always having the scrollbar visible, prevents certain browsers from\n// causing the content to stutter horizontally between taller-than-viewport and\n// not-taller-than-viewport pages.\n\nhtml\n overflow-x: hidden\n overflow-y: scroll\n scroll-behavior: smooth\n\n.sidebar-scroll, .toc-scroll, article[role=main] *\n // Override Firefox scrollbar style\n scrollbar-width: thin\n scrollbar-color: var(--color-foreground-border) transparent\n\n // Override Chrome scrollbar styles\n &::-webkit-scrollbar\n width: 0.25rem\n height: 0.25rem\n &::-webkit-scrollbar-thumb\n background-color: var(--color-foreground-border)\n border-radius: 0.125rem\n\n//\n// Overalls\n//\nhtml,\nbody\n height: 100%\n color: var(--color-foreground-primary)\n background: var(--color-background-primary)\n\narticle\n color: var(--color-content-foreground)\n background: var(--color-content-background)\n overflow-wrap: break-word\n\n.page\n display: flex\n // fill the viewport for pages with little content.\n min-height: 100%\n\n.mobile-header\n width: 100%\n height: var(--header-height)\n background-color: var(--color-header-background)\n color: var(--color-header-text)\n border-bottom: 1px solid var(--color-header-border)\n\n // Looks like sub-script/super-script have this, and we need this to\n // be \"on top\" of those.\n z-index: 10\n\n // We don't show the header on large screens.\n display: none\n\n // Add shadow when scrolled\n &.scrolled\n border-bottom: none\n box-shadow: 0 0 0.2rem rgba(0, 0, 0, 0.1), 0 0.2rem 0.4rem rgba(0, 0, 0, 0.2)\n\n .header-center\n a\n color: var(--color-header-text)\n text-decoration: none\n\n.main\n display: flex\n flex: 1\n\n// Sidebar (left) also covers the entire left portion of screen.\n.sidebar-drawer\n box-sizing: border-box\n\n border-right: 1px solid var(--color-sidebar-background-border)\n background: var(--color-sidebar-background)\n\n display: flex\n justify-content: flex-end\n // These next two lines took me two days to figure out.\n width: calc((100% - #{$full-width}) / 2 + #{$sidebar-width})\n min-width: $sidebar-width\n\n// Scroll-along sidebars\n.sidebar-container,\n.toc-drawer\n box-sizing: border-box\n width: $sidebar-width\n\n.toc-drawer\n background: var(--color-toc-background)\n // See HACK described on top of this document\n padding-right: 1rem\n\n.sidebar-sticky,\n.toc-sticky\n position: sticky\n top: 0\n height: min(100%, 100vh)\n height: 100vh\n\n display: flex\n flex-direction: column\n\n.sidebar-scroll,\n.toc-scroll\n flex-grow: 1\n flex-shrink: 1\n\n overflow: auto\n scroll-behavior: smooth\n\n// Central items.\n.content\n padding: 0 $content-padding\n width: $content-width\n\n display: flex\n flex-direction: column\n justify-content: space-between\n\n.icon\n display: inline-block\n height: 1rem\n width: 1rem\n svg\n width: 100%\n height: 100%\n\n//\n// Accommodate announcement banner\n//\n.announcement\n background-color: var(--color-announcement-background)\n color: var(--color-announcement-text)\n\n height: var(--header-height)\n display: flex\n align-items: center\n overflow-x: auto\n & + .page\n min-height: calc(100% - var(--header-height))\n\n.announcement-content\n box-sizing: border-box\n padding: 0.5rem\n min-width: 100%\n white-space: nowrap\n text-align: center\n\n a\n color: var(--color-announcement-text)\n text-decoration-color: var(--color-announcement-text)\n\n &:hover\n color: var(--color-announcement-text)\n text-decoration-color: var(--color-link--hover)\n\n////////////////////////////////////////////////////////////////////////////////\n// Toggles for theme\n////////////////////////////////////////////////////////////////////////////////\n.no-js .theme-toggle-container // don't show theme toggle if there's no JS\n display: none\n\n.theme-toggle-container\n vertical-align: middle\n\n.theme-toggle\n cursor: pointer\n border: none\n padding: 0\n background: transparent\n\n.theme-toggle svg\n vertical-align: middle\n height: 1rem\n width: 1rem\n color: var(--color-foreground-primary)\n display: none\n\n.theme-toggle-header\n float: left\n padding: 1rem 0.5rem\n\n////////////////////////////////////////////////////////////////////////////////\n// Toggles for elements\n////////////////////////////////////////////////////////////////////////////////\n.toc-overlay-icon, .nav-overlay-icon\n display: none\n cursor: pointer\n\n .icon\n color: var(--color-foreground-secondary)\n height: 1rem\n width: 1rem\n\n.toc-header-icon, .nav-overlay-icon\n // for when we set display: flex\n justify-content: center\n align-items: center\n\n.toc-content-icon\n height: 1.5rem\n width: 1.5rem\n\n.content-icon-container\n float: right\n display: flex\n margin-top: 1.5rem\n margin-left: 1rem\n margin-bottom: 1rem\n gap: 0.5rem\n\n .edit-this-page svg\n color: inherit\n height: 1rem\n width: 1rem\n\n.sidebar-toggle\n position: absolute\n display: none\n// \n.sidebar-toggle[name=\"__toc\"]\n left: 20px\n.sidebar-toggle:checked\n left: 40px\n// \n\n.overlay\n position: fixed\n top: 0\n width: 0\n height: 0\n\n transition: width 0ms, height 0ms, opacity 250ms ease-out\n\n opacity: 0\n background-color: rgba(0, 0, 0, 0.54)\n.sidebar-overlay\n z-index: 20\n.toc-overlay\n z-index: 40\n\n// Keep things on top and smooth.\n.sidebar-drawer\n z-index: 30\n transition: left 250ms ease-in-out\n.toc-drawer\n z-index: 50\n transition: right 250ms ease-in-out\n\n// Show the Sidebar\n#__navigation:checked\n & ~ .sidebar-overlay\n width: 100%\n height: 100%\n opacity: 1\n & ~ .page\n .sidebar-drawer\n top: 0\n left: 0\n // Show the toc sidebar\n#__toc:checked\n & ~ .toc-overlay\n width: 100%\n height: 100%\n opacity: 1\n & ~ .page\n .toc-drawer\n top: 0\n right: 0\n\n////////////////////////////////////////////////////////////////////////////////\n// Back to top\n////////////////////////////////////////////////////////////////////////////////\n.back-to-top\n text-decoration: none\n\n display: none\n position: fixed\n left: 0\n top: 1rem\n padding: 0.5rem\n padding-right: 0.75rem\n border-radius: 1rem\n font-size: 0.8125rem\n\n background: var(--color-background-primary)\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), #6b728080 0px 0px 1px 0px\n\n z-index: 10\n\n margin-left: 50%\n transform: translateX(-50%)\n svg\n height: 1rem\n width: 1rem\n fill: currentColor\n display: inline-block\n\n span\n margin-left: 0.25rem\n\n .show-back-to-top &\n display: flex\n align-items: center\n\n////////////////////////////////////////////////////////////////////////////////\n// Responsive layouting\n////////////////////////////////////////////////////////////////////////////////\n// Make things a bit bigger on bigger screens.\n@media (min-width: $full-width + $sidebar-width)\n html\n font-size: 110%\n\n@media (max-width: $full-width)\n // Collapse \"toc\" into the icon.\n .toc-content-icon\n display: flex\n .toc-drawer\n position: fixed\n height: 100vh\n top: 0\n right: -$sidebar-width\n border-left: 1px solid var(--color-background-muted)\n .toc-tree\n border-left: none\n font-size: var(--toc-font-size--mobile)\n\n // Accomodate for a changed content width.\n .sidebar-drawer\n width: calc((100% - #{$full-width - $sidebar-width}) / 2 + #{$sidebar-width})\n\n@media (max-width: $full-width - $sidebar-width)\n // Collapse \"navigation\".\n .nav-overlay-icon\n display: flex\n .sidebar-drawer\n position: fixed\n height: 100vh\n width: $sidebar-width\n\n top: 0\n left: -$sidebar-width\n\n // Swap which icon is visible.\n .toc-header-icon\n display: flex\n .toc-content-icon, .theme-toggle-content\n display: none\n .theme-toggle-header\n display: block\n\n // Show the header.\n .mobile-header\n position: sticky\n top: 0\n display: flex\n justify-content: space-between\n align-items: center\n\n .header-left,\n .header-right\n display: flex\n height: var(--header-height)\n padding: 0 var(--header-padding)\n label\n height: 100%\n width: 100%\n user-select: none\n\n .nav-overlay-icon .icon,\n .theme-toggle svg\n height: 1.25rem\n width: 1.25rem\n\n // Add a scroll margin for the content\n :target\n scroll-margin-top: var(--header-height)\n\n // Show back-to-top below the header\n .back-to-top\n top: calc(var(--header-height) + 0.5rem)\n\n // Center the page, and accommodate for the header.\n .page\n flex-direction: column\n justify-content: center\n .content\n margin-left: auto\n margin-right: auto\n\n@media (max-width: $content-width + 2* $content-padding)\n // Content should respect window limits.\n .content\n width: 100%\n overflow-x: auto\n\n@media (max-width: $content-width)\n .content\n padding: 0 $content-padding--small\n // Don't float sidebars to the right.\n article aside.sidebar\n float: none\n width: 100%\n margin: 1rem 0\n","//\n// The design here is strongly inspired by mkdocs-material.\n.admonition, .topic\n margin: 1rem auto\n padding: 0 0.5rem 0.5rem 0.5rem\n\n background: var(--color-admonition-background)\n\n border-radius: 0.2rem\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), 0 0 0.0625rem rgba(0, 0, 0, 0.1)\n\n font-size: var(--admonition-font-size)\n\n overflow: hidden\n page-break-inside: avoid\n\n // First element should have no margin, since the title has it.\n > :nth-child(2)\n margin-top: 0\n\n // Last item should have no margin, since we'll control that w/ padding\n > :last-child\n margin-bottom: 0\n\n.admonition p.admonition-title,\np.topic-title\n position: relative\n margin: 0 -0.5rem 0.5rem\n padding-left: 2rem\n padding-right: .5rem\n padding-top: .4rem\n padding-bottom: .4rem\n\n font-weight: 500\n font-size: var(--admonition-title-font-size)\n line-height: 1.3\n\n // Our fancy icon\n &::before\n content: \"\"\n position: absolute\n left: 0.5rem\n width: 1rem\n height: 1rem\n\n// Default styles\np.admonition-title\n background-color: var(--color-admonition-title-background)\n &::before\n background-color: var(--color-admonition-title)\n mask-image: var(--icon-admonition-default)\n mask-repeat: no-repeat\n\np.topic-title\n background-color: var(--color-topic-title-background)\n &::before\n background-color: var(--color-topic-title)\n mask-image: var(--icon-topic-default)\n mask-repeat: no-repeat\n\n//\n// Variants\n//\n.admonition\n border-left: 0.2rem solid var(--color-admonition-title)\n\n @each $type, $value in $admonitions\n &.#{$type}\n border-left-color: var(--color-admonition-title--#{$type})\n > .admonition-title\n background-color: var(--color-admonition-title-background--#{$type})\n &::before\n background-color: var(--color-admonition-title--#{$type})\n mask-image: var(--icon-#{nth($value, 2)})\n\n.admonition-todo > .admonition-title\n text-transform: uppercase\n","// This file stylizes the API documentation (stuff generated by autodoc). It's\n// deeply nested due to how autodoc structures the HTML without enough classes\n// to select the relevant items.\n\n// API docs!\ndl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)\n // Tweak the spacing of all the things!\n dd\n margin-left: 2rem\n > :first-child\n margin-top: 0.125rem\n > :last-child\n margin-bottom: 0.75rem\n\n // This is used for the arguments\n .field-list\n margin-bottom: 0.75rem\n\n // \"Headings\" (like \"Parameters\" and \"Return\")\n > dt\n text-transform: uppercase\n font-size: var(--font-size--small)\n\n dd:empty\n margin-bottom: 0.5rem\n dd > ul\n margin-left: -1.2rem\n > li\n > p:nth-child(2)\n margin-top: 0\n // When the last-empty-paragraph follows a paragraph, it doesn't need\n // to augument the existing spacing.\n > p + p:last-child:empty\n margin-top: 0\n margin-bottom: 0\n\n // Colorize the elements\n > dt\n color: var(--color-api-overall)\n\n.sig:not(.sig-inline)\n font-weight: bold\n\n font-size: var(--api-font-size)\n font-family: var(--font-stack--monospace)\n\n margin-left: -0.25rem\n margin-right: -0.25rem\n padding-top: 0.25rem\n padding-bottom: 0.25rem\n padding-right: 0.5rem\n\n // These are intentionally em, to properly match the font size.\n padding-left: 3em\n text-indent: -2.5em\n\n border-radius: 0.25rem\n\n background: var(--color-api-background)\n transition: background 100ms ease-out\n\n &:hover\n background: var(--color-api-background-hover)\n\n // adjust the size of the [source] link on the right.\n a.reference\n .viewcode-link\n font-weight: normal\n width: 3.5rem\n\nem.property\n font-style: normal\n &:first-child\n color: var(--color-api-keyword)\n.sig-name\n color: var(--color-api-name)\n.sig-prename\n font-weight: normal\n color: var(--color-api-pre-name)\n.sig-paren\n color: var(--color-api-paren)\n.sig-param\n font-style: normal\n\n.versionmodified\n font-style: italic\ndiv.versionadded, div.versionchanged, div.deprecated\n p\n margin-top: 0.125rem\n margin-bottom: 0.125rem\n\n// Align the [docs] and [source] to the right.\n.viewcode-link, .viewcode-back\n float: right\n text-align: right\n",".line-block\n margin-top: 0.5rem\n margin-bottom: 0.75rem\n .line-block\n margin-top: 0rem\n margin-bottom: 0rem\n padding-left: 1rem\n","// Captions\narticle p.caption,\ntable > caption,\n.code-block-caption\n font-size: var(--font-size--small)\n text-align: center\n\n// Caption above a TOCTree\n.toctree-wrapper.compound\n .caption, :not(.caption) > .caption-text\n font-size: var(--font-size--small)\n text-transform: uppercase\n\n text-align: initial\n margin-bottom: 0\n\n > ul\n margin-top: 0\n margin-bottom: 0\n","// Inline code\ncode.literal, .sig-inline\n background: var(--color-inline-code-background)\n border-radius: 0.2em\n // Make the font smaller, and use padding to recover.\n font-size: var(--font-size--small--2)\n padding: 0.1em 0.2em\n\n pre.literal-block &\n font-size: inherit\n padding: 0\n\n p &\n border: 1px solid var(--color-background-border)\n\n.sig-inline\n font-family: var(--font-stack--monospace)\n\n// Code and Literal Blocks\n$code-spacing-vertical: 0.625rem\n$code-spacing-horizontal: 0.875rem\n\n// Wraps every literal block + line numbers.\ndiv[class*=\" highlight-\"],\ndiv[class^=\"highlight-\"]\n margin: 1em 0\n display: flex\n\n .table-wrapper\n margin: 0\n padding: 0\n\npre\n margin: 0\n padding: 0\n overflow: auto\n\n // Needed to have more specificity than pygments' \"pre\" selector. :(\n article[role=\"main\"] .highlight &\n line-height: 1.5\n\n &.literal-block,\n .highlight &\n font-size: var(--code-font-size)\n padding: $code-spacing-vertical $code-spacing-horizontal\n\n // Make it look like all the other blocks.\n &.literal-block\n margin-top: 1rem\n margin-bottom: 1rem\n\n border-radius: 0.2rem\n background-color: var(--color-code-background)\n color: var(--color-code-foreground)\n\n// All code is always contained in this.\n.highlight\n width: 100%\n border-radius: 0.2rem\n\n // Make line numbers and prompts un-selectable.\n .gp, span.linenos\n user-select: none\n pointer-events: none\n\n // Expand the line-highlighting.\n .hll\n display: block\n margin-left: -$code-spacing-horizontal\n margin-right: -$code-spacing-horizontal\n padding-left: $code-spacing-horizontal\n padding-right: $code-spacing-horizontal\n\n/* Make code block captions be nicely integrated */\n.code-block-caption\n display: flex\n padding: $code-spacing-vertical $code-spacing-horizontal\n\n border-radius: 0.25rem\n border-bottom-left-radius: 0\n border-bottom-right-radius: 0\n font-weight: 300\n border-bottom: 1px solid\n\n background-color: var(--color-code-background)\n color: var(--color-code-foreground)\n border-color: var(--color-background-border)\n\n + div[class]\n margin-top: 0\n pre\n border-top-left-radius: 0\n border-top-right-radius: 0\n\n// When `html_codeblock_linenos_style` is table.\n.highlighttable\n width: 100%\n display: block\n tbody\n display: block\n\n tr\n display: flex\n\n // Line numbers\n td.linenos\n background-color: var(--color-code-background)\n color: var(--color-code-foreground)\n padding: $code-spacing-vertical $code-spacing-horizontal\n padding-right: 0\n border-top-left-radius: 0.2rem\n border-bottom-left-radius: 0.2rem\n\n .linenodiv\n padding-right: $code-spacing-horizontal\n font-size: var(--code-font-size)\n box-shadow: -0.0625rem 0 var(--color-foreground-border) inset\n\n // Actual code\n td.code\n padding: 0\n display: block\n flex: 1\n overflow: hidden\n\n .highlight\n border-top-left-radius: 0\n border-bottom-left-radius: 0\n\n// When `html_codeblock_linenos_style` is inline.\n.highlight\n span.linenos\n display: inline-block\n padding-left: 0\n padding-right: $code-spacing-horizontal\n margin-right: $code-spacing-horizontal\n box-shadow: -0.0625rem 0 var(--color-foreground-border) inset\n","// Inline Footnote Reference\n.footnote-reference\n font-size: var(--font-size--small--4)\n vertical-align: super\n\n// Definition list, listing the content of each note.\n// docutils <= 0.17\ndl.footnote.brackets\n font-size: var(--font-size--small)\n color: var(--color-foreground-secondary)\n\n display: grid\n grid-template-columns: max-content auto\n dt\n margin: 0\n > .fn-backref\n margin-left: 0.25rem\n\n &:after\n content: \":\"\n\n .brackets\n &:before\n content: \"[\"\n &:after\n content: \"]\"\n\n dd\n margin: 0\n padding: 0 1rem\n\n// docutils >= 0.18\naside.footnote\n font-size: var(--font-size--small)\n color: var(--color-foreground-secondary)\n\naside.footnote > span,\ndiv.citation > span\n float: left\n font-weight: 500\n padding-right: 0.25rem\n\naside.footnote > p,\ndiv.citation > p\n margin-left: 2rem\n","//\n// Figures\n//\nimg\n box-sizing: border-box\n max-width: 100%\n height: auto\n\narticle\n figure, .figure\n border-radius: 0.2rem\n\n margin: 0\n :last-child\n margin-bottom: 0\n\n .align-left\n float: left\n clear: left\n margin: 0 1rem 1rem\n\n .align-right\n float: right\n clear: right\n margin: 0 1rem 1rem\n\n .align-default,\n .align-center\n display: block\n text-align: center\n margin-left: auto\n margin-right: auto\n\n // WELL, table needs to be stylised like a table.\n table.align-default\n display: table\n text-align: initial\n",".genindex-jumpbox, .domainindex-jumpbox\n border-top: 1px solid var(--color-background-border)\n border-bottom: 1px solid var(--color-background-border)\n padding: 0.25rem\n\n.genindex-section, .domainindex-section\n h2\n margin-top: 0.75rem\n margin-bottom: 0.5rem\n ul\n margin-top: 0\n margin-bottom: 0\n","ul,\nol\n padding-left: 1.2rem\n\n // Space lists out like paragraphs\n margin-top: 1rem\n margin-bottom: 1rem\n // reduce margins within li.\n li\n > p:first-child\n margin-top: 0.25rem\n margin-bottom: 0.25rem\n\n > p:last-child\n margin-top: 0.25rem\n\n > ul,\n > ol\n margin-top: 0.5rem\n margin-bottom: 0.5rem\n\nol\n &.arabic\n list-style: decimal\n &.loweralpha\n list-style: lower-alpha\n &.upperalpha\n list-style: upper-alpha\n &.lowerroman\n list-style: lower-roman\n &.upperroman\n list-style: upper-roman\n\n// Don't space lists out when they're \"simple\" or in a `.. toctree::`\n.simple,\n.toctree-wrapper\n li\n > ul,\n > ol\n margin-top: 0\n margin-bottom: 0\n\n// Definition Lists\n.field-list,\n.option-list,\ndl:not([class]),\ndl.simple,\ndl.footnote,\ndl.glossary\n dt\n font-weight: 500\n margin-top: 0.25rem\n + dt\n margin-top: 0\n\n .classifier::before\n content: \":\"\n margin-left: 0.2rem\n margin-right: 0.2rem\n\n dd\n > p:first-child,\n ul\n margin-top: 0.125rem\n\n ul\n margin-bottom: 0.125rem\n",".math-wrapper\n width: 100%\n overflow-x: auto\n\ndiv.math\n position: relative\n text-align: center\n\n .headerlink,\n &:focus .headerlink\n display: none\n\n &:hover .headerlink\n display: inline-block\n\n span.eqno\n position: absolute\n right: 0.5rem\n top: 50%\n transform: translate(0, -50%)\n z-index: 1\n","// Abbreviations\nabbr[title]\n cursor: help\n\n// \"Problematic\" content, as identified by Sphinx\n.problematic\n color: var(--color-problematic)\n\n// Keyboard / Mouse \"instructions\"\nkbd:not(.compound)\n margin: 0 0.2rem\n padding: 0 0.2rem\n border-radius: 0.2rem\n border: 1px solid var(--color-foreground-border)\n color: var(--color-foreground-primary)\n vertical-align: text-bottom\n\n font-size: var(--font-size--small--3)\n display: inline-block\n\n box-shadow: 0 0.0625rem 0 rgba(0, 0, 0, 0.2), inset 0 0 0 0.125rem var(--color-background-primary)\n\n background-color: var(--color-background-secondary)\n\n// Blockquote\nblockquote\n border-left: 4px solid var(--color-background-border)\n background: var(--color-background-secondary)\n\n margin-left: 0\n margin-right: 0\n padding: 0.5rem 1rem\n\n .attribution\n font-weight: 600\n text-align: right\n\n &.pull-quote,\n &.highlights\n font-size: 1.25em\n\n &.epigraph,\n &.pull-quote\n border-left-width: 0\n border-radius: 0.5rem\n\n &.highlights\n border-left-width: 0\n background: transparent\n\n// Center align embedded-in-text images\np .reference img\n vertical-align: middle\n","p.rubric\n line-height: 1.25\n font-weight: bold\n font-size: 1.125em\n\n // For Numpy-style documentation that's got rubrics within it.\n // https://github.com/pradyunsg/furo/discussions/505\n dd &\n line-height: inherit\n font-weight: inherit\n\n font-size: var(--font-size--small)\n text-transform: uppercase\n","article .sidebar\n float: right\n clear: right\n width: 30%\n\n margin-left: 1rem\n margin-right: 0\n\n border-radius: 0.2rem\n background-color: var(--color-background-secondary)\n border: var(--color-background-border) 1px solid\n\n > *\n padding-left: 1rem\n padding-right: 1rem\n\n > ul, > ol // lists need additional padding, because bullets.\n padding-left: 2.2rem\n\n .sidebar-title\n margin: 0\n padding: 0.5rem 1rem\n border-bottom: var(--color-background-border) 1px solid\n\n font-weight: 500\n\n// TODO: subtitle\n// TODO: dedicated variables?\n",".table-wrapper\n width: 100%\n overflow-x: auto\n margin-top: 1rem\n margin-bottom: 0.5rem\n padding: 0.2rem 0.2rem 0.75rem\n\ntable.docutils\n border-radius: 0.2rem\n border-spacing: 0\n border-collapse: collapse\n\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), 0 0 0.0625rem rgba(0, 0, 0, 0.1)\n\n th\n background: var(--color-table-header-background)\n\n td,\n th\n // Space things out properly\n padding: 0 0.25rem\n\n // Get the borders looking just-right.\n border-left: 1px solid var(--color-table-border)\n border-right: 1px solid var(--color-table-border)\n border-bottom: 1px solid var(--color-table-border)\n\n p\n margin: 0.25rem\n\n &:first-child\n border-left: none\n &:last-child\n border-right: none\n\n // MyST-parser tables set these classes for control of column alignment\n &.text-left\n text-align: left\n &.text-right\n text-align: right\n &.text-center\n text-align: center\n",":target\n scroll-margin-top: 0.5rem\n\n@media (max-width: $full-width - $sidebar-width)\n :target\n scroll-margin-top: calc(0.5rem + var(--header-height))\n\n // When a heading is selected\n section > span:target\n scroll-margin-top: calc(0.8rem + var(--header-height))\n\n// Permalinks\n.headerlink\n font-weight: 100\n user-select: none\n\nh1,\nh2,\nh3,\nh4,\nh5,\nh6,\ndl dt,\np.caption,\nfigcaption p,\ntable > caption,\n.code-block-caption\n > .headerlink\n margin-left: 0.5rem\n visibility: hidden\n &:hover > .headerlink\n visibility: visible\n\n // Don't change to link-like, if someone adds the contents directive.\n > .toc-backref\n color: inherit\n text-decoration-line: none\n\n// Figure and table captions are special.\nfigure:hover > figcaption > p > .headerlink,\ntable:hover > caption > .headerlink\n visibility: visible\n\n:target >, // Regular section[id] style anchors\nspan:target ~ // Non-regular span[id] style \"extra\" anchors\n h1,\n h2,\n h3,\n h4,\n h5,\n h6\n &:nth-of-type(1)\n background-color: var(--color-highlight-on-target)\n // .headerlink\n // visibility: visible\n code.literal\n background-color: transparent\n\ntable:target > caption,\nfigure:target\n background-color: var(--color-highlight-on-target)\n\n// Inline page contents\n.this-will-duplicate-information-and-it-is-still-useful-here li :target\n background-color: var(--color-highlight-on-target)\n\n// Code block permalinks\n.literal-block-wrapper:target .code-block-caption\n background-color: var(--color-highlight-on-target)\n\n// When a definition list item is selected\n//\n// There isn't really an alternative to !important here, due to the\n// high-specificity of API documentation's selector.\ndt:target\n background-color: var(--color-highlight-on-target) !important\n\n// When a footnote reference is selected\n.footnote > dt:target + dd,\n.footnote-reference:target\n background-color: var(--color-highlight-on-target)\n",".guilabel\n background-color: var(--color-guilabel-background)\n border: 1px solid var(--color-guilabel-border)\n color: var(--color-guilabel-text)\n\n padding: 0 0.3em\n border-radius: 0.5em\n font-size: 0.9em\n","// This file contains the styles used for stylizing the footer that's shown\n// below the content.\n\nfooter\n font-size: var(--font-size--small)\n display: flex\n flex-direction: column\n\n margin-top: 2rem\n\n// Bottom of page information\n.bottom-of-page\n display: flex\n align-items: center\n justify-content: space-between\n\n margin-top: 1rem\n padding-top: 1rem\n padding-bottom: 1rem\n\n color: var(--color-foreground-secondary)\n border-top: 1px solid var(--color-background-border)\n\n line-height: 1.5\n\n @media (max-width: $content-width)\n text-align: center\n flex-direction: column-reverse\n gap: 0.25rem\n\n .left-details\n font-size: var(--font-size--small)\n\n .right-details\n display: flex\n flex-direction: column\n gap: 0.25rem\n text-align: right\n\n .icons\n display: flex\n justify-content: flex-end\n gap: 0.25rem\n font-size: 1rem\n\n a\n text-decoration: none\n\n svg,\n img\n font-size: 1.125rem\n height: 1em\n width: 1em\n\n// Next/Prev page information\n.related-pages\n a\n display: flex\n align-items: center\n\n text-decoration: none\n &:hover .page-info .title\n text-decoration: underline\n color: var(--color-link)\n text-decoration-color: var(--color-link-underline)\n\n svg.furo-related-icon,\n svg.furo-related-icon > use\n flex-shrink: 0\n\n color: var(--color-foreground-border)\n\n width: 0.75rem\n height: 0.75rem\n margin: 0 0.5rem\n\n &.next-page\n max-width: 50%\n\n float: right\n clear: right\n text-align: right\n\n &.prev-page\n max-width: 50%\n\n float: left\n clear: left\n\n svg\n transform: rotate(180deg)\n\n.page-info\n display: flex\n flex-direction: column\n overflow-wrap: anywhere\n\n .next-page &\n align-items: flex-end\n\n .context\n display: flex\n align-items: center\n\n padding-bottom: 0.1rem\n\n color: var(--color-foreground-muted)\n font-size: var(--font-size--small)\n text-decoration: none\n","// This file contains the styles for the contents of the left sidebar, which\n// contains the navigation tree, logo, search etc.\n\n////////////////////////////////////////////////////////////////////////////////\n// Brand on top of the scrollable tree.\n////////////////////////////////////////////////////////////////////////////////\n.sidebar-brand\n display: flex\n flex-direction: column\n flex-shrink: 0\n\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n text-decoration: none\n\n.sidebar-brand-text\n color: var(--color-sidebar-brand-text)\n overflow-wrap: break-word\n margin: var(--sidebar-item-spacing-vertical) 0\n font-size: 1.5rem\n\n.sidebar-logo-container\n margin: var(--sidebar-item-spacing-vertical) 0\n\n.sidebar-logo\n margin: 0 auto\n display: block\n max-width: 100%\n\n////////////////////////////////////////////////////////////////////////////////\n// Search\n////////////////////////////////////////////////////////////////////////////////\n.sidebar-search-container\n display: flex\n align-items: center\n margin-top: var(--sidebar-search-space-above)\n\n position: relative\n\n background: var(--color-sidebar-search-background)\n &:hover,\n &:focus-within\n background: var(--color-sidebar-search-background--focus)\n\n &::before\n content: \"\"\n position: absolute\n left: var(--sidebar-item-spacing-horizontal)\n width: var(--sidebar-search-icon-size)\n height: var(--sidebar-search-icon-size)\n\n background-color: var(--color-sidebar-search-icon)\n mask-image: var(--icon-search)\n\n.sidebar-search\n box-sizing: border-box\n\n border: none\n border-top: 1px solid var(--color-sidebar-search-border)\n border-bottom: 1px solid var(--color-sidebar-search-border)\n\n padding-top: var(--sidebar-search-input-spacing-vertical)\n padding-bottom: var(--sidebar-search-input-spacing-vertical)\n padding-right: var(--sidebar-search-input-spacing-horizontal)\n padding-left: calc(var(--sidebar-item-spacing-horizontal) + var(--sidebar-search-input-spacing-horizontal) + var(--sidebar-search-icon-size))\n\n width: 100%\n\n color: var(--color-sidebar-search-foreground)\n background: transparent\n z-index: 10\n\n &:focus\n outline: none\n\n &::placeholder\n font-size: var(--sidebar-search-input-font-size)\n\n//\n// Hide Search Matches link\n//\n#searchbox .highlight-link\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal) 0\n margin: 0\n text-align: center\n\n a\n color: var(--color-sidebar-search-icon)\n font-size: var(--font-size--small--2)\n\n////////////////////////////////////////////////////////////////////////////////\n// Structure/Skeleton of the navigation tree (left)\n////////////////////////////////////////////////////////////////////////////////\n.sidebar-tree\n font-size: var(--sidebar-item-font-size)\n margin-top: var(--sidebar-tree-space-above)\n margin-bottom: var(--sidebar-item-spacing-vertical)\n\n ul\n padding: 0\n margin-top: 0\n margin-bottom: 0\n\n display: flex\n flex-direction: column\n\n list-style: none\n\n li\n position: relative\n margin: 0\n\n > ul\n margin-left: var(--sidebar-item-spacing-horizontal)\n\n .icon\n color: var(--color-sidebar-link-text)\n\n .reference\n box-sizing: border-box\n color: var(--color-sidebar-link-text)\n\n // Fill the parent.\n display: inline-block\n line-height: var(--sidebar-item-line-height)\n text-decoration: none\n\n // Don't allow long words to cause wrapping.\n overflow-wrap: anywhere\n\n height: 100%\n width: 100%\n\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n\n &:hover\n background: var(--color-sidebar-item-background--hover)\n\n // Add a nice little \"external-link\" arrow here.\n &.external::after\n content: url('data:image/svg+xml,')\n margin: 0 0.25rem\n vertical-align: middle\n color: var(--color-sidebar-link-text)\n\n // Make the current page reference bold.\n .current-page > .reference\n font-weight: bold\n\n label\n position: absolute\n top: 0\n right: 0\n height: var(--sidebar-item-height)\n width: var(--sidebar-expander-width)\n\n cursor: pointer\n user-select: none\n\n display: flex\n justify-content: center\n align-items: center\n\n .caption, :not(.caption) > .caption-text\n font-size: var(--sidebar-caption-font-size)\n color: var(--color-sidebar-caption-text)\n\n font-weight: bold\n text-transform: uppercase\n\n margin: var(--sidebar-caption-space-above) 0 0 0\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n\n // If it has children, add a bit more padding to wrap the content to avoid\n // overlapping with the