sampling/
histogram.rs

1//! Traits for implementing histograms for Wang Landau or entropic sampling.
2//! Contains histogram implementations for all primitive numbers
3//! # Using Histograms
4//! For the histograms of integers with bin width larger than 1: you should use the newly implemented 
5//! [GenericHist]  of [BinningWithWidth].
6//! These will likely be much faster than [HistogramInt], especially if you have a lot of bins. 
7//! I did not remove the slower implementation, because then I'd have to change all 
8//! of my other code in which I use them ^^"
9//! 
10//! Anyhow, here is an example for using a fast histogram with bin width 3
11//! 
12//! ```
13//! use sampling::histogram::*;
14//! use rand_pcg::Pcg64;
15//! use rand::prelude::*;
16//! use rand::distr::*;
17//! 
18//! // now I use one of the type aliases to first create the binning and then the histogram:
19//! let mut hist = BinningI32::new_inclusive(-20,132, 3)
20//!     .unwrap()
21//!     .to_generic_hist();
22//! 
23//! let uniform = Uniform::new_inclusive(-20, 132).unwrap();
24//! let mut rng = Pcg64::seed_from_u64(3987612);
25//! // create 10000 samples
26//! let iter = uniform
27//!     .sample_iter(rng) 
28//!     .take(10000);
29//! for val in iter{
30//!     hist.count_val(val)
31//!         .unwrap(); // would panic if a value were to be outside the hist 
32//!     // alternatively, if you don't want the panic:
33//!     // let _ = hist.count_val(val);
34//! }
35//! ```
36//! If you have a bin width of 1, then you can either use the newly implemented 
37//! [GenericHist] of [FastSingleIntBinning] like in the example below, or 
38//! you can keep using the old [HistogramFast], as there seems to be no real difference in speed,
39//! at least on my machine they are within variance of one another.
40//! 
41//! Either way, there are type aliases for convenience, see below.
42//! 
43//! ```
44//! use sampling::histogram::*;
45//! use rand_pcg::Pcg64;
46//! use rand::prelude::*;
47//! use rand::distr::*;
48//! 
49//! // now I use one of the type aliases to first create the binning and then the histogram:
50//! let mut hist = FastBinningI32::new_inclusive(-20,130)
51//!     .to_generic_hist();
52//! 
53//! let uniform = Uniform::new_inclusive(-20, 130).unwrap();
54//! let mut rng = Pcg64::seed_from_u64(3987612);
55//! // create 10000 samples
56//! let iter = uniform
57//!     .sample_iter(rng) 
58//!     .take(10000);
59//! for val in iter{
60//! 
61//!     hist.count_val(val)
62//!         .unwrap(); // would panic if a value were to be outside the hist 
63//!     // alternatively, if you don't want the panic:
64//!     // let _ = hist.count_val(val);
65//! }
66//! ```
67//! 
68//! # Atomic Histograms
69//! 
70//! Sometimes you want to create a histograms in parallel, i.e.,
71//! from multiple threads simultaneously.
72//! In this case you can use Atomic histograms, 
73//! ```
74//! use sampling::histogram::*;
75//! use rand_pcg::Pcg64;
76//! use rand::prelude::*;
77//! use rand::distr::*;
78//! use rayon::prelude::*;
79//! 
80//! // now I use one of the type aliases to first create the binning and then the histogram:
81//! let mut atomic_hist = BinningI16::new_inclusive(-20,132, 3)
82//!     .unwrap()
83//!     .to_generic_atomic_hist();
84//! 
85//! let uniform = Uniform::new_inclusive(-20, 132)
86//!     .unwrap();
87//! 
88//! (0..4)
89//!     .into_par_iter()
90//!     .for_each(
91//!         |seed|
92//!         {
93//!             let mut rng = Pcg64::seed_from_u64(seed);
94//!             // create 10000 samples
95//!             let iter = uniform
96//!                 .sample_iter(rng) 
97//!                 .take(10000);
98//!             for val in iter{
99//!                 atomic_hist.count_val(val)
100//!                     .unwrap(); // would panic if a value were to be outside the hist 
101//!                 // alternatively, if you don't want the panic:
102//!                 // let _ = hist.count_val(val);
103//!             }
104//!         }
105//!     );
106//! assert_eq!(
107//!     atomic_hist.total_hits(), 
108//!     40000
109//! );
110//! 
111//! // You can also convert the generic atomic histogram into a normal histogram.
112//! let hist = atomic_hist.into_generic_hist();
113//! // You can also convert it the other way round
114//! let atomic_hist = hist.into_atomic_generic_hist();
115//! ```
116
117mod histogram_traits;
118mod histogram_float;
119mod histogram_int;
120mod helper;
121mod histogram_fast;
122
123mod atomic_hist_float;
124mod binning;
125mod generic_hist;
126mod atomic_generic_hist;
127
128pub use histogram_traits::*;
129pub use histogram_float::*;
130pub use histogram_int::*;
131pub use helper::*;
132pub use histogram_fast::*;
133
134pub use atomic_hist_float::*;
135pub use binning::*;
136pub use generic_hist::*;
137pub use atomic_generic_hist::*;
sampling/histogram.rs

sampling/
histogram.rs
