Skip to content

Small improvements to docs API #817

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.

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 4 commits into from
Oct 7, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
16 changes: 16 additions & 0 deletions .github/workflows/rtd-link-preview.yml
Original file line number Diff line number Diff line change
@@ -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"
7 changes: 0 additions & 7 deletions doc/library/graph/graph.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
10 changes: 5 additions & 5 deletions doc/library/graph/index.rst
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@

.. _libdoc_graph:

================================================
:mod:`graph` -- Theano Internals [doc TODO]
================================================
========================================
:mod:`graph` -- PyTensor Graph Internals
========================================

.. module:: graph
:platform: Unix, Windows
:synopsis: Theano Internals

.. moduleauthor:: LISA

.. toctree::
:maxdepth: 1

graph
fgraph
replace
features
op
type
Expand Down
12 changes: 4 additions & 8 deletions doc/library/graph/op.rst
Original file line number Diff line number Diff line change
@@ -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:
8 changes: 8 additions & 0 deletions doc/library/graph/replace.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
.. _libdoc_graph_replace:

==================================================
:mod:`replace` -- High level graph transformations
==================================================

.. automodule:: pytensor.graph.replace
:members:
2 changes: 2 additions & 0 deletions doc/library/tensor/functional.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
.. automodule:: pytensor.tensor.functional
:members: vectorize
20 changes: 11 additions & 9 deletions doc/library/tensor/index.rst
Original file line number Diff line number Diff line change
@@ -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::
Expand All @@ -29,3 +30,4 @@ They are grouped into the following sections:
conv
math_opt
basic_opt
functional
161 changes: 0 additions & 161 deletions doc/library/tensor/random/basic.rst

This file was deleted.

8 changes: 8 additions & 0 deletions doc/library/tensor/random/distributions.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
.. _libdoc_tensor_random_distributions:

Distributions
=============

.. automodule:: pytensor.tensor.random.basic
:members:
:special-members: __call__
88 changes: 78 additions & 10 deletions doc/library/tensor/random/index.rst
Original file line number Diff line number Diff line change
@@ -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 <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
Loading
Loading