From 5351abfe7fae36bc4f5ec09f6fac2e581f54870d Mon Sep 17 00:00:00 2001 From: Ricardo Vieira Date: Tue, 11 Jun 2024 16:53:18 +0200 Subject: [PATCH 1/4] Cleanup random API docs --- doc/library/tensor/random/basic.rst | 161 -------------------- doc/library/tensor/random/distributions.rst | 8 + doc/library/tensor/random/index.rst | 88 +++++++++-- doc/library/tensor/random/utils.rst | 64 -------- 4 files changed, 86 insertions(+), 235 deletions(-) delete mode 100644 doc/library/tensor/random/basic.rst create mode 100644 doc/library/tensor/random/distributions.rst delete mode 100644 doc/library/tensor/random/utils.rst diff --git a/doc/library/tensor/random/basic.rst b/doc/library/tensor/random/basic.rst deleted file mode 100644 index 2d47aabede..0000000000 --- a/doc/library/tensor/random/basic.rst +++ /dev/null @@ -1,161 +0,0 @@ - -.. _libdoc_tensor_random_basic: - -============================================= -:mod:`basic` -- Low-level random numbers -============================================= - -.. module:: pytensor.tensor.random - :synopsis: symbolic random variables - - -The :mod:`pytensor.tensor.random` module provides random-number drawing functionality -that closely resembles the :mod:`numpy.random` module. - -Reference -========= - -.. class:: RandomStream() - - A helper class that tracks changes in a shared :class:`numpy.random.RandomState` - and behaves like :class:`numpy.random.RandomState` by managing access - to :class:`RandomVariable`\s. For example: - - .. testcode:: constructors - - from pytensor.tensor.random.utils import RandomStream - - rng = RandomStream() - sample = rng.normal(0, 1, size=(2, 2)) - -.. class:: RandomStateType(Type) - - A :class:`Type` for variables that will take :class:`numpy.random.RandomState` - values. - -.. function:: random_state_type(name=None) - - Return a new :class:`Variable` whose :attr:`Variable.type` is an instance of - :class:`RandomStateType`. - -.. class:: RandomVariable(Op) - - :class:`Op` that draws random numbers from a :class:`numpy.random.RandomState` object. - This :class:`Op` is parameterized to draw numbers from many possible - distributions. - -Distributions -============== - -PyTensor can produce :class:`RandomVariable`\s that draw samples from many different statistical distributions, using the following :class:`Op`\s. The :class:`RandomVariable`\s behave similarly to NumPy's *Generalized Universal Functions* (or `gunfunc`): it supports "core" random variable :class:`Op`\s that map distinctly shaped inputs to potentially non-scalar outputs. We document this behavior in the following with `gufunc`-like signatures. - -.. autoclass:: pytensor.tensor.random.basic.UniformRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.RandIntRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.IntegersRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.ChoiceRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.PermutationRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.BernoulliRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.BetaRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.BetaBinomialRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.BinomialRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.CauchyRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.CategoricalRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.DirichletRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.ExponentialRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.GammaRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.GenGammaRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.GeometricRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.GumbelRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.HalfCauchyRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.HalfNormalRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.HyperGeometricRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.InvGammaRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.LaplaceRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.LogisticRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.LogNormalRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.MultinomialRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.MvNormalRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.NegBinomialRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.NormalRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.ParetoRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.PoissonRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.StandardNormalRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.StudentTRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.TriangularRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.TruncExponentialRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.VonMisesRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.WaldRV - :members: __call__ - -.. autoclass:: pytensor.tensor.random.basic.WeibullRV - :members: __call__ diff --git a/doc/library/tensor/random/distributions.rst b/doc/library/tensor/random/distributions.rst new file mode 100644 index 0000000000..bf3ae95ac0 --- /dev/null +++ b/doc/library/tensor/random/distributions.rst @@ -0,0 +1,8 @@ +.. _libdoc_tensor_random_distributions: + +Distributions +============= + +.. automodule:: pytensor.tensor.random.basic + :members: + :special-members: __call__ diff --git a/doc/library/tensor/random/index.rst b/doc/library/tensor/random/index.rst index 0e23510aee..210b77d5c1 100644 --- a/doc/library/tensor/random/index.rst +++ b/doc/library/tensor/random/index.rst @@ -1,21 +1,89 @@ -.. _libdoc_tensor_random: + +.. _libdoc_tensor_random_basic: ============================================= -:mod:`random` -- Low-level random numbers +:mod:`random` -- Random number functionality ============================================= -Low-level random numbers ------------------------- +.. module:: pytensor.tensor.random + :synopsis: symbolic random variables + The :mod:`pytensor.tensor.random` module provides random-number drawing functionality that closely resembles the :mod:`numpy.random` module. -.. toctree:: - :maxdepth: 2 - basic - utils +High-level API +============== + +PyTensor assigns NumPy RNG states (i.e. `Generator` objects) to +each `RandomVariable`. The combination of an RNG state, a specific +`RandomVariable` type (e.g. `NormalRV`), and a set of distribution parameters +uniquely defines the `RandomVariable` instances in a graph. + +This means that a "stream" of distinct RNG states is required in order to +produce distinct random variables of the same kind. `RandomStream` provides a +means of generating distinct random variables in a fully reproducible way. + +`RandomStream` is also designed to produce simpler graphs and work with more +sophisticated `Op`\s like `Scan`, which makes it a user-friendly random variable +interface in PyTensor. + +For an example of how to use random numbers, see :ref:`Using Random Numbers `. + + +.. class:: RandomStream() + + This is a symbolic stand-in for `numpy.random.Generator`. + + .. method:: updates() + + :returns: a list of all the (state, new_state) update pairs for the + random variables created by this object + + This can be a convenient shortcut to enumerating all the random + variables in a large graph in the ``update`` argument to + `pytensor.function`. + + .. method:: seed(meta_seed) + + `meta_seed` will be used to seed a temporary random number generator, + that will in turn generate seeds for all random variables + created by this object (via `gen`). + + :returns: None + + .. method:: gen(op, *args, **kwargs) + + Return the random variable from ``op(*args, **kwargs)``. + + This function also adds the returned variable to an internal list so + that it can be seeded later by a call to `seed`. + + .. method:: uniform, normal, binomial, multinomial, random_integers, ... + + See :ref: Available distributions `<_libdoc_tensor_random_distributions>`. + + + .. testcode:: constructors + + from pytensor.tensor.random.utils import RandomStream + + rng = RandomStream() + sample = rng.normal(0, 1, size=(2, 2)) + + fn = pytensor.function([], sample) + print(fn(), fn()) # different numbers due to default updates + + +Low-level objects +================= + +.. automodule:: pytensor.tensor.random.op + :members: RandomVariable, default_rng +..automodule:: pytensor.tensor.random.type + :members: RandomType, RandomGeneratorType, random_generator_type -.. automodule:: pytensor.tensor.random.basic - :members: +.. automodule:: pytensor.tensor.random.var + :members: RandomGeneratorSharedVariable diff --git a/doc/library/tensor/random/utils.rst b/doc/library/tensor/random/utils.rst deleted file mode 100644 index 09a8670025..0000000000 --- a/doc/library/tensor/random/utils.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _libdoc_tensor_random_utils: - -====================================================== -:mod:`utils` -- Friendly random numbers -====================================================== - -.. module:: pytensor.tensor.random.utils - :platform: Unix, Windows - :synopsis: symbolic random variables -.. moduleauthor:: LISA - -Guide -===== - -PyTensor assigns NumPy RNG states (e.g. `Generator` or `RandomState` objects) to -each `RandomVariable`. The combination of an RNG state, a specific -`RandomVariable` type (e.g. `NormalRV`), and a set of distribution parameters -uniquely defines the `RandomVariable` instances in a graph. - -This means that a "stream" of distinct RNG states is required in order to -produce distinct random variables of the same kind. `RandomStream` provides a -means of generating distinct random variables in a fully reproducible way. - -`RandomStream` is also designed to produce simpler graphs and work with more -sophisticated `Op`\s like `Scan`, which makes it the de facto random variable -interface in PyTensor. - -For an example of how to use random numbers, see :ref:`Using Random Numbers `. - - -Reference -========= - -.. class:: RandomStream() - - This is a symbolic stand-in for `numpy.random.Generator`. - - .. method:: updates() - - :returns: a list of all the (state, new_state) update pairs for the - random variables created by this object - - This can be a convenient shortcut to enumerating all the random - variables in a large graph in the ``update`` argument to - `pytensor.function`. - - .. method:: seed(meta_seed) - - `meta_seed` will be used to seed a temporary random number generator, - that will in turn generate seeds for all random variables - created by this object (via `gen`). - - :returns: None - - .. method:: gen(op, *args, **kwargs) - - Return the random variable from ``op(*args, **kwargs)``. - - This function also adds the returned variable to an internal list so - that it can be seeded later by a call to `seed`. - - .. method:: uniform, normal, binomial, multinomial, random_integers, ... - - See :class:`basic.RandomVariable`. From 468f14bab3e3654426858b7f8101b0c05f041388 Mon Sep 17 00:00:00 2001 From: Ricardo Vieira Date: Tue, 11 Jun 2024 17:00:02 +0200 Subject: [PATCH 2/4] Add tensor vectorize to docs --- doc/library/tensor/functional.rst | 2 ++ doc/library/tensor/index.rst | 20 +++++++++++--------- 2 files changed, 13 insertions(+), 9 deletions(-) create mode 100644 doc/library/tensor/functional.rst diff --git a/doc/library/tensor/functional.rst b/doc/library/tensor/functional.rst new file mode 100644 index 0000000000..904ebc2ac6 --- /dev/null +++ b/doc/library/tensor/functional.rst @@ -0,0 +1,2 @@ +.. automodule:: pytensor.tensor.functional + :members: vectorize \ No newline at end of file diff --git a/doc/library/tensor/index.rst b/doc/library/tensor/index.rst index dbd7c1c600..519d49293c 100644 --- a/doc/library/tensor/index.rst +++ b/doc/library/tensor/index.rst @@ -1,17 +1,18 @@ .. _libdoc_tensor: -================================================== -:mod:`tensor` -- Types and Ops for Symbolic numpy -================================================== +=============================================== +:mod:`tensor` -- Tensor operations in PyTensor +=============================================== .. module:: tensor - :platform: Unix, Windows - :synopsis: symbolic types and operations for n-dimensional arrays. -.. moduleauthor:: LISA -Theano's strength is in expressing symbolic calculations involving tensors. -There are many types of symbolic expressions for tensors. -They are grouped into the following sections: +PyTensor's strength is in expressing symbolic calculations involving tensors. + +PyTensor tries to emulate the numpy interface as much as possible in the tensor module. +This means that once TensorVariables are created, it should be possibly to define +symbolic expressions using calls that look just like numpy calls, such as +`pt.exp(x).transpose(0, 1)[:, None]` + .. toctree:: @@ -29,3 +30,4 @@ They are grouped into the following sections: conv math_opt basic_opt + functional From abe0563bc3231e05da0aa573c8c141a95a8c6c95 Mon Sep 17 00:00:00 2001 From: Ricardo Vieira Date: Tue, 11 Jun 2024 17:07:04 +0200 Subject: [PATCH 3/4] Cleanup graph API docs --- doc/library/graph/graph.rst | 7 ------- doc/library/graph/index.rst | 10 +++++----- doc/library/graph/op.rst | 12 ++++-------- doc/library/graph/replace.rst | 8 ++++++++ 4 files changed, 17 insertions(+), 20 deletions(-) create mode 100644 doc/library/graph/replace.rst diff --git a/doc/library/graph/graph.rst b/doc/library/graph/graph.rst index a1172af733..23150d33d0 100644 --- a/doc/library/graph/graph.rst +++ b/doc/library/graph/graph.rst @@ -4,12 +4,5 @@ :mod:`graph` -- Interface for the PyTensor graph ================================================ ---------- -Reference ---------- - .. automodule:: pytensor.graph.basic - :platform: Unix, Windows - :synopsis: Interface for types of symbolic variables :members: -.. moduleauthor:: LISA diff --git a/doc/library/graph/index.rst b/doc/library/graph/index.rst index 1328d193fd..fa82c14737 100644 --- a/doc/library/graph/index.rst +++ b/doc/library/graph/index.rst @@ -1,13 +1,12 @@ .. _libdoc_graph: -================================================ -:mod:`graph` -- Theano Internals [doc TODO] -================================================ +======================================== +:mod:`graph` -- PyTensor Graph Internals +======================================== .. module:: graph - :platform: Unix, Windows - :synopsis: Theano Internals + .. moduleauthor:: LISA .. toctree:: @@ -15,6 +14,7 @@ graph fgraph + replace features op type diff --git a/doc/library/graph/op.rst b/doc/library/graph/op.rst index 0a7b5f7139..43394898c8 100644 --- a/doc/library/graph/op.rst +++ b/doc/library/graph/op.rst @@ -1,12 +1,8 @@ - .. _libdoc_graph_op: -============================================================== -:mod:`graph` -- Objects and functions for computational graphs -============================================================== +=========================================== +:mod:`op` -- Objects that define operations +=========================================== .. automodule:: pytensor.graph.op - :platform: Unix, Windows - :synopsis: Interface for types of symbolic variables - :members: -.. moduleauthor:: LISA + :members: \ No newline at end of file diff --git a/doc/library/graph/replace.rst b/doc/library/graph/replace.rst new file mode 100644 index 0000000000..36c714dbf0 --- /dev/null +++ b/doc/library/graph/replace.rst @@ -0,0 +1,8 @@ +.. _libdoc_graph_replace: + +================================================== +:mod:`replace` -- High level graph transformations +================================================== + +.. automodule:: pytensor.graph.replace + :members: From c24d281c75c99f0322ddd43e86abf2e24010de3c Mon Sep 17 00:00:00 2001 From: Ricardo Vieira Date: Tue, 11 Jun 2024 18:38:38 +0200 Subject: [PATCH 4/4] Add RTD link preview --- .github/workflows/rtd-link-preview.yml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .github/workflows/rtd-link-preview.yml diff --git a/.github/workflows/rtd-link-preview.yml b/.github/workflows/rtd-link-preview.yml new file mode 100644 index 0000000000..23a967e123 --- /dev/null +++ b/.github/workflows/rtd-link-preview.yml @@ -0,0 +1,16 @@ +name: Read the Docs Pull Request Preview +on: + pull_request_target: + types: + - opened + +permissions: + pull-requests: write + +jobs: + documentation-links: + runs-on: ubuntu-latest + steps: + - uses: readthedocs/actions/preview@v1 + with: + project-slug: "pytensor"