Skip to content

Commit 5286f22

Browse files
ZorPastamanZorPastaman
committed
Readme and some little fixes
1 parent ffe51bd commit 5286f22

File tree

14 files changed

+236
-19
lines changed

14 files changed

+236
-19
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
77

88
## [Unreleased]
99

10+
## [1.0.0] - 2020-09-19
11+
1012
### Added
1113

1214
#### Distributions
@@ -53,4 +55,5 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
5355
- Default Int Uniform generator provider.
5456
- Default Marsaglia generator provider.
5557

56-
[unreleased]: https://github.com/ZorPastaman/Random-Generators
58+
[unreleased]: https://github.com/ZorPastaman/Random-Generators/compare/v1.0.0...HEAD
59+
[1.0.0]: https://github.com/ZorPastaman/Random-Generators/releases/tag/v1.0.0

‎README.md‎

Lines changed: 202 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,203 @@
11
# Random-Generators
2-
A collection of random generators and distributions. WIP.
2+
Random generators for Unity is a collection of random generators,
3+
different distributions, modificators and filters.
4+
5+
The library has a useful infrastructure that makes it easy to expand it and add new
6+
distributions, modificators, filters and random generators.
7+
8+
The library is very fast and heap allocation free.
9+
10+
## Installation
11+
12+
This repo is a regular Unity package. You can install it as your project dependency.
13+
More here: https://docs.unity3d.com/Manual/upm-dependencies.html.
14+
15+
## Usage
16+
17+
1. Create a provider from **Assets/Create/Random Generator Providers/** or choose one of
18+
pre-made providers among
19+
**DefaultBoolUniformGeneratorProvider**, **DefaultIntUniformGeneratorProvider**,
20+
**DefaultFloatUniformGeneratorProvider**, **DefaultMarsagliaGeneratorProvider** and
21+
**DefaultBatesGeneratorProvider**.
22+
2. Add **ContinuousGeneratorProviderReference** for continuous distributions or
23+
**DiscreteGeneratorProviderReference** for discrete distributions as a serialize field
24+
into your component.
25+
3. Link a selected provider into a right provider reference. Toggle on/off Shared.
26+
If Shared is on, a generator is created once and reused by all requesters.
27+
If Shared is off, a new generator is created for every requester.
28+
4. In your script, call **ContinuousGeneratorProviderReference.generator** or
29+
**DiscreteGeneratorProviderReference.GetGenerator<T>()** and cache the result.
30+
They return a **IContinuousGenerator** or **IDiscreteGenerator<T>** that generate
31+
a random value.
32+
5. Call **Generate()** in a gotten generator to get a random value that corresponds to
33+
a selected distribution.
34+
35+
Also, you can create your own infrastructure. Every part of this library is public and
36+
available separately from other parts.
37+
38+
## Parts
39+
40+
### Distributions
41+
42+
Distributions are just algorithms in static classes that return a random value(s).
43+
They usually require an independent and identically distributed random generator.
44+
By default, Unity generator is used as such a generator.
45+
Also, the distributions support `Func<float>` and `IContinuousGenerator` as an iid random generator.
46+
47+
### Generators
48+
49+
Generators are standard c# classes that implement [IContinuousGenerator](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/ContinuousDistributions/IContinuousGenerator.cs)
50+
or [IDiscreteGenerator<T>](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/DiscreteDistributions/IDiscreteGenerator.cs)
51+
and wrap one of the methods of the distributions.
52+
53+
### Generator Providers
54+
55+
Generator providers are scriptable objects and can be linked to a serialize field in Unity components.
56+
They wrap generators and provide unique and shared instances of them.
57+
58+
#### List of continuous generator algorithms
59+
60+
- [Acceptance Rejection](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/IndependentDistributions/AcceptanceRejectionDistribution) -
61+
[Wikipedia](https://en.wikipedia.org/wiki/Rejection_sampling);
62+
- [Bates](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/NormalDistributions/BatesDistribution) -
63+
[Wikipedia](https://en.wikipedia.org/wiki/Bates_distribution);
64+
- [Box-Muller](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/NormalDistributions/BoxMullerDistribution) -
65+
[Wikipedia](https://en.wikipedia.org/wiki/Box%E2%80%93Muller_transform);
66+
- [Irwin-Hall](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/NormalDistributions/IrwinHallDistribution) -
67+
[Wikipedia](https://en.wikipedia.org/wiki/Irwin%E2%80%93Hall_distribution);
68+
- [Marsaglia](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/NormalDistributions/MarsagliaDistribution) -
69+
[Wikipedia](https://en.wikipedia.org/wiki/Marsaglia_polar_method);
70+
- [C# Random Generator Wrapper](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/UniformDistributions/SharpDistribution) -
71+
[Microsoft Docs](https://docs.microsoft.com/en-us/dotnet/api/system.random?view=netframework-4.8);
72+
- [Unity Random Generator Wrapper](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/UniformDistributions/UnityDistribution) -
73+
[Unity Docs](https://docs.unity3d.com/ScriptReference/Random.html).
74+
75+
#### List of discrete generator algorithms
76+
77+
- [Bernoulli](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/BernoulliDistribution) -
78+
[Wikipedia](https://en.wikipedia.org/wiki/Bernoulli_distribution);
79+
- [Binomial](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/BinomialDistribution) -
80+
[Wikipedia](https://en.wikipedia.org/wiki/Binomial_distribution);
81+
- [Poisson](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/PoissonDistribution) -
82+
[Wikipedia](https://en.wikipedia.org/wiki/Poisson_distribution);
83+
- [C# Random Generator Wrapper](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/SharpDistribution) -
84+
[Microsoft Docs](https://docs.microsoft.com/en-us/dotnet/api/system.random?view=netframework-4.8);
85+
- [Unity Random Generator Wrapper](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/UnityDistribution) -
86+
[Unity Docs](https://docs.unity3d.com/ScriptReference/Random.html);
87+
- [Weighted](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/WeightedDistribution) -
88+
[Wikipedia](https://en.wikipedia.org/wiki/Weight_function).
89+
90+
### Modificators
91+
92+
Modificators are standard c# classes that implement [IContinuousGenerator](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/ContinuousDistributions/IContinuousGenerator.cs)
93+
or [IDiscreteGenerator<T>](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/DiscreteDistributions/IDiscreteGenerator.cs)
94+
but they are not actually generators, they take a generated value from a depended generator, modify it somehow and return a result.
95+
96+
### Modificator Providers
97+
98+
Modificator providers are scriptable objects and can be linked to a serialize field in Unity components.
99+
They wrap modificators and provide unique and shared instances of them.
100+
101+
#### List of continuous modificators
102+
103+
- [Clamp](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/DistributionModificators/Clamp) -
104+
a continuous value is clamped between specified minimum and maximum values;
105+
- [Round](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/DistributionModificators/Round) -
106+
a continuous value is rounded to a nearest integer.
107+
108+
#### List of discrete modificators
109+
110+
- [Clamp](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/DistributionModificators/Clamp) -
111+
a discrete value is clamped between specified minimum and maximum values;
112+
- [Round to Int](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/DistributionModificators/Round) -
113+
a continuous value is rounded to a nearest integer and returned as a discrete value.
114+
115+
### Filters
116+
117+
Filters are algorithms in static classes that check if a new generated value corresponds to their rules.
118+
They usually forbid certain sequences of random generated values.
119+
120+
### Filter Wrappers
121+
122+
Filter wrappers are standard c# classes that implement [IContinuousFilter](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/ContinuousDistributions/DistributionFilters/IContinuousFilter.cs)
123+
or [IDiscreteFilter](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/DiscreteDistributions/DistributionFilters/IDiscreteFilter.cs)
124+
and wrap one of the methods of filters.
125+
126+
### Filter Providers
127+
128+
Filter providers are scriptable objects and can be linked to a serialize field in Unity components.
129+
They wrap filter wrappers and provide unique and shared instances of them.
130+
131+
### Filtered Generators
132+
133+
Filtered generators are standard c# classes that implement [IContinuousFilter](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/ContinuousDistributions/DistributionFilters/IContinuousFilter.cs)
134+
or [IDiscreteFilter](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/DiscreteDistributions/DistributionFilters/IDiscreteFilter.cs).
135+
They take a generated value from a depended generator and check that value with filters.
136+
If at least one filter doesn't approve a new value, it's regenerated and checked again.
137+
138+
### Filtered Generator Providers
139+
140+
Filtered generator providers are scriptable objects and can be linked to a serialize field in Unity components.
141+
They wrap filtered generators and provide unique and shared instances of them.
142+
143+
#### List of continuous filters
144+
145+
- [Ascendant Sequence](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/DistributionFilters/AscendantSequenceFilters) -
146+
checks if a value continues an ascendant sequence and it needs to be regenerated;
147+
- [Close](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/DistributionFilters/CloseFilters) -
148+
checks if a value continues a sequence where every value is close enough to a reference value and needs to be regenerated;
149+
- [Descendant Sequence](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/DistributionFilters/DescendantSequenceFilters) -
150+
checks if a value continues a descendant sequence and it needs to be regenerated;
151+
- [Greater](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/DistributionFilters/GreaterFilters) -
152+
checks if a value continues a sequence where every value is greater than a reference value and needs to be regenerated;
153+
- [In Range](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/DistributionFilters/InRangeFilters) -
154+
checks if a value continues a sequence where every value is in range between the minimum and maximum and needs to be regenerated;
155+
- [Less](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/DistributionFilters/LessFilters) -
156+
checks if a value continues a sequence where every value is less than a reference value and needs to be regenerated;
157+
- [Little Difference](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/DistributionFilters/LittleDifferenceFilters) -
158+
checks if a value continues a sequence where consecutive elements differ by less than a required difference and needs to be regenerated;
159+
- [Not In Range](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/ContinuousDistributions/DistributionFilters/NotInRangeFilters) -
160+
checks if a value continues a sequence where every value is in range between the minimum and maximum and needs to be regenerated.
161+
162+
#### List of discrete filters
163+
164+
- [Ascendant Sequence](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/DistributionFilters/AscendantSequenceFilters) -
165+
checks if a value continues an ascendant sequence and it needs to be regenerated;
166+
- [Close](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/DistributionFilters/CloseFilters) -
167+
checks if a value continues a sequence where every value is close enough to a reference value and needs to be regenerated;
168+
- [Descendant Sequence](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/DistributionFilters/DescendantSequenceFilters) -
169+
checks if a value continues a descendant sequence and it needs to be regenerated;
170+
- [Frequent Value](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/DistributionFilters/FrequentValueFilters) -
171+
checks if a value is contained in a sequence more than allowed times and needs to be regenerated;
172+
- [Opposite Pattern](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/DistributionFilters/OppositePatternFilters) -
173+
checks if a value forms a pattern opposite to a previous pattern and needs to be regenerated;
174+
- [Pair](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/DistributionFilters/PairFilters) -
175+
Checks if a value is contained in a sequence some elements before and needs to be regenerated;
176+
- [Repeating Pattern](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/DistributionFilters/RepeatingPatternFilters) -
177+
checks if a new value forms a pattern the same to a pattern some elements before and needs to be regenerated;
178+
- [Same Pattern](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/DistributionFilters/SamePatternFilters) -
179+
checks if a value forms the same pattern in a sequence as a pattern before and needs to be regenerated;
180+
- [Same Sequence](https://github.com/ZorPastaman/Random-Generators/tree/master/Runtime/DiscreteDistributions/DistributionFilters/SameSequenceFilters) -
181+
checks if a value continues a sequence where every value is the same and needs to be regenerated.
182+
183+
### References
184+
185+
References are serializable structs that wrap an access to unique and shared generators or filters from their providers.
186+
All the references require a link to a provider. Also, they have a toggle **Shared**.
187+
If it's on, a reference returns a shared generator or filter. If it's off, a reference returns a unique generator or filter.
188+
189+
#### List of references
190+
191+
- [Continuous Generator Provider Reference](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/ContinuousDistributions/ContinuousGeneratorProviderReference.cs);
192+
- [Discrete Generator Provider Reference](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/DiscreteDistributions/DiscreteGeneratorProviderReference.cs);
193+
- [Continuous Filter Provider Reference](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/ContinuousDistributions/DistributionFilters/ContinuousFilterProviderReference.cs);
194+
- [Discrete Filter Provider Reference](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/DiscreteDistributions/DistributionFilters/DiscreteFilterProviderReference.cs).
195+
196+
### Property drawers
197+
198+
- [Require Discrete Generator](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/PropertyDrawerAttributes/RequireDiscreteGenerator.cs) -
199+
doesn't allow to set a generator with a wrong type into
200+
[Discrete Generator Provider Reference](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/DiscreteDistributions/DiscreteGeneratorProviderReference.cs);
201+
- [Require Discrete Filter](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/PropertyDrawerAttributes/RequireDiscreteFilter.cs) -
202+
doesn't allow to set a filter with a wrong type into
203+
[Discrete Filter Provider Reference](https://github.com/ZorPastaman/Random-Generators/blob/master/Runtime/DiscreteDistributions/DistributionFilters/DiscreteFilterProviderReference.cs).

‎Runtime/ContinuousDistributions/DistributionFilters/GreaterFilters/GreaterFiltering.cs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ public static class GreaterFiltering
1010
public const byte DefaultGreaterSequenceLength = 3;
1111

1212
/// <summary>
13-
/// Checks if the value <paramref name="newValue"/> continues the greater sequence <paramref name="sequence"/>
13+
/// Checks if the value <paramref name="newValue"/> continues the sequence <paramref name="sequence"/>
14+
/// where every value is greater than the reference value <paramref name="referenceValue"/>
1415
/// and needs to be regenerated.
1516
/// </summary>
1617
/// <param name="sequence">Sequence of generated and already applied values.</param>

‎Runtime/ContinuousDistributions/DistributionFilters/InRangeFilters/InRangeFiltering.cs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ public static class InRangeFiltering
1111
public const byte DefaultInRangeSequenceLength = 3;
1212

1313
/// <summary>
14-
/// Checks if the value <paramref name="newValue"/> continues the in range sequence <paramref name="sequence"/>
14+
/// Checks if the value <paramref name="newValue"/> continues the sequence <paramref name="sequence"/>
15+
/// where every value is in range between the minimum <paramref name="min"/> and maximum <paramref name="max"/>
1516
/// and needs to be regenerated.
1617
/// </summary>
1718
/// <param name="sequence">Sequence of generated and already applied values.</param>

‎Runtime/ContinuousDistributions/DistributionFilters/LessFilters/LessFiltering.cs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ public static class LessFiltering
1010
public const byte DefaultLessSequenceLength = 3;
1111

1212
/// <summary>
13-
/// Checks if the value <paramref name="newValue"/> continues the less sequence <paramref name="sequence"/>
13+
/// Checks if the value <paramref name="newValue"/> continues the sequence <paramref name="sequence"/>
14+
/// where every value is less than the reference value <paramref name="referenceValue"/>
1415
/// and needs to be regenerated.
1516
/// </summary>
1617
/// <param name="sequence">Sequence of generated and already applied values.</param>

‎Runtime/ContinuousDistributions/DistributionFilters/NotInRangeFilters/NotInRangeFiltering.cs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,9 @@ public static class NotInRangeFiltering
1111
public const byte DefaultNotInRangeSequenceLength = 3;
1212

1313
/// <summary>
14-
/// Checks if the value <paramref name="newValue"/> continues the not in range sequence
15-
/// <paramref name="sequence"/> and needs to be regenerated.
14+
/// Checks if the value <paramref name="newValue"/> continues the sequence <paramref name="sequence"/>
15+
/// where every value is not in range between the minimum <paramref name="min"/> and maximum <paramref name="max"/>
16+
/// and needs to be regenerated.
1617
/// </summary>
1718
/// <param name="sequence">Sequence of generated and already applied values.</param>
1819
/// <param name="newValue">New generated value.</param>

‎Runtime/ContinuousDistributions/NormalDistributions/IrwinHallDistribution/IrwinHallDistribution.cs‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
// Copyright (c) 2020 Vladimir Popov [email protected] https://github.com/ZorPastaman/Random-Generators
22

33
using System;
4-
using System.Runtime.CompilerServices;
54
using JetBrains.Annotations;
65
using Random = UnityEngine.Random;
76

‎Runtime/DiscreteDistributions/DistributionFilters/FilteredGeneratorProviders/DiscreteFilteredGeneratorProvider.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -178,10 +178,10 @@ private IDiscreteFilter<T>[] filters
178178
{
179179
if (m_filtersCache == null)
180180
{
181-
int filtersCount = m_FilterProviders.Length;
182-
m_filtersCache = new IDiscreteFilter<T>[filtersCount];
181+
int count = m_FilterProviders.Length;
182+
m_filtersCache = new IDiscreteFilter<T>[count];
183183

184-
for (int i = 0; i < filtersCount; ++i)
184+
for (int i = 0; i < count; ++i)
185185
{
186186
m_filtersCache[i] = m_FilterProviders[i].GetFilter<T>();
187187
}

‎Runtime/DiscreteDistributions/DistributionFilters/FrequentValueFilters/FrequentValueFiltering.cs‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
// Copyright (c) 2020 Vladimir Popov [email protected] https://github.com/ZorPastaman/Random-Generators
22

33
using System;
4-
using System.Collections.Generic;
54
using JetBrains.Annotations;
65

76
namespace Zor.RandomGenerators.DiscreteDistributions.DistributionFilters

‎Runtime/DiscreteDistributions/DistributionFilters/PairFilters/Filters/PairFilter.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ namespace Zor.RandomGenerators.DiscreteDistributions.DistributionFilters
1010
/// The filter recommends to regenerate a new value if a sequence has the same value some elements before.
1111
/// </summary>
1212
/// <typeparam name="T"></typeparam>
13-
public sealed class PairFilter<T> : IDiscreteFilter<T> where T : IEquatable<T>
13+
public sealed class PairFilter<T> : IPairFilter<T> where T : IEquatable<T>
1414
{
1515
private byte m_elementsBetweenPair;
1616

0 commit comments

Comments
 (0)