Skip to content

Commit d80fec1

Browse files
rockyrocky
authored
Merge pull request #805 from Mathics3/go-over-random-docs
Go over Random builtins docs to get this standard
2 parents c84e7a4 + 9544aad commit d80fec1

File tree

1 file changed

+144
-122
lines changed

1 file changed

+144
-122
lines changed

‎mathics/builtin/numbers/randomnumbers.py‎

Lines changed: 144 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -101,43 +101,6 @@ def randchoice(self, n, size, replace, p):
101101
return numpy.random.choice(n, size=size, replace=replace, p=p)
102102

103103

104-
class RandomState(Builtin):
105-
"""
106-
<url>:WMA: https://reference.wolfram.com/language/ref/RandomState.html</url>
107-
<dl>
108-
<dt>'$RandomState'
109-
<dd>is a long number representing the internal state of the \
110-
pseudo-random number generator.
111-
</dl>
112-
113-
>> Mod[$RandomState, 10^100]
114-
= ...
115-
>> IntegerLength[$RandomState]
116-
= ...
117-
118-
So far, it is not possible to assign values to '$RandomState'.
119-
>> $RandomState = 42
120-
: It is not possible to change the random state.
121-
= 42
122-
Not even to its own value:
123-
>> $RandomState = $RandomState;
124-
: It is not possible to change the random state.
125-
"""
126-
127-
name = "$RandomState"
128-
messages = {
129-
"rndst": "It is not possible to change the random state.",
130-
# "`1` is not a valid random state.",
131-
}
132-
summary_text = "internal state of the (pseudo)random number generator"
133-
134-
def eval(self, evaluation):
135-
"$RandomState"
136-
137-
with RandomEnv(evaluation):
138-
return Integer(get_random_state())
139-
140-
141104
class _RandomBase(Builtin):
142105
messages = {
143106
"array": (
@@ -168,16 +131,22 @@ def _size_to_python(self, domain, size, evaluation):
168131

169132

170133
class _RandomSelection(_RandomBase):
171-
# implementation note: weights are clipped to numpy floats. this might be different from MMA
172-
# where weights might be handled with full dynamic precision support through the whole computation.
173-
# we try to limit the error by normalizing weights with full precision, and then clipping to float.
174-
# since weights are probabilities into a finite set, this should not make a difference.
134+
# Implementation note: weights are clipped to numpy floats. this
135+
# might be different from MMA where weights might be handled with
136+
# full dynamic precision support through the whole computation.
137+
# we try to limit the error by normalizing weights with full
138+
# precision, and then clipping to float. since weights are
139+
# probabilities into a finite set, this should not make a
140+
# difference.
175141

176142
messages = {
177-
"wghtv": "The weights on the left-hand side of `1` has to be a list of non-negative numbers "
178-
+ "with the same length as the list of items on the right-hand side.",
179-
"lrwl": "`1` has to be a list of items or a rule of the form weights -> choices.",
180-
"smplen": "RandomSample cannot choose `1` samples, as this are more samples than there are in `2`. "
143+
"wghtv": "The weights on the left-hand side of `1` has to be a list of "
144+
"non-negative numbers with the same length as the list of items "
145+
"on the right-hand side.",
146+
"lrwl": "`1` has to be a list of items or a rule of the form "
147+
"weights -> choices.",
148+
"smplen": "RandomSample cannot choose `1` samples, as this are more samples "
149+
"than there are in `2`. "
181150
+ "Use RandomChoice to choose items from a set with replacing.",
182151
}
183152

@@ -249,7 +218,7 @@ def _weights_to_python(self, weights, evaluation):
249218
class Random(Builtin):
250219
"""
251220
<url>
252-
:WMA:
221+
:WMA link:
253222
https://reference.wolfram.com/language/ref/Random.html</url>
254223
<dl>
255224
<dt>'Random[]'
@@ -280,18 +249,81 @@ class Random(Builtin):
280249
summary_text = "pick a random number"
281250

282251

252+
class RandomChoice(_RandomSelection):
253+
"""
254+
<url>
255+
:WMA link:
256+
https://reference.wolfram.com/language/ref/RandomChoice.html</url>
257+
258+
<dl>
259+
260+
<dt>'RandomChoice[$items$]'
261+
<dd>randomly picks one item from $items$.
262+
263+
<dt>'RandomChoice[$items$, $n$]'
264+
<dd>randomly picks $n$ items from $items$. Each pick in the $n$ picks happens \
265+
from the given set of $items$, so each item can be picked any number of times.
266+
267+
<dt>'RandomChoice[$items$, {$n1$, $n2$, ...}]'
268+
<dd>randomly picks items from $items$ and arranges the picked items in the \
269+
nested list structure described by {$n1$, $n2$, ...}.
270+
271+
<dt>'RandomChoice[$weights$ -> $items$, $n$]'
272+
<dd>randomly picks $n$ items from $items$ and uses the corresponding numeric \
273+
values in $weights$ to determine how probable it is for each item in $items$ \
274+
to get picked (in the long run, items with higher weights will get picked \
275+
more often than ones with lower weight).
276+
277+
<dt>'RandomChoice[$weights$ -> $items$]'
278+
<dd>randomly picks one items from $items$ using weights $weights$.
279+
280+
<dt>'RandomChoice[$weights$ -> $items$, {$n1$, $n2$, ...}]'
281+
<dd>randomly picks a structured list of items from $items$ using weights \
282+
$weights$.
283+
</dl>
284+
285+
Note: 'SeedRandom' is used below so we get repeatable "random" numbers that we \
286+
can test.
287+
288+
>> SeedRandom[42]
289+
>> RandomChoice[{a, b, c}]
290+
= {c}
291+
>> SeedRandom[42] (* Set for repeatable randomness *)
292+
>> RandomChoice[{a, b, c}, 20]
293+
= {c, a, c, c, a, a, c, b, c, c, c, c, a, c, b, a, b, b, b, b}
294+
>> SeedRandom[42]
295+
>> RandomChoice[{"a", {1, 2}, x, {}}, 10]
296+
= {x, {}, a, x, x, {}, a, a, x, {1, 2}}
297+
>> SeedRandom[42]
298+
>> RandomChoice[{a, b, c}, {5, 2}]
299+
= {{c, a}, {c, c}, {a, a}, {c, b}, {c, c}}
300+
>> SeedRandom[42]
301+
>> RandomChoice[{1, 100, 5} -> {a, b, c}, 20]
302+
= {b, b, b, b, b, b, b, b, b, b, b, c, b, b, b, b, b, b, b, b}
303+
"""
304+
305+
_replace = True
306+
summary_text = "pick items randomly from a given list"
307+
308+
283309
class RandomComplex(Builtin):
284310
"""
285-
<url>:WMA: https://reference.wolfram.com/language/ref/RandomComplex.html</url>)
311+
<url>
312+
:WMA link:
313+
https://reference.wolfram.com/language/ref/RandomComplex.html</url>
314+
286315
<dl>
287316
<dt>'RandomComplex[{$z_min$, $z_max$}]'
288-
<dd>yields a pseudorandom complex number in the rectangle with complex corners $z_min$ and $z_max$.
317+
<dd>yields a pseudorandom complex number in the rectangle with complex corners \
318+
$z_min$ and $z_max$.
289319
290320
<dt>'RandomComplex[$z_max$]'
291-
<dd>yields a pseudorandom complex number in the rectangle with corners at the origin and at $z_max$.
321+
<dd>yields a pseudorandom complex number in the rectangle with corners at the \
322+
origin and at $z_max$.
292323
293324
<dt>'RandomComplex[]'
294-
<dd>yields a pseudorandom complex number with real and imaginary parts from 0 to 1.
325+
<dd>yields a pseudorandom complex number with real and imaginary parts from 0 \
326+
to 1.
295327
296328
<dt>'RandomComplex[$range$, $n$]'
297329
<dd>gives a list of $n$ pseudorandom complex numbers.
@@ -407,7 +439,9 @@ def eval_list(self, zmin, zmax, ns, evaluation):
407439

408440
class RandomInteger(Builtin):
409441
"""
410-
<url>:WMA: https://reference.wolfram.com/language/ref/RandomInteger.html</url>)
442+
<url>
443+
:WMA link:
444+
https://reference.wolfram.com/language/ref/RandomInteger.html</url>
411445
<dl>
412446
<dt>'RandomInteger[{$min$, $max$}]'
413447
<dd>yields a pseudorandom integer in the range from $min$ to \
@@ -485,7 +519,10 @@ def eval_list(self, rmin, rmax, ns, evaluation):
485519

486520
class RandomReal(Builtin):
487521
"""
488-
<url>:WMA: https://reference.wolfram.com/language/ref/RandomReal.html</url>)
522+
<url>
523+
:WMA link:
524+
https://reference.wolfram.com/language/ref/RandomReal.html</url>
525+
489526
<dl>
490527
<dt>'RandomReal[{$min$, $max$}]'
491528
<dd>yields a pseudorandom real number in the range from $min$ to $max$.
@@ -581,9 +618,49 @@ def eval_list(self, xmin, xmax, ns, evaluation):
581618
)
582619

583620

621+
class RandomState(Builtin):
622+
"""
623+
<url>:WMA link:
624+
https://reference.wolfram.com/language/ref/RandomState.html</url>
625+
<dl>
626+
<dt>'$RandomState'
627+
<dd>is a long number representing the internal state of the \
628+
pseudo-random number generator.
629+
</dl>
630+
631+
>> Mod[$RandomState, 10^100]
632+
= ...
633+
>> IntegerLength[$RandomState]
634+
= ...
635+
636+
So far, it is not possible to assign values to '$RandomState'.
637+
>> $RandomState = 42
638+
: It is not possible to change the random state.
639+
= 42
640+
Not even to its own value:
641+
>> $RandomState = $RandomState;
642+
: It is not possible to change the random state.
643+
"""
644+
645+
name = "$RandomState"
646+
messages = {
647+
"rndst": "It is not possible to change the random state.",
648+
# "`1` is not a valid random state.",
649+
}
650+
summary_text = "internal state of the (pseudo)random number generator"
651+
652+
def eval(self, evaluation):
653+
"$RandomState"
654+
655+
with RandomEnv(evaluation):
656+
return Integer(get_random_state())
657+
658+
584659
class SeedRandom(Builtin):
585660
"""
586-
<url>:WMA: https://reference.wolfram.com/language/ref/SeedRandom.html</url>)
661+
<url>
662+
:WMA link:
663+
https://reference.wolfram.com/language/ref/SeedRandom.html</url>
587664
<dl>
588665
<dt>'SeedRandom[$n$]'
589666
<dd>resets the pseudorandom generator with seed $n$.
@@ -651,94 +728,39 @@ def eval_empty(self, evaluation):
651728
return SymbolNull
652729

653730

654-
# If numpy is not in the system, the following classes are going to be redefined as None. flake8 complains about this.
655-
# What should happen here is that, or the classes be defined just if numpy is there, or to use a fallback native
656-
# implementation.
657-
658-
659-
class RandomChoice(_RandomSelection):
660-
"""
661-
<url>:WMA: https://reference.wolfram.com/language/ref/RandomChoice.html</url>
662-
663-
<dl>
664-
665-
<dt>'RandomChoice[$items$]'
666-
<dd>randomly picks one item from $items$.
667-
668-
<dt>'RandomChoice[$items$, $n$]'
669-
<dd>randomly picks $n$ items from $items$. Each pick in the $n$ picks happens from the \
670-
given set of $items$, so each item can be picked any number of times.
671-
672-
<dt>'RandomChoice[$items$, {$n1$, $n2$, ...}]'
673-
<dd>randomly picks items from $items$ and arranges the picked items in the nested list \
674-
structure described by {$n1$, $n2$, ...}.
675-
676-
<dt>'RandomChoice[$weights$ -> $items$, $n$]'
677-
<dd>randomly picks $n$ items from $items$ and uses the corresponding numeric values in \
678-
$weights$ to determine how probable it is for each item in $items$ to get picked (in the \
679-
long run, items with higher weights will get picked more often than ones with lower weight).
680-
681-
<dt>'RandomChoice[$weights$ -> $items$]'
682-
<dd>randomly picks one items from $items$ using weights $weights$.
683-
684-
<dt>'RandomChoice[$weights$ -> $items$, {$n1$, $n2$, ...}]'
685-
<dd>randomly picks a structured list of items from $items$ using weights $weights$.
686-
</dl>
687-
688-
Note: 'SeedRandom' is used below so we get repeatable "random" numbers that we can test.
689-
690-
>> SeedRandom[42]
691-
>> RandomChoice[{a, b, c}]
692-
= {c}
693-
>> SeedRandom[42] (* Set for repeatable randomness *)
694-
>> RandomChoice[{a, b, c}, 20]
695-
= {c, a, c, c, a, a, c, b, c, c, c, c, a, c, b, a, b, b, b, b}
696-
>> SeedRandom[42]
697-
>> RandomChoice[{"a", {1, 2}, x, {}}, 10]
698-
= {x, {}, a, x, x, {}, a, a, x, {1, 2}}
699-
>> SeedRandom[42]
700-
>> RandomChoice[{a, b, c}, {5, 2}]
701-
= {{c, a}, {c, c}, {a, a}, {c, b}, {c, c}}
702-
>> SeedRandom[42]
703-
>> RandomChoice[{1, 100, 5} -> {a, b, c}, 20]
704-
= {b, b, b, b, b, b, b, b, b, b, b, c, b, b, b, b, b, b, b, b}
705-
"""
706-
707-
_replace = True
708-
summary_text = "pick items randomly from a given list"
709-
710-
711731
class RandomSample(_RandomSelection):
712732
"""
713-
<url>:WMA: https://reference.wolfram.com/language/ref/RandomSample.html</url>
733+
<url>:WMA link:
734+
https://reference.wolfram.com/language/ref/RandomSample.html</url>
714735
715736
<dl>
716737
<dt>'RandomSample[$items$]'
717738
<dd>randomly picks one item from $items$.
718739
719740
<dt>'RandomSample[$items$, $n$]'
720-
<dd>randomly picks $n$ items from $items$. Each pick in the $n$ picks happens after the \
721-
previous items picked have been removed from $items$, so each item can be picked at most \
722-
once.
741+
<dd>randomly picks $n$ items from $items$. Each pick in the $n$ picks happens \
742+
after the previous items picked have been removed from $items$, so each item \
743+
can be picked at most once.
723744
724745
<dt>'RandomSample[$items$, {$n1$, $n2$, ...}]'
725-
<dd>randomly picks items from $items$ and arranges the picked items in the nested list \
726-
structure described by {$n1$, $n2$, ...}. \
746+
<dd>randomly picks items from $items$ and arranges the picked items in the \
747+
nested list structure described by {$n1$, $n2$, ...}. \
727748
Each item gets picked at most once.
728749
729750
<dt>'RandomSample[$weights$ -> $items$, $n$]'
730-
<dd>randomly picks $n$ items from $items$ and uses the corresponding numeric values in \
731-
$weights$ to determine how probable it is for each item in $items$ to get picked (in the \
732-
long run, items with higher weights will get picked more often than ones with lower weight). \
733-
Each item gets picked at most once.
751+
<dd>randomly picks $n$ items from $items$ and uses the corresponding numeric \
752+
values in $weights$ to determine how probable it is for each item in $items$ \
753+
to get picked (in the long run, items with higher weights will get \
754+
picked more often than ones with lower weight). Each item gets picked at\
755+
most once.
734756
735757
<dt>'RandomSample[$weights$ -> $items$]'
736758
<dd>randomly picks one items from $items$ using weights $weights$. \
737759
Each item gets picked at most once.
738760
739761
<dt>'RandomSample[$weights$ -> $items$, {$n1$, $n2$, ...}]'
740-
<dd>randomly picks a structured list of items from $items$ using weights $weights$. Each \
741-
item gets picked at most once.
762+
<dd>randomly picks a structured list of items from $items$ using weights $weights$.
763+
Each item gets picked at most once.
742764
</dl>
743765
744766
>> SeedRandom[42]

0 commit comments

Comments
 (0)