Module histogram

Expand description

Traits for implementing histograms for Wang Landau or entropic sampling. Contains histogram implementations for all primitive numbers

§Using Histograms

For the histograms of integers with bin width larger than 1: you should use the newly implemented GenericHist of BinningWithWidth. These will likely be much faster than HistogramInt, especially if you have a lot of bins. I did not remove the slower implementation, because then I’d have to change all of my other code in which I use them ^^“

Anyhow, here is an example for using a fast histogram with bin width 3

use sampling::histogram::*;
use rand_pcg::Pcg64;
use rand::prelude::*;
use rand::distr::*;
 
// now I use one of the type aliases to first create the binning and then the histogram:
let mut hist = BinningI32::new_inclusive(-20,132, 3)
    .unwrap()
    .to_generic_hist();
 
let uniform = Uniform::new_inclusive(-20, 132).unwrap();
let mut rng = Pcg64::seed_from_u64(3987612);
// create 10000 samples
let iter = uniform
    .sample_iter(rng) 
    .take(10000);
for val in iter{
    hist.count_val(val)
        .unwrap(); // would panic if a value were to be outside the hist 
    // alternatively, if you don't want the panic:
    // let _ = hist.count_val(val);
}

If you have a bin width of 1, then you can either use the newly implemented GenericHist of FastSingleIntBinning like in the example below, or you can keep using the old HistogramFast, as there seems to be no real difference in speed, at least on my machine they are within variance of one another.

Either way, there are type aliases for convenience, see below.

use sampling::histogram::*;
use rand_pcg::Pcg64;
use rand::prelude::*;
use rand::distr::*;
 
// now I use one of the type aliases to first create the binning and then the histogram:
let mut hist = FastBinningI32::new_inclusive(-20,130)
    .to_generic_hist();
 
let uniform = Uniform::new_inclusive(-20, 130).unwrap();
let mut rng = Pcg64::seed_from_u64(3987612);
// create 10000 samples
let iter = uniform
    .sample_iter(rng) 
    .take(10000);
for val in iter{
 
    hist.count_val(val)
        .unwrap(); // would panic if a value were to be outside the hist 
    // alternatively, if you don't want the panic:
    // let _ = hist.count_val(val);
}

§Atomic Histograms

Sometimes you want to create a histograms in parallel, i.e., from multiple threads simultaneously. In this case you can use Atomic histograms,

use sampling::histogram::*;
use rand_pcg::Pcg64;
use rand::prelude::*;
use rand::distr::*;
use rayon::prelude::*;
 
// now I use one of the type aliases to first create the binning and then the histogram:
let mut atomic_hist = BinningI16::new_inclusive(-20,132, 3)
    .unwrap()
    .to_generic_atomic_hist();
 
let uniform = Uniform::new_inclusive(-20, 132)
    .unwrap();
 
(0..4)
    .into_par_iter()
    .for_each(
        |seed|
        {
            let mut rng = Pcg64::seed_from_u64(seed);
            // create 10000 samples
            let iter = uniform
                .sample_iter(rng) 
                .take(10000);
            for val in iter{
                atomic_hist.count_val(val)
                    .unwrap(); // would panic if a value were to be outside the hist 
                // alternatively, if you don't want the panic:
                // let _ = hist.count_val(val);
            }
        }
    );
assert_eq!(
    atomic_hist.total_hits(), 
    40000
);
 
// You can also convert the generic atomic histogram into a normal histogram.
let hist = atomic_hist.into_generic_hist();
// You can also convert it the other way round
let atomic_hist = hist.into_atomic_generic_hist();

Structs§

AtomicGenericHist: Provides Histogram functionality
AtomicHistogramFloat: Generic Histogram struct
BinningWithWidth: Generic binning meant for any integer type
FastSingleIntBinning: Generic binning meant for any integer type
GenericHist: Provides Histogram functionality
HistogramFast: Faster version of HistogramInt for Integers
HistogramFloat: Generic Histogram struct
HistogramIntDeprecated: Generic Histogram for integer types

Enums§

Bin: Definition of a Bin
HistErrors: Possible Errors of the traits Histogram and HistogramVal
Outcome: You have done something that can succeed or fail

Traits§

AtomicHistogram: Implements histogram
AtomicHistogramVal: trait used for mapping values of arbitrary type T to binsused to create a histogram
BinDisplay: Trait used to display bins
Binning: Implements Binning
HasUnsignedVersion: Helper trait for efficient calculations in other implementations
Histogram: Implements histogram
HistogramCombine: Used to get a histogram, which contains the smaller histograms
HistogramIntervalDistance: Distance metric for how far a value is from a valid interval
HistogramPartition: Your Interval is to large to sample in a reasonable amount of time? No problem
HistogramVal: trait used for mapping values of arbitrary type T to binsused to create a histogram
IntervalOrder: Trait for comparing two intervals

Functions§

checked_mul_div_i8: Checked multiply divide
checked_mul_div_i16: Checked multiply divide
checked_mul_div_i32: Checked multiply divide
checked_mul_div_i64: Checked multiply divide
checked_mul_div_i128: Checked multiply divide
checked_mul_div_isize: Checked multiply divide
checked_mul_div_u8: Checked multiply divide
checked_mul_div_u16: Checked multiply divide
checked_mul_div_u32: Checked multiply divide
checked_mul_div_u64: Checked multiply divide
checked_mul_div_u128: Checked multiply divide
checked_mul_div_usize: Checked multiply divide

Type Aliases§

AtomicHistF32: Histogram for binning f32 - alias for HistogramFloat<f32>
AtomicHistF64: Histogram for binning f64 - alias for HistogramFloat<f64>
BinningI8: Efficient binning for i8 with arbitrary width
BinningI16: Efficient binning for i16 with arbitrary width
BinningI32: Efficient binning for i32 with arbitrary width
BinningI64: Efficient binning for i64 with arbitrary width
BinningI128: Efficient binning for i128 with arbitrary width
BinningISIZE: Efficient binning for isize with arbitrary width
BinningU8: Efficient binning for u8 with arbitrary width
BinningU16: Efficient binning for u16 with arbitrary width
BinningU32: Efficient binning for u32 with arbitrary width
BinningU64: Efficient binning for u64 with arbitrary width
BinningU128: Efficient binning for u128 with arbitrary width
BinningUSIZE: Efficient binning for usize with arbitrary width
FastBinningI8: Efficient binning for i8 with bins of width 1
FastBinningI16: Efficient binning for i16 with bins of width 1
FastBinningI32: Efficient binning for i32 with bins of width 1
FastBinningI64: Efficient binning for i64 with bins of width 1
FastBinningI128: Efficient binning for i128 with bins of width 1
FastBinningISIZE: Efficient binning for isize with bins of width 1
FastBinningU8: Efficient binning for u8 with bins of width 1
FastBinningU16: Efficient binning for u16 with bins of width 1
FastBinningU32: Efficient binning for u32 with bins of width 1
FastBinningU64: Efficient binning for u64 with bins of width 1
FastBinningU128: Efficient binning for u128 with bins of width 1
FastBinningUSIZE: Efficient binning for usize with bins of width 1
HistF32: Histogram for binning f32 - alias for HistogramFloat<f32>
HistF64: Histogram for binning f64 - alias for HistogramFloat<f64>
HistI8Deprecated: Histogram for binning i8 - alias for HistogramInt<i8>
HistI8Fast: Histogram for binning i8 - alias for HistogramFastiu8>
HistI16Deprecated: Histogram for binning i16 - alias for HistogramInt<i16>
HistI32Deprecated: Histogram for binning i32 - alias for HistogramInt<i32>
HistI64Deprecated: Histogram for binning i64 - alias for HistogramInt<i64>
HistI16Fast: Histogram for binning i16 - alias for HistogramFast<i16>
HistI32Fast: Histogram for binning i32 - alias for HistogramFast<i32>
HistI64Fast: Histogram for binning i64 - alias for HistogramFast<i64>
HistI128Deprecated: Histogram for binning i128 - alias for HistogramInt<i128>
HistI128Fast: Histogram for binning i128 - alias for HistogramFast<i128>
HistIsizeDeprecated: Histogram for binning isize - alias for HistogramInt<isize>
HistIsizeFast: Histogram for binning isize - alias for HistogramFast<isize>
HistU8Deprecated: Histogram for binning u8 - alias for HistogramInt<u8>
HistU8Fast: Histogram for binning u8 - alias for HistogramFast<u8>
HistU16Deprecated: Histogram for binning u16 - alias for HistogramInt<u16>
HistU32Deprecated: Histogram for binning u32 - alias for HistogramInt<u32>
HistU64Deprecated: Histogram for binning u64 - alias for HistogramInt<u64>
HistU16Fast: Histogram for binning u16 - alias for HistogramFast<u16>
HistU32Fast: Histogram for binning u32 - alias for HistogramFast<u32>
HistU64Fast: Histogram for binning u64 - alias for HistogramFast<u64>
HistU128Deprecated: Histogram for binning u128 - alias for HistogramInt<u128>
HistU128Fast: Histogram for binning u128 - alias for HistogramFast<u128>
HistUsizeDeprecated: Histogram for binning usize - alias for HistogramInt<usize>
HistUsizeFast: Histogram for binning usize- alias for HistogramFast<usize>

Module histogramCopy item path