Skip to content
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

Documentation Refactoring #526

Merged
merged 20 commits into from
May 6, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
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
Prev Previous commit
Added more undocumented fucntions. Edited docstrings. Minor config ch…
…anges
  • Loading branch information
limarta committed May 1, 2024
commit 62a69be0053ff2e2bc446055f55d0310937850f8
5 changes: 2 additions & 3 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,9 @@ The docs are divided in roughly four sections:
- API = Modeling API + Inference API
- Explanations + Internals

# Build Docs Locally
To build the docs, run `julia --make.jl` or alternatively startup the Julia REPL and include `make.jl`.

# Add Tutorial Code
# Developing
To build the docs, run `julia --make.jl` or alternatively startup the Julia REPL and include `make.jl`. For debugging, consider setting `draft=true` in the `makedocs` function found in `make.jl`.
Currently you must write the tutorial directly in the docs rather than a source file (e.g. Quarto). See `getting_started` or `tutorials` for examples.

Code snippets must use the triple backtick with a label to run. The environment carries over so long as the labels match. Example:
Expand Down
3 changes: 2 additions & 1 deletion docs/make.jl
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ makedocs(
),
sitename = "Gen.jl",
pages = pages,
# draft = true,
checkdocs=:exports,
pagesonly=true,
)

deploydocs(
Expand Down
9 changes: 5 additions & 4 deletions docs/pages.jl
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ pages = [
"tutorials/basics/modeling_in_gen.md",
"tutorials/basics/gfi.md",
"tutorials/basics/combinators.md",
"tutorials/basics/vi.md"
"tutorials/basics/particle_filter.md",
"tutorials/basics/vi.md",
],
"Advanced" => [
"tutorials/trace_translators.md",
Expand All @@ -28,13 +29,12 @@ pages = [
"Modeling Library" => [
"Generative Functions" => "api/model/gfi.md",
"Probability Distributions" => "api/model/distributions.md",
"Choice Maps" => "api/model/choice_maps.md",
"Built-in Modeling Languages" => "api/model/modeling.md",
"Combinators" => "api/model/combinators.md",
"Choice Maps" => "api/model/choice_maps.md",
"Selections" => "api/model/selections.md",
"Optimizing Trainable Parameters" => "api/model/parameter_optimization.md",
"Trace Translators" => "api/model/trace_translators.md",
"Differential Programming" => "api/model/differential_programming.md"
],
"Inference Library" => [
"Importance Sampling" => "api/inference/importance.md",
Expand All @@ -47,6 +47,7 @@ pages = [
],
],
"Explanation and Internals" => [
"Modeling Language Implementation" => "explanations/language_implementation.md"
"Modeling Language Implementation" => "explanations/language_implementation.md",
"explanations/combinator_design.md"
]
]
19 changes: 15 additions & 4 deletions docs/src/api/model/choice_maps.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,13 @@ Choice maps also implement:
- `==`, which tests if two choice maps have the same addresses and values at those addresses.


## Mutable Choice Maps

```@docs
DynamicChoiceMap
EmptyChoiceMap
StaticChoiceMap
choicemap
```

A mutable choice map can be constructed with [`choicemap`](@ref), and then populated:
```julia
Expand All @@ -45,13 +51,18 @@ There is also a constructor that takes initial (address, value) pairs:
choices = choicemap((:x, true), ("foo", 1.25), (:y => 1 => :z, -6.3))
```


```@docs
choicemap
set_value!
set_submap!
Base.merge(::ChoiceMap, ::ChoiceMap)
Base.merge(::ChoiceMap, ::Vararg{ChoiceMap})
Base.isempty(::ChoiceMap)
```

```@docs
DynamicChoiceMap
EmptyChoiceMap
Gen.pair
Gen.unpair
Gen.ChoiceMapNestedView
```

5 changes: 4 additions & 1 deletion docs/src/api/model/combinators.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,9 @@ FunctionalCollections.PersistentVector{Any}[true, false, true, false, true]

## Recurse combinator

TODO: document me
```@docs
Recurse
```

```@raw html
<div style="text-align:center">
Expand Down Expand Up @@ -161,3 +163,4 @@ The resulting trace contains the subtrace from the branch with index `2` - in th
└── :z : 13.552870875213735
```

1 change: 1 addition & 0 deletions docs/src/api/model/distributions.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ piecewise_uniform
poisson
uniform
uniform_discrete
broadcasted_normal
```

## [Defining New Distributions Inline with the `@dist` DSL](@id dist_dsl)
Expand Down
4 changes: 4 additions & 0 deletions docs/src/api/model/gfi.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,15 +22,19 @@ project
propose
assess
has_argument_grads
has_submap
accepts_output_grad
accumulate_param_gradients!
choice_gradients
get_params
```

```@docs
Diff
NoChange
UnknownChange
SetDiff
Diffed
```

```@docs
Expand Down
3 changes: 3 additions & 0 deletions docs/src/api/model/modeling.md
Original file line number Diff line number Diff line change
Expand Up @@ -274,8 +274,11 @@ The following methods are exported for the trainable parameters of `@gen` functi
init_param!
get_param
get_param_grad
set_param_grad!
set_param!
zero_param_grad!
accumulate_param_gradients_determ!
gradient_with_state
```

Trainable parameters are designed to be trained using gradient-based methods.
Expand Down
1 change: 1 addition & 0 deletions docs/src/api/model/parameter_optimization.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,4 @@ GradientDescent
ADAM
```
For adding new types of update configurations, see [Optimizing Trainable Parameters (Internal)](@ref optimizing-internal).

3 changes: 3 additions & 0 deletions docs/src/api/model/selections.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,3 +56,6 @@ DynamicSelection
StaticSelection
ComplementSelection
```
```@docs
Gen.get_address_schema
```
4 changes: 4 additions & 0 deletions docs/src/api/model/trace_translators.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,12 @@
pair_bijections!
is_involution!
inverse
TraceTranslator
DeterministicTraceTranslator
GeneralTraceTranslator
SimpleExtendingTraceTranslator
SymmetricTraceTranslator
```
```@docs
TraceTransformDSLProgram
```
9 changes: 9 additions & 0 deletions docs/src/explanations/combinator_design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Combinator Design and Implementation

Internally, the Combinators use custom trace types.
```@docs
Gen.VectorTrace
Gen.process_all_new!
Gen.update_recurse_merge
Gen.update_discard
```
31 changes: 31 additions & 0 deletions docs/src/explanations/language_implementation.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# [Modeling Language Implementation](@id language-implementation)
!!! warning
The API described here is internal to Gen's design and is subject to changes with no deprecation.

## Parsing `@gen` functions

Expand All @@ -15,3 +17,32 @@ For clarity, below is a procedural description of how the `@gen` macro processes
3. Pass the macro-expanded and de-sugared function body on to `make_static_gen_function` or `make_dynamic_gen_function` accordingly.
4. For static `@gen` functions, match `:gentrace` expressions when adding address nodes to the static computation graph, and match `:genparam` expressions when adding parameter nodes to the static computation graph. A `StaticIRGenerativeFunction` is then compiled from the static computation graph.
5. For dynamic `@gen` functions, rewrite any `:gentrace` expression with its implementation `dynamic_trace_impl`, and rewrite any `:genparam` expression with its implementation `dynamic_param_impl`. The rewritten syntax tree is then evaluated as a standard Julia function, which serves as the implementation of the constructed `DynamicDSLFunction`.

```@docs
Gen.make_dynamic_gen_function
Gen.dynamic_param_impl
Gen.rewrite_dynamic_gen_exprs
Gen.dynamic_trace_impl
Gen.arg_to_ast
Gen.escape_default
Gen.state
Gen.choice_or_call_at
```
## Static Modeling Language Tooling

```@docs
Gen.StaticIRGenerativeFunction
Gen.make_static_gen_function
Gen.gen_node_name
Gen.parse_static_dsl_line!
Gen.parse_typed_var
Gen.parse_julia_expr!
Gen.parse_param_line!
Gen.parse_trace_expr!
Gen.parse_and_rewrite_trace!
Gen.parse_assignment_line!
Gen.parse_return_line!
Gen.parse_static_dsl_function_body!
Gen.split_addr!
Gen.resolve_symbols
```
5 changes: 2 additions & 3 deletions docs/src/how_to/custom_derivatives.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,5 @@ Gen.has_argument_grads(::MyPlus) = (true, true)
# [Optimizing Trainable Parameters](@id optimizing-internal)

To add support for a new type of gradient-based parameter update, create a new type with the following methods defined for the types of generative functions that are to be supported.
- [Gen.init_update_state](@ref)
- [Gen.apply_update!](@ref)
```
- [`Gen.init_update_state`](@ref)
- [`Gen.apply_update!`](@ref)
Loading
Loading