Add a way to derive `Standard` and `Uniform` distributions for a struct

[LikeLakers2]

Background

What is your motivation?

rand offers the Standard and Uniform distributions, for making random samples of a primitive or struct. However, to implement them for a new type, the impls (impl Distribution<T> for Standard for Standard; impl SampleUniform for T and impl UniformSampler for TUniformSampler for Uniform) must currently be hand-written.

What type of application is this?

No specific type of application, though I write this after having to manually implement Uniform distribution support for the glam crate.

Feature request

I propose that derives be added for the Standard and Uniform distributions. When used on a struct where all fields already implement support for that type of distribution, it will generate the needed code to use Standard/Uniform distributions with that struct.

A derive for the Standard distribution would probably look like this (click the arrow to expand):

Standard distribution derive

#[derive(StandardRand)]
struct Vec3 {
	x: f32,
	y: f32,
	z: f32,
}

This derive would generate code similar to the following:

impl Distribution<Vec3> for Standard {
	fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Vec3 {
		Vec3 {
			x: rng.gen(),
			y: rng.gen(),
			z: rng.gen(),
		}
	}
}

A derive for the Uniform distribution would be much the same, albeit with the addition of a struct being generated for the UniformSampler impl:

Uniform distribution derive

#[derive(UniformRand)]
struct Vec3 {
	x: f32,
	y: f32,
	z: f32,
}

generates the following code:

impl SampleUniform for Vec3 {
	type Sampler = Vec3UniformSampler;
}

struct Vec3UniformSampler {
	x_gen: Uniform<f32>,
	y_gen: Uniform<f32>,
	z_gen: Uniform<f32>,
}

impl UniformSampler for Vec3UniformSampler {
	type X = Vec3;

	fn new<B1, B2>(low_b: B1, high_b: B2) -> Self
	where
		B1: SampleBorrow<Self::X> + Sized,
		B2: SampleBorrow<Self::X> + Sized,
	{
		let low = *low_b.borrow();
		let high = *high_b.borrow();
		// Asserts here are technically optional, since our fields are Uniforms,
		// but I'm including them anyways for the sake of the example.
		assert!(low.x < high.x, "Uniform::new called with `low.x >= high.x");
		assert!(low.y < high.y, "Uniform::new called with `low.y >= high.y");
		assert!(low.z < high.z, "Uniform::new called with `low.z >= high.z");
		Self {
			x_gen: Uniform::new(low.x, high.x),
			y_gen: Uniform::new(low.y, high.y),
			z_gen: Uniform::new(low.z, high.z),
		}
	}

	fn new_inclusive<B1, B2>(low_b: B1, high_b: B2) -> Self
	where
		B1: SampleBorrow<Self::X> + Sized,
		B2: SampleBorrow<Self::X> + Sized,
	{
		let low = *low_b.borrow();
		let high = *high_b.borrow();
		assert!(low.x < high.x, "Uniform::new_inclusive called with `low.x >= high.x");
		assert!(low.y < high.y, "Uniform::new_inclusive called with `low.y >= high.y");
		assert!(low.z < high.z, "Uniform::new_inclusive called with `low.z >= high.z");
		Self {
			x_gen: Uniform::new_inclusive(low.x, high.x),
			y_gen: Uniform::new_inclusive(low.y, high.y),
			z_gen: Uniform::new_inclusive(low.z, high.z),
		}
	}

	fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Self::X {
		Self::X {
			x: self.x_gen.sample(rng),
			y: self.y_gen.sample(rng),
			z: self.z_gen.sample(rng),
		}
	}
	
	// sample_single() and sample_single_inclusive() are not included for the
	// sake of shortening the example.
}

If I've missed any details, or if there's any questions you have for me regarding this suggestion, please don't hesitate to let me know.

[dhardy]

The rand lib used to have similar functionality which was deprecated (largely because of other changes which would have required significant revision to the macro and a lack of usage.) Interestingly, rand_derive now has 7 reverse-deps.

We could, then, add derive support. It would not be part of the rand crate but a separate crate.

It should be obvious that all such fields would be sampled independently, thus e.g. samples of Vec3 above would fill a cube not a sphere in 3D space. I wouldn't be surprised if some users fail to realise this however.

On the above snippets:

• #[derive(UniformRand)] — yeah, not ideal having to use a fake name. I'd be tempted to provide an impl-tools::autoimpl implementation instead just because that supports paths. (I wrote impl-tools because standard custom derives don't provide enough flexibility, though I don't think we'd have any use for its other features like ignore field / using field / enum support here.) Maybe just #[derive(rand_distr_Uniform)] is good enough.
• struct Vec3UniformSampler — a "derive" macro should be hygenic and not dump extra items into the current scope. Unfortunately I don't think this is solvable, so I guess documenting this is about all we can do.
• Plenty of times the derive will fail because a (generic) field type does not support Uniform / Standard. We may remove support for Option in the next release, and we won't try to support a vast number of generic types. This does limit the usefulness of a derive macro, though not remove it's uses completely.

[LikeLakers2]

I meant to post this yesterday: Shortly after making this feature request, I decided to start work on https://github.com/LikeLakers2/michis_rand_distr_derive, which is a proc-macro crate for deriving Standard and Uniform distributions for a struct.

However, its primary use is as derive-macro practice for myself - and in any case, it's not finished. Still, I wonder if it may be useful to some folks?

---

@dhardy Thanks for the comments. RE the snippets:

#[derive(UniformRand)] — yeah, not ideal having to use a fake name.

Just to make sure I understand: When you say "fake name", you're referring to UniformRand expanding into items that aren't called UniformRand?

struct Vec3UniformSampler — a "derive" macro should be hygenic and not dump extra items into the current scope. Unfortunately I don't think this is solvable, so I guess documenting this is about all we can do.

I do admit that a derive macro doing more than implementing a trait is odd. However, I'm not sure an attribute macro:

#[generate_uniform_support]
struct Vec3(f32, f32, f32);

or a function-like macro:

generate_uniform_support! {
	struct Vec3(f32, f32, f32);
}

would be any better, since several items (impl SampleUniform for MyType, struct MyTypeUniformSampler, and impl UniformSampler for MyTypeUniformSampler) need to exist for Uniform support to be possible.

[benjamin-lieser]

I can see the general use case for creating test instances of structs. I also don't think that people would care about the details of the resulting distribution (cube vs sphere), they just want something "random"

For this usecase a GetRandomInstance trait would probably ideal and it would also not interfere with what we already have. Option and Result could also implement this, because users would not care to much about the exact distributions of this trait.

Probably this would be functionality for it's own crate outside of the scope of rand. But I also see the appeal of rand being the one stop thing for everything random.

[dhardy]

would be any better

They're not. I guess what we could do is something like this:

[#derive_distr(Uniform, sampler=Vec3Uniform)]`
struct Vec3(f32, f32, f32);

in order to let users supply a name... but that is overly complicated (also less obvious what it does just reading it).

GetRandomInstance trait

You are referring to something like the old Rand trait? The limitation is that this only works for what we're probably now(#1297) calling StandardUniform, not also parametrised samplers like Uniform.

[benjamin-lieser]

You are referring to something like the old Rand trait? The limitation is that this only works for what we're probably now(#1297) calling StandardUniform, not also parametrised samplers like Uniform.

Yes. I think this limitation is fine if someone just wants something random. If you need more control you implement it yourself.

[vks]

I can see the general use case for creating test instances of structs. I also don't think that people would care about the details of the resulting distribution (cube vs sphere), they just want something "random"

I think this is better served by crates for fuzzing and/or property-based testing, which already offer such traits, for example Arbitrary. I'm not sure Rand's Uniform is the right place for this, as these use cases don't necessarily require or even want a uniform distribution.

[dhardy]

@vks @benjamin-lieser implementing Distribution<Vec3> for StandardUniform makes as much sense as it does for f32 etc: not a whole lot, though apparently enough that we inherited this functionality and never got rid of it.

Adding derive support for StandardUniform shouldn't be too hard on some types, though it would be on others; e.g. glam-rs has:

// Basic 3D vector over f32 uses individual fields
#[cfg_attr(not(target_arch = "spirv"), repr(C))]
#[cfg_attr(target_arch = "spirv", repr(simd))]
pub struct Vec3 {
    pub x: f32,
    pub y: f32,
    pub z: f32,
}

// But the SIMD-optimised type does not
#[repr(transparent)]
pub struct Vec3A(pub(crate) __m128);

Supporting derivation of Uniform on such types is harder since (a) it needs to pass and unpack low/high limits and (b) define a supporting sampler type (which could be hidden; it is still nameable through the SampleUniform trait), but it would also save more code.

But @LikeLakers2 I still don't know whether it would actually make sense for glam-rs to use those derive macros though, most notably because it would require dependencies on proc-macro crates like syn, increasing compile times for glam-rs.

So I think I'll just close this issue for now, but if someone wants to write such a macro and link it here (or better yet, add links to the rand/book docs), please do.

[LikeLakers2]

So I think I'll just close this issue for now, but if someone wants to write such a macro and link it here (or better yet, add links to the rand/book docs), please do.

For what it's worth, I tried my hand at writing such a thing - https://github.com/LikeLakers2/michis_rand_distr_derive - though it's far from complete, and I've been busy with other things for a while. Maybe I'll work again on it soon.

Still, if anyone wants to start their own work, feel free to base it off mine. I hope I left enough comments for the work thus far to be somewhat understandable.