Skip to content

Update description of functions in RandomState class #1264

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 21, 2022
Merged

Update description of functions in RandomState class #1264

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 47 additions & 34 deletions dpnp/random/dpnp_random_state.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,22 @@ class RandomState:
A container for the Mersenne Twister pseudo-random number generator.

For full documentation refer to :obj:`numpy.random.RandomState`.

Parameters
----------
device : {None, string, SyclDevice, SyclQueue}, optional
An array API concept of device where the output array is created.
`device` can be ``None`` (the default), a oneAPI filter selector string,
an instance of :class:`dpctl.SyclDevice` corresponding to a non-partitioned SYCL device,
an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by
:obj:`dpnp.dpnp_array.dpnp_array.device` property.
sycl_queue : {None, SyclQueue}, optional
The SYCL queue to use for output array allocation and copying.

Limitations
-----------
Parameter `seed` is supported as either a integer scalar or array_like
of maximumum three integer scalars.
"""

def __init__(self, seed=None, device=None, sycl_queue=None):
Expand Down Expand Up @@ -107,9 +123,9 @@ def _is_signbit_scalar(self, x):

def _validate_float_dtype(self, dtype, supported_types):
"""
Test an input floating type if it is listed in ``supported_types`` and
Test an input floating type if it is listed in `supported_types` and
if it is supported by the used SYCL device.
If ``dtype`` is None, default floating type will be validating.
If `dtype` is ``None``, default floating type will be validating.
Return the examined floating type if it follows all validation checks.
"""

Expand Down Expand Up @@ -139,7 +155,7 @@ def get_state(self):

def get_sycl_queue(self):
"""
Return an instance of of :class:`dpctl.SyclQueue` used within the generator for data allocation.
Return an instance of :class:`dpctl.SyclQueue` used within the generator for data allocation.

Returns
-------
Expand All @@ -151,7 +167,7 @@ def get_sycl_queue(self):

def get_sycl_device(self):
"""
Return an instance of of :class:`dpctl.SyclDevice` used within the generator to allocate data on.
Return an instance of :class:`dpctl.SyclDevice` used within the generator to allocate data on.

Returns
-------
Expand All @@ -169,25 +185,24 @@ def normal(self, loc=0.0, scale=1.0, size=None, dtype=None, usm_type="device"):

Parameters
----------
usm_type : ("device" | "shared" | "host"), optional
usm_type : {"device", "shared", "host"}, optional
The type of SYCL USM allocation for the output array.

Returns
-------
out : dpnp.ndarray
Drawn samples from the parameterized normal distribution.
Output array data type is the same as input ``dtype``. If ``dtype`` is None (default),
:obj:`dpnp.float64` type will be used if device supports it or :obj:`dpnp.float32` otherwise.
Output array data type is the same as input `dtype`. If `dtype` is ``None`` (the default),
:obj:`dpnp.float64` type will be used if device supports it, or :obj:`dpnp.float32` otherwise.

Limitations
-----------
Parameters ``loc`` and ``scale`` are supported as scalar. Otherwise,
Parameters `loc` and `scale` are supported as scalar. Otherwise,
:obj:`numpy.random.RandomState.normal(loc, scale, size)` samples are drawn.
Parameter ``dtype`` is supported only for :obj:`dpnp.float32`, :obj:`dpnp.float64` or `None`.
Parameter `dtype` is supported only as :obj:`dpnp.float32`, :obj:`dpnp.float64` or ``None``.

Examples
--------
Draw samples from the distribution:
>>> s = dpnp.random.RandomState().normal(loc=3.7, scale=2.5, size=(2, 4))
>>> print(s)
[[ 1.58997253 -0.84288406 2.33836967 4.16394577]
Expand Down Expand Up @@ -241,14 +256,14 @@ def rand(self, *args, usm_type="device"):

Parameters
----------
usm_type : ("device" | "shared" | "host"), optional
usm_type : {"device", "shared", "host"}, optional
The type of SYCL USM allocation for the output array.

Returns
-------
out : dpnp.ndarray
Random values in a given shape.
Output array data type is :obj:`dpnp.float64` if device supports it or :obj:`dpnp.float32` otherwise.
Output array data type is :obj:`dpnp.float64` if device supports it, or :obj:`dpnp.float32` otherwise.

Examples
--------
Expand Down Expand Up @@ -284,21 +299,21 @@ def randint(self, low, high=None, size=None, dtype=int, usm_type="device"):

Parameters
----------
usm_type : ("device" | "shared" | "host"), optional
usm_type : {"device", "shared", "host"}, optional
The type of SYCL USM allocation for the output array.

Returns
-------
out : dpnp.ndarray
`size`-shaped array of random integers from the appropriate distribution,
or a single such random int if `size` not provided.
Output array data type is the same as input ``dtype``.
or a single such random int if `size` is not provided.
Output array data type is the same as input `dtype`.

Limitations
-----------
Parameters ``low`` and ``high`` are supported only as scalar.
Parameter ``dtype`` is supported only as :obj:`dpnp.int32` or `int`,
but `int` value is considered to be exactly equivalent to :obj:`dpnp.int32`.
Parameters `low` and `high` are supported only as a scalar.
Parameter `dtype` is supported only as :obj:`dpnp.int32` or ``int``,
but ``int`` value is considered to be exactly equivalent to :obj:`dpnp.int32`.
Otherwise, :obj:`numpy.random.randint(low, high, size, dtype)` samples are drawn.

Examples
Expand Down Expand Up @@ -359,16 +374,16 @@ def randn(self, *args, usm_type="device"):

Parameters
----------
usm_type : ("device" | "shared" | "host"), optional
usm_type : {"device", "shared", "host"}, optional
The type of SYCL USM allocation for the output array.

Returns
-------
Z : dpnp.ndarray
out : dpnp.ndarray
A ``(d0, d1, ..., dn)``-shaped array of floating-point samples from
the standard normal distribution, or a single such float if
no parameters were supplied.
Output array data type is :obj:`dpnp.float64` if device supports it
Output array data type is :obj:`dpnp.float64` if device supports it,
or :obj:`dpnp.float32` otherwise.

Examples
Expand Down Expand Up @@ -408,15 +423,15 @@ def random_sample(self, size=None, usm_type="device"):

Parameters
----------
usm_type : ("device" | "shared" | "host"), optional
usm_type : {"device", "shared", "host"}, optional
The type of SYCL USM allocation for the output array.

Returns
-------
out : dpnp.ndarray
Array of random floats of shape `size` (if ``size=None``,
zero dimension array with a single float is returned).
Output array data type is :obj:`dpnp.float64` if device supports it
Output array data type is :obj:`dpnp.float64` if device supports it,
or :obj:`dpnp.float32` otherwise.

Examples
Expand Down Expand Up @@ -447,20 +462,19 @@ def standard_normal(self, size=None, usm_type="device"):

Parameters
----------
usm_type : ("device" | "shared" | "host"), optional
usm_type : {"device", "shared", "host"}, optional
The type of SYCL USM allocation for the output array.

Returns
-------
out : dpnp.ndarray
A floating-point array of shape ``size`` of drawn samples, or a
single sample if ``size`` was not specified.
Output array data type is :obj:`dpnp.float64` if device supports it
A floating-point array of shape `size` of drawn samples, or a
single sample if `size` was not specified.
Output array data type is :obj:`dpnp.float64` if device supports it,
or :obj:`dpnp.float32` otherwise.

Examples
--------
Draw samples from the distribution:
>>> s = dpnp.random.RandomState().standard_normal(size=(3, 5))
>>> print(s)
[[-0.84401099 -1.81715362 -0.54465213 0.18557831 0.28352814]
Expand Down Expand Up @@ -492,25 +506,24 @@ def uniform(self, low=0.0, high=1.0, size=None, dtype=None, usm_type="device"):

Parameters
----------
usm_type : ("device" | "shared" | "host"), optional
usm_type : {"device", "shared", "host"}, optional
The type of SYCL USM allocation for the output array.

Returns
-------
out : dpnp.ndarray
Drawn samples from the parameterized uniform distribution.
Output array data type is the same as input ``dtype``. If ``dtype`` is None (default),
:obj:`dpnp.float64` type will be used if device supports it or :obj:`dpnp.float32` otherwise.
Output array data type is the same as input `dtype`. If `dtype` is ``None`` (the default),
:obj:`dpnp.float64` type will be used if device supports it, or :obj:`dpnp.float32` otherwise.

Limitations
-----------
Parameters ``low`` and ``high`` are supported as scalar. Otherwise,
Parameters `low` and `high` are supported as scalar. Otherwise,
:obj:`numpy.random.uniform(low, high, size)` samples are drawn.
Parameter ``dtype`` is supported only for :obj:`dpnp.int32`, :obj:`dpnp.float32`, :obj:`dpnp.float64` or `None`.
Parameter `dtype` is supported only as :obj:`dpnp.int32`, :obj:`dpnp.float32`, :obj:`dpnp.float64` or ``None``.

Examples
--------
Draw samples from the distribution:
>>> low, high = 1.23, 10.54 # low and high
>>> s = dpnp.random.RandomState().uniform(low, high, 5)
>>> print(s)
Expand Down