diff --git a/ndarray-rand/Cargo.toml b/ndarray-rand/Cargo.toml index 024174a28..c91760717 100644 --- a/ndarray-rand/Cargo.toml +++ b/ndarray-rand/Cargo.toml @@ -7,6 +7,7 @@ license = "MIT/Apache-2.0" repository = "https://github.com/rust-ndarray/ndarray" documentation = "https://docs.rs/ndarray-rand/" +readme = "README.md" description = "Constructors for randomized arrays. `rand` integration for `ndarray`." @@ -14,13 +15,14 @@ keywords = ["multidimensional", "matrix", "rand", "ndarray"] [dependencies] ndarray = { version = "0.12.0", path = ".." } +rand_distr = "0.2.1" [dependencies.rand] version = "0.7.0" features = ["small_rng"] [dev-dependencies] -rand_distr = "0.2.1" +rand_isaac = "0.2.0" [package.metadata.release] no-dev-version = true diff --git a/ndarray-rand/README.md b/ndarray-rand/README.md new file mode 100644 index 000000000..e993440df --- /dev/null +++ b/ndarray-rand/README.md @@ -0,0 +1,65 @@ +ndarray-rand +============ + +Constructors for randomized arrays: `rand`'s integration with `ndarray`. + +Example +======= + +Generate a 2-dimensional array with shape `(2,5)` and elements drawn from a uniform distribution +over the `(0., 10.)` interval: + +```rust +use ndarray::Array; +use ndarray_rand::RandomExt; +use ndarray_rand::rand_distr::Uniform; + +fn main() { + let a = Array::random((2, 5), Uniform::new(0., 10.)); + println!("{:8.4}", a); + // Example Output: + // [[ 8.6900, 6.9824, 3.8922, 6.5861, 2.4890], + // [ 0.0914, 5.5186, 5.8135, 5.2361, 3.1879]] +} +``` + +Dependencies +============ + +``ndarray-rand`` depends on ``rand`` 0.7. + +[`rand`](https://docs.rs/rand/0.7.0/rand/) and [`rand-distr`](https://docs.rs/rand_distr/0.2.1/rand_distr/) are +re-exported as sub-modules, `ndarray_rand::rand` and `ndarray_rand::rand_distr` respectively. +Please rely on these submodules for guaranteed version compatibility. + +If you want to use a random number generator or distribution from another crate +with `ndarray-rand`, you need to make sure that the other crate also depends on the +same version of `rand`. Otherwise, the compiler may return errors saying +that the items are not compatible (e.g. that a type doesn't implement a +necessary trait). + +Recent changes +============== + +0.10.0 +------ + + - Require `rand` 0.7 + - Require Rust 1.32 or later + - Re-export `rand` as a submodule, `ndarray_rand::rand` + - Re-export `rand-distr` as a submodule, `ndarray_rand::rand_distr` + +Check _[Changelogs](https://github.com/rust-ndarray/ndarray/ndarray-rand/RELEASES.md)_ to see +the changes introduced in previous releases. + + +License +======= + +Dual-licensed to be compatible with the Rust project. + +Licensed under the Apache License, Version 2.0 +http://www.apache.org/licenses/LICENSE-2.0 or the MIT license +http://opensource.org/licenses/MIT, at your +option. This file may not be copied, modified, or distributed +except according to those terms. diff --git a/ndarray-rand/README.rst b/ndarray-rand/README.rst deleted file mode 100644 index d764b6cbb..000000000 --- a/ndarray-rand/README.rst +++ /dev/null @@ -1,76 +0,0 @@ -ndarray-rand -============ - -Dependencies ------------- - -``ndarray-rand`` depends on ``rand`` 0.7. If you use any other items from -``rand``, you need to specify a compatible version of ``rand`` in your -``Cargo.toml``. If you want to use a RNG or distribution from another crate -with ``ndarray-rand``, you need to make sure that crate also depends on the -correct version of ``rand``. Otherwise, the compiler will return errors saying -that the items are not compatible (e.g. that a type doesn't implement a -necessary trait). - -Recent Changes --------------- - -- 0.10.0 - - - Require rand 0.7 - - Require Rust 1.32 or later - -- 0.9.0 - - - Require rand 0.6 - -- 0.8.0 - - - Require ndarray 0.12 - - Require rand 0.5 - -- 0.7.0 - - - Require ndarray 0.11 - - Require rand 0.4 - -- 0.6.1 - - - Clean up implementation of ``Array::random`` by @v-shmyhlo - -- 0.6.0 - - - Require ndarray 0.10.0 - -- 0.5.0 - - - Require ndarray 0.9 - -- 0.4.0 - - - Require ndarray 0.8 - -- 0.3.0 - - - Require ndarray 0.7 - -- 0.2.0 - - - Require ndarray 0.6 - -- 0.1.0 - - - Initial release - -License -======= - -Dual-licensed to be compatible with the Rust project. - -Licensed under the Apache License, Version 2.0 -http://www.apache.org/licenses/LICENSE-2.0 or the MIT license -http://opensource.org/licenses/MIT, at your -option. This file may not be copied, modified, or distributed -except according to those terms. - - diff --git a/ndarray-rand/RELEASES.md b/ndarray-rand/RELEASES.md new file mode 100644 index 000000000..d99fd3f8f --- /dev/null +++ b/ndarray-rand/RELEASES.md @@ -0,0 +1,51 @@ +Recent Changes +-------------- + +- 0.10.0 + + - Require `rand` 0.7 + - Require Rust 1.32 or later + - Re-export `rand` as a submodule, `ndarray_rand::rand` + - Re-export `rand-distr` as a submodule, `ndarray_rand::rand_distr` + +- 0.9.0 + + - Require rand 0.6 + +- 0.8.0 + + - Require ndarray 0.12 + - Require rand 0.5 + +- 0.7.0 + + - Require ndarray 0.11 + - Require rand 0.4 + +- 0.6.1 + + - Clean up implementation of ``Array::random`` by @v-shmyhlo + +- 0.6.0 + + - Require ndarray 0.10.0 + +- 0.5.0 + + - Require ndarray 0.9 + +- 0.4.0 + + - Require ndarray 0.8 + +- 0.3.0 + + - Require ndarray 0.7 + +- 0.2.0 + + - Require ndarray 0.6 + +- 0.1.0 + + - Initial release diff --git a/ndarray-rand/src/lib.rs b/ndarray-rand/src/lib.rs index 69d088096..be747fd23 100644 --- a/ndarray-rand/src/lib.rs +++ b/ndarray-rand/src/lib.rs @@ -6,33 +6,50 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Constructors for randomized arrays. `rand` integration for `ndarray`. +//! Constructors for randomized arrays: `rand` integration for `ndarray`. //! //! See [**`RandomExt`**](trait.RandomExt.html) for usage examples. //! -//! **Note:** `ndarray-rand` depends on `rand` 0.7. If you use any other items -//! from `rand`, you need to specify a compatible version of `rand` in your -//! `Cargo.toml`. If you want to use a RNG or distribution from another crate -//! with `ndarray-rand`, you need to make sure that crate also depends on the -//! correct version of `rand`. Otherwise, the compiler will return errors -//! saying that the items are not compatible (e.g. that a type doesn't -//! implement a necessary trait). +//! ## Note +//! +//! `ndarray-rand` depends on [`rand` 0.7.0](https://docs.rs/rand/0.7.0/rand/). +//! +//! [`rand`](https://docs.rs/rand/0.7.0/rand/) and [`rand-distr`](https://docs.rs/rand_distr/0.2.1/rand_distr/) +//! are re-exported as sub-modules, [`ndarray_rand::rand`](rand/index.html) +//! and [`ndarray_rand::rand_distr`](rand_distr/index.html) respectively. +//! Please rely on these submodules for guaranteed version compatibility. +//! +//! If you want to use a random number generator or distribution from another crate +//! with `ndarray-rand`, you need to make sure that the other crate also depends on the +//! same version of `rand`. Otherwise, the compiler will return errors saying +//! that the items are not compatible (e.g. that a type doesn't implement a +//! necessary trait). -use rand::distributions::Distribution; -use rand::rngs::SmallRng; -use rand::{thread_rng, Rng, SeedableRng}; +use crate::rand::distributions::Distribution; +use crate::rand::rngs::SmallRng; +use crate::rand::{thread_rng, Rng, SeedableRng}; use ndarray::ShapeBuilder; use ndarray::{ArrayBase, DataOwned, Dimension}; +/// [`rand`](https://docs.rs/rand/0.7.0/rand/), re-exported for convenience and version-compatibility. +pub mod rand { + pub use rand::*; +} + +/// [`rand-distr`](https://docs.rs/rand_distr/0.2.1/rand_distr/), re-exported for convenience and version-compatibility. +pub mod rand_distr { + pub use rand_distr::*; +} + /// Constructors for n-dimensional arrays with random elements. /// /// This trait extends ndarray’s `ArrayBase` and can not be implemented /// for other types. /// /// The default RNG is a fast automatically seeded rng (currently -/// [`rand::rngs::SmallRng`](https://docs.rs/rand/0.5/rand/rngs/struct.SmallRng.html) -/// seeded from [`rand::thread_rng`](https://docs.rs/rand/0.5/rand/fn.thread_rng.html)). +/// [`rand::rngs::SmallRng`](https://docs.rs/rand/0.7/rand/rngs/struct.SmallRng.html) +/// seeded from [`rand::thread_rng`](https://docs.rs/rand/0.7/rand/fn.thread_rng.html)). /// /// Note that `SmallRng` is cheap to initialize and fast, but it may generate /// low-quality random numbers, and reproducibility is not guaranteed. See its @@ -50,13 +67,9 @@ where /// overflows usize. /// /// ``` - /// extern crate rand; - /// extern crate ndarray; - /// extern crate ndarray_rand; - /// - /// use rand::distributions::Uniform; /// use ndarray::Array; /// use ndarray_rand::RandomExt; + /// use ndarray_rand::rand_distr::Uniform; /// /// # fn main() { /// let a = Array::random((2, 5), Uniform::new(0., 10.)); @@ -74,6 +87,26 @@ where /// `distribution`, using a specific Rng `rng`. /// /// ***Panics*** if the number of elements overflows usize. + /// + /// ``` + /// use ndarray::Array; + /// use ndarray_rand::RandomExt; + /// use ndarray_rand::rand::SeedableRng; + /// use ndarray_rand::rand_distr::Uniform; + /// use rand_isaac::isaac64::Isaac64Rng; + /// + /// # fn main() { + /// // Get a seeded random number generator for reproducibility (Isaac64 algorithm) + /// let seed = 42; + /// let mut rng = Isaac64Rng::seed_from_u64(seed); + /// + /// // Generate a random array using `rng` + /// let a = Array::random_using((2, 5), Uniform::new(0., 10.), &mut rng); + /// println!("{:8.4}", a); + /// // Example Output: + /// // [[ 8.6900, 6.9824, 3.8922, 6.5861, 2.4890], + /// // [ 0.0914, 5.5186, 5.8135, 5.2361, 3.1879]] + /// # } fn random_using(shape: Sh, distribution: IdS, rng: &mut R) -> ArrayBase where IdS: Distribution, @@ -109,16 +142,13 @@ where /// A wrapper type that allows casting f64 distributions to f32 /// /// ``` -/// extern crate rand; -/// extern crate ndarray; -/// extern crate ndarray_rand; -/// -/// use rand::distributions::Normal; /// use ndarray::Array; /// use ndarray_rand::{RandomExt, F32}; +/// use ndarray_rand::rand_distr::Normal; /// /// # fn main() { -/// let a = Array::random((2, 5), F32(Normal::new(0., 1.))); +/// let distribution_f64 = Normal::new(0., 1.).expect("Failed to create normal distribution"); +/// let a = Array::random((2, 5), F32(distribution_f64)); /// println!("{:8.4}", a); /// // Example Output: /// // [[ -0.6910, 1.1730, 1.0902, -0.4092, -1.7340], diff --git a/ndarray-rand/tests/tests.rs b/ndarray-rand/tests/tests.rs index 1f936d25c..6e64a10b9 100644 --- a/ndarray-rand/tests/tests.rs +++ b/ndarray-rand/tests/tests.rs @@ -1,6 +1,6 @@ use ndarray::Array; +use ndarray_rand::rand_distr::Uniform; use ndarray_rand::RandomExt; -use rand::distributions::Uniform; #[test] fn test_dim() {