Skip to content

Commit 493fbba

Browse files
alexgdebeeralexgdebeer
committed
Rebuild docs
1 parent 61399bd commit 493fbba

File tree

10 files changed

+255
-28
lines changed

10 files changed

+255
-28
lines changed

‎deep_tensor/debiasing/importance_sampling.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,15 @@
1010
class ImportanceSamplingResult(object):
1111
r"""An object containing the results of importance sampling.
1212
13-
Parameters
13+
Attributes
1414
----------
15-
log_weights:
15+
log_weights: Tensor
1616
An $n$-dimensional vector containing the unnormalised
1717
importance weights associated with a set of samples.
18-
log_norm:
18+
log_norm: Tensor
1919
An estimate of the logarithm of the normalising constant
2020
associated with the target density.
21-
ess:
21+
ess: Tensor
2222
An estimate of the effective sample size of the samples.
2323
2424
"""

‎deep_tensor/debiasing/mcmc.py‎

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -64,13 +64,20 @@ def print_progress(self) -> None:
6464
class MCMCResult(object):
6565
r"""An object containing a constructed Markov chain.
6666
67-
Parameters
67+
Attributes
6868
----------
69-
xs:
70-
An $n \times d$ matrix containing the samples that form the
69+
xs: Tensor
70+
An $n \times k$ matrix containing the samples that form the
7171
Markov chain.
72-
acceptance_rate:
72+
potentials: Tensor
73+
An $n$-dimensional vector containing the potential function
74+
associated with the target density evaluated at each sample in
75+
the chain.
76+
acceptance_rate: float
7377
The acceptance rate of the sampler.
78+
iacts: Tensor
79+
A $k$-dimensional vector containing estimates of the integrated
80+
autocorrelation time (IACT) for each parameter.
7481
7582
"""
7683
def __init__(self, chain: MarkovChain):
@@ -153,13 +160,13 @@ def run_irt_pcn(
153160
subset: str = "first",
154161
verbose: bool = True
155162
) -> MCMCResult:
156-
r"""Runs a preconditioned Crank-Nicholson (pCN) sampler.
163+
r"""Runs a pCN sampler using the DIRT mapping.
157164
158-
Runs a pCN sampler (Cotter *et al.*, 2013) to characterise the
159-
pullback of the target density under the DIRT mapping, then pushes
160-
the resulting samples forward under the DIRT mapping to obtain
161-
samples distributed according to the target. This idea was
162-
initially outlined by Cui *et al.* (2023).
165+
Runs a preconditioned Crank-Nicholson sampler (Cotter *et al.*,
166+
2013) to characterise the pullback of the target density under the
167+
DIRT mapping, then pushes the resulting samples forward under the
168+
DIRT mapping to obtain samples distributed according to the target.
169+
This idea was initially outlined by Cui *et al.* (2023).
163170
164171
Note that the pCN proposal is only applicable to problems with a
165172
Gaussian reference density.
@@ -265,7 +272,7 @@ def run_cirt_pcn(
265272
subset: str = "first",
266273
verbose: bool = True
267274
) -> MCMCResult:
268-
r"""Runs a preconditioned Crank-Nicholson (pCN) sampler using a conditional of the DIRT mapping.
275+
r"""Runs a pCN sampler using a conditional of the DIRT mapping.
269276
270277
Runs a pCN sampler to characterise the pullback of the target
271278
density under a conditional of the DIRT mapping, then pushes the
@@ -296,7 +303,7 @@ def run_cirt_pcn(
296303
containing a sample from the reference domain. If not passed in,
297304
the mean of the reference density will be used.
298305
subset:
299-
Whether 'y' is a realisation of the first $k$ variables
306+
Whether `y` is a realisation of the first $k$ variables
300307
(`subset='first'`) or the final $k$ variables (`subset='last'`).
301308
verbose:
302309
Whether to print diagnostic information during the sampling

‎docs/_sidebar.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,8 @@ website:
3636
- contents:
3737
- reference/run_importance_sampling.qmd
3838
- reference/run_independence_sampler.qmd
39-
- reference/run_dirt_pcn.qmd
39+
- reference/run_irt_pcn.qmd
40+
- reference/run_cirt_pcn.qmd
4041
- reference/ImportanceSamplingResult.qmd
4142
- reference/MCMCResult.qmd
4243
section: Debiasing

‎docs/objects.json‎

Lines changed: 1 addition & 1 deletion
Large diffs are not rendered by default.

‎docs/reference/DIRT.qmd‎

Lines changed: 59 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ Foundations of Computational Mathematics **22**, 1863--1922.
6161
| [eval_irt](#deep_tensor.DIRT.eval_irt) | Evaluates the deep inverse Rosenblatt transport. |
6262
| [eval_cirt](#deep_tensor.DIRT.eval_cirt) | Evaluates the conditional inverse Rosenblatt transport. |
6363
| [eval_irt_pullback](#deep_tensor.DIRT.eval_irt_pullback) | Evaluates the pullback of a density function under the DIRT mapping. |
64+
| [eval_cirt_pullback](#deep_tensor.DIRT.eval_cirt_pullback) | Evaluates the pullback of a conditional density function under the DIRT mapping. |
6465
| [random](#deep_tensor.DIRT.random) | Generates a set of random samples. |
6566
| [sobol](#deep_tensor.DIRT.sobol) | Generates a set of QMC samples. |
6667

@@ -267,8 +268,8 @@ DIRT.eval_irt_pullback(
267268
Evaluates the pullback of a density function under the DIRT mapping.
268269

269270
This function evaluates $\mathcal{T}^{\sharp}f(r)$, where
270-
$\mathcal{T}(\cdot)$ denotes the inverse Rosenblatt transport and
271-
$f(\cdot)$ denotes an arbitrary density function.
271+
$\mathcal{T}(\cdot)$ denotes the inverse Rosenblatt transport
272+
and $f(\cdot)$ denotes an arbitrary density function.
272273

273274
#### Parameters {.doc-section .doc-section-parameters}
274275

@@ -292,7 +293,62 @@ $f(\cdot)$ denotes an arbitrary density function.
292293

293294
<code>[**neglogTfrs**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`)]{.parameter-annotation}</code>
294295

295-
: An $n$-dimensional vector containing the potential of the pullback function evaluated at each element in `rs`.
296+
: An $n$-dimensional vector containing the potential of the pullback function evaluated at each element in `rs`; that is, $-\log(\mathcal{T}^{\sharp}f(r))$.
297+
298+
<code>[**neglogfxs**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`)]{.parameter-annotation}</code>
299+
300+
: An $n$-dimensional vector containing the potential of the target function evaluated at each element in `rs`, pushed forward under the IRT; that is, $-\log(f(\mathcal{T}(r)))$.
301+
302+
### eval_cirt_pullback { #deep_tensor.DIRT.eval_cirt_pullback }
303+
304+
```python
305+
DIRT.eval_cirt_pullback(
306+
potential: Callable[[Tensor], Tensor],
307+
ys: Tensor,
308+
rs: Tensor,
309+
subset: str = 'first',
310+
n_layers: int | None = None,
311+
)
312+
```
313+
314+
Evaluates the pullback of a conditional density function under the DIRT mapping.
315+
316+
This function evaluates $\mathcal{T}^{\sharp}f(r|y)$, where
317+
$\mathcal{T}(\cdot)$ denotes the inverse Rosenblatt transport
318+
and $f(\cdot|y)$ denotes an arbitrary conditional density
319+
function.
320+
321+
#### Parameters {.doc-section .doc-section-parameters}
322+
323+
<code>[**potential**]{.parameter-name} [:]{.parameter-annotation-sep} [[Callable](`typing.Callable`)\[\[[Tensor](`torch.Tensor`)\], [Tensor](`torch.Tensor`)\]]{.parameter-annotation}</code>
324+
325+
: A function that takes an $n \times (d-k)$ matrix of samples from the approximation domain, and returns an $n$-dimensional vector containing the potential function associated with $f(\cdot\|y)$ evaluated at each sample.
326+
327+
<code>[**ys**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`)]{.parameter-annotation}</code>
328+
329+
: A matrix containing samples from the approximation domain. The matrix should have dimensions $1 \times k$ (if the same realisation of $Y$ is to be used for all samples in `rs`) or $n \times k$ (if a different realisation of $Y$ is to be used for each samples in `rs`).
330+
331+
<code>[**rs**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`)]{.parameter-annotation}</code>
332+
333+
: An $n \times (d-k)$ matrix containing a set of samples from the reference domain.
334+
335+
<code>[**subset**]{.parameter-name} [:]{.parameter-annotation-sep} [[str](`str`)]{.parameter-annotation} [ = ]{.parameter-default-sep} [\'first\']{.parameter-default}</code>
336+
337+
: Whether `ys` corresponds to the first $k$ variables (`subset='first'`) of the approximation, or the last $k$ variables (`subset='last'`).
338+
339+
<code>[**n_layers**]{.parameter-name} [:]{.parameter-annotation-sep} [[int](`int`) \| None]{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
340+
341+
: The number of layers of the deep inverse Rosenblatt transport to pull the samples back under. If not specified, the samples will be pulled back through all the layers.
342+
343+
#### Returns {.doc-section .doc-section-returns}
344+
345+
<code>[**neglogTfrs**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`)]{.parameter-annotation}</code>
346+
347+
: An $n$-dimensional vector containing the potential of the pullback function evaluated at each element in `rs`; that is, $-\log(\mathcal{T}^{\sharp}f(r\|y))$.
348+
349+
<code>[**neglogfxs**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`)]{.parameter-annotation}</code>
350+
351+
: An $n$-dimensional vector containing the potential of the target function evaluated at each element in `rs`, pushed forward under the IRT; that is, $-\log(f(\mathcal{T}(r)\|y))$.
296352

297353
### random { #deep_tensor.DIRT.random }
298354

‎docs/reference/ImportanceSamplingResult.qmd‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ ImportanceSamplingResult(log_weights: Tensor, log_norm: Tensor, ess: Tensor)
66

77
An object containing the results of importance sampling.
88

9-
## Parameters {.doc-section .doc-section-parameters}
9+
## Attributes {.doc-section .doc-section-attributes}
1010

1111
<code>[**log_weights**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`)]{.parameter-annotation}</code>
1212

‎docs/reference/MCMCResult.qmd‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,25 @@
11
# MCMCResult { #deep_tensor.MCMCResult }
22

33
```python
4-
MCMCResult(xs: Tensor, acceptance_rate: Tensor)
4+
MCMCResult(chain: MarkovChain)
55
```
66

77
An object containing a constructed Markov chain.
88

9-
## Parameters {.doc-section .doc-section-parameters}
9+
## Attributes {.doc-section .doc-section-attributes}
1010

1111
<code>[**xs**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`)]{.parameter-annotation}</code>
1212

13-
: An $n \times d$ matrix containing the samples that form the Markov chain.
13+
: An $n \times k$ matrix containing the samples that form the Markov chain.
1414

15-
<code>[**acceptance_rate**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`)]{.parameter-annotation}</code>
15+
<code>[**potentials**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`)]{.parameter-annotation}</code>
1616

17-
: The acceptance rate of the sampler.
17+
: An $n$-dimensional vector containing the potential function associated with the target density evaluated at each sample in the chain.
18+
19+
<code>[**acceptance_rate**]{.parameter-name} [:]{.parameter-annotation-sep} [[float](`float`)]{.parameter-annotation}</code>
20+
21+
: The acceptance rate of the sampler.
22+
23+
<code>[**iacts**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`)]{.parameter-annotation}</code>
24+
25+
: A $k$-dimensional vector containing estimates of the integrated autocorrelation time (IACT) for each parameter.

‎docs/reference/index.qmd‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ Functions used to remove the bias associated with the use of an approximation to
7474
| --- | --- |
7575
| [run_importance_sampling](run_importance_sampling.qmd#deep_tensor.run_importance_sampling) | Computes the importance weights associated with a set of samples. |
7676
| [run_independence_sampler](run_independence_sampler.qmd#deep_tensor.run_independence_sampler) | Runs an independence MCMC sampler. |
77-
| [run_dirt_pcn](run_dirt_pcn.qmd#deep_tensor.run_dirt_pcn) | Runs a preconditioned Crank-Nicholson (pCN) sampler. |
77+
| [run_irt_pcn](run_irt_pcn.qmd#deep_tensor.run_irt_pcn) | Runs a pCN sampler using the DIRT mapping. |
78+
| [run_cirt_pcn](run_cirt_pcn.qmd#deep_tensor.run_cirt_pcn) | Runs a pCN sampler using a conditional of the DIRT mapping. |
7879
| [ImportanceSamplingResult](ImportanceSamplingResult.qmd#deep_tensor.ImportanceSamplingResult) | An object containing the results of importance sampling. |
7980
| [MCMCResult](MCMCResult.qmd#deep_tensor.MCMCResult) | An object containing a constructed Markov chain. |

‎docs/reference/run_cirt_pcn.qmd‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# run_cirt_pcn { #deep_tensor.run_cirt_pcn }
2+
3+
```python
4+
run_cirt_pcn(
5+
potential: Callable[[Tensor], Tensor],
6+
dirt: AbstractDIRT,
7+
y: Tensor,
8+
n: int,
9+
dt: float = 2.0,
10+
r0: Tensor | None = None,
11+
subset: str = 'first',
12+
verbose: bool = True,
13+
)
14+
```
15+
16+
Runs a pCN sampler using a conditional of the DIRT mapping.
17+
18+
Runs a pCN sampler to characterise the pullback of the target
19+
density under a conditional of the DIRT mapping, then pushes the
20+
resulting samples forward under the DIRT mapping to obtain samples
21+
distributed according to the target. This idea was initially
22+
outlined by Cui *et al.* (2023).
23+
24+
Note that the pCN proposal is only applicable to problems with a
25+
Gaussian reference density.
26+
27+
## Parameters {.doc-section .doc-section-parameters}
28+
29+
<code>[**potential**]{.parameter-name} [:]{.parameter-annotation-sep} [[Callable](`typing.Callable`)\[\[[Tensor](`torch.Tensor`)\], [Tensor](`torch.Tensor`)\]]{.parameter-annotation}</code>
30+
31+
: A function that returns the negative logarithm of the (possibly unnormalised) target density at a given sample.
32+
33+
<code>[**dirt**]{.parameter-name} [:]{.parameter-annotation-sep} [[AbstractDIRT](`deep_tensor.irt.AbstractDIRT`)]{.parameter-annotation}</code>
34+
35+
: A previously-constructed DIRT object.
36+
37+
<code>[**y**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`)]{.parameter-annotation}</code>
38+
39+
: A $1 \times k$ matrix containing a sample from the approximation domain to condition on.
40+
41+
<code>[**n**]{.parameter-name} [:]{.parameter-annotation-sep} [[int](`int`)]{.parameter-annotation}</code>
42+
43+
: The length of the Markov chain to construct.
44+
45+
<code>[**dt**]{.parameter-name} [:]{.parameter-annotation-sep} [[float](`float`)]{.parameter-annotation} [ = ]{.parameter-default-sep} [2.0]{.parameter-default}</code>
46+
47+
: pCN stepsize, $\Delta t$. If this is not specified, a value of $\Delta t = 2$ (independence sampler) will be used.
48+
49+
<code>[**r0**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`) \| None]{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
50+
51+
: The starting state. This should be a $1 \times (d-k)$ matrix containing a sample from the reference domain. If not passed in, the mean of the reference density will be used.
52+
53+
<code>[**subset**]{.parameter-name} [:]{.parameter-annotation-sep} [[str](`str`)]{.parameter-annotation} [ = ]{.parameter-default-sep} [\'first\']{.parameter-default}</code>
54+
55+
: Whether `y` is a realisation of the first $k$ variables (`subset='first'`) or the final $k$ variables (`subset='last'`).
56+
57+
<code>[**verbose**]{.parameter-name} [:]{.parameter-annotation-sep} [[bool](`bool`)]{.parameter-annotation} [ = ]{.parameter-default-sep} [True]{.parameter-default}</code>
58+
59+
: Whether to print diagnostic information during the sampling process.
60+
61+
## Returns {.doc-section .doc-section-returns}
62+
63+
<code>[**res**]{.parameter-name} [:]{.parameter-annotation-sep} [[MCMCResult](`deep_tensor.debiasing.mcmc.MCMCResult`)]{.parameter-annotation}</code>
64+
65+
: An object containing the constructed Markov chain and some diagnostic information.

‎docs/reference/run_irt_pcn.qmd‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# run_irt_pcn { #deep_tensor.run_irt_pcn }
2+
3+
```python
4+
run_irt_pcn(
5+
potential: Callable[[Tensor], Tensor],
6+
dirt: AbstractDIRT,
7+
n: int,
8+
dt: float = 2.0,
9+
r0: Tensor | None = None,
10+
subset: str = 'first',
11+
verbose: bool = True,
12+
)
13+
```
14+
15+
Runs a pCN sampler using the DIRT mapping.
16+
17+
Runs a preconditioned Crank-Nicholson sampler (Cotter *et al.*,
18+
2013) to characterise the pullback of the target density under the
19+
DIRT mapping, then pushes the resulting samples forward under the
20+
DIRT mapping to obtain samples distributed according to the target.
21+
This idea was initially outlined by Cui *et al.* (2023).
22+
23+
Note that the pCN proposal is only applicable to problems with a
24+
Gaussian reference density.
25+
26+
## Parameters {.doc-section .doc-section-parameters}
27+
28+
<code>[**potential**]{.parameter-name} [:]{.parameter-annotation-sep} [[Callable](`typing.Callable`)\[\[[Tensor](`torch.Tensor`)\], [Tensor](`torch.Tensor`)\]]{.parameter-annotation}</code>
29+
30+
: A function that returns the negative logarithm of the (possibly unnormalised) target density at a given sample.
31+
32+
<code>[**dirt**]{.parameter-name} [:]{.parameter-annotation-sep} [[AbstractDIRT](`deep_tensor.irt.AbstractDIRT`)]{.parameter-annotation}</code>
33+
34+
: A previously-constructed DIRT object.
35+
36+
<code>[**n**]{.parameter-name} [:]{.parameter-annotation-sep} [[int](`int`)]{.parameter-annotation}</code>
37+
38+
: The length of the Markov chain to construct.
39+
40+
<code>[**dt**]{.parameter-name} [:]{.parameter-annotation-sep} [[float](`float`)]{.parameter-annotation} [ = ]{.parameter-default-sep} [2.0]{.parameter-default}</code>
41+
42+
: pCN stepsize, $\Delta t$. If this is not specified, a value of $\Delta t = 2$ (independence sampler) will be used.
43+
44+
<code>[**r0**]{.parameter-name} [:]{.parameter-annotation-sep} [[Tensor](`torch.Tensor`) \| None]{.parameter-annotation} [ = ]{.parameter-default-sep} [None]{.parameter-default}</code>
45+
46+
: The starting state. This should be a $1 \times k$ matrix containing a sample from the reference domain. If not passed in, the mean of the reference density will be used.
47+
48+
<code>[**subset**]{.parameter-name} [:]{.parameter-annotation-sep} [[str](`str`)]{.parameter-annotation} [ = ]{.parameter-default-sep} [\'first\']{.parameter-default}</code>
49+
50+
: If the samples contain a subset of the variables, (*i.e.,* $k < d$), whether they correspond to the first $k$ variables (`subset='first'`) or the last $k$ variables (`subset='last'`).
51+
52+
<code>[**verbose**]{.parameter-name} [:]{.parameter-annotation-sep} [[bool](`bool`)]{.parameter-annotation} [ = ]{.parameter-default-sep} [True]{.parameter-default}</code>
53+
54+
: Whether to print diagnostic information during the sampling process.
55+
56+
## Returns {.doc-section .doc-section-returns}
57+
58+
<code>[**res**]{.parameter-name} [:]{.parameter-annotation-sep} [[MCMCResult](`deep_tensor.debiasing.mcmc.MCMCResult`)]{.parameter-annotation}</code>
59+
60+
: An object containing the constructed Markov chain and some diagnostic information.
61+
62+
## Notes {.doc-section .doc-section-notes}
63+
64+
When the reference density is the standard Gaussian density (that
65+
is, $\rho(\theta) = \mathcal{N}(0_{d}, I_{d})$), the pCN proposal
66+
(given current state $\theta^{(i)}$) takes the form
67+
$$
68+
\theta' = \frac{2-\Delta t}{2+\Delta t} \theta^{(i)}
69+
+ \frac{2\sqrt{2\Delta t}}{2 + \Delta t} \tilde{\theta},
70+
$$
71+
where $\tilde{\theta} \sim \rho(\,\cdot\,)$, and $\Delta t$ denotes
72+
the step size.
73+
74+
When $\Delta t = 2$, the resulting sampler is an independence
75+
sampler. When $\Delta t > 2$, the proposals are negatively
76+
correlated, and when $\Delta t < 2$, the proposals are positively
77+
correlated.
78+
79+
## References {.doc-section .doc-section-references}
80+
81+
Cotter, SL, Roberts, GO, Stuart, AM and White, D (2013). *[MCMC
82+
methods for functions: Modifying old algorithms to make them
83+
faster](https://doi.org/10.1214/13-STS421).* Statistical Science
84+
**28**, 424--446.
85+
86+
Cui, T, Dolgov, S and Zahm, O (2023). *[Scalable conditional deep
87+
inverse Rosenblatt transports using tensor trains and gradient-based
88+
dimension reduction](https://doi.org/10.1016/j.jcp.2023.112103).*
89+
Journal of Computational Physics **485**, 112103.

0 commit comments

Comments
 (0)