From c6f99b65c1e2a1007effd0155d9ac449faccbe7c Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 11:56:41 +0000 Subject: [PATCH 01/15] Gen index.rst --- docs/genrst.jl | 72 +++++++++++++++++++++++++++++----- docs/source/Prior.rst | 11 ------ docs/source/PriorArray.rst | 19 --------- docs/source/PriorContainer.rst | 38 ------------------ docs/source/index.rst | 8 ++++ docs/source/replay.rst | 72 ++++++++++++++++++++++++++++++++++ 6 files changed, 143 insertions(+), 77 deletions(-) delete mode 100644 docs/source/Prior.rst delete mode 100644 docs/source/PriorArray.rst delete mode 100644 docs/source/PriorContainer.rst create mode 100644 docs/source/replay.rst diff --git a/docs/genrst.jl b/docs/genrst.jl index 814716429a..0065abb6b2 100644 --- a/docs/genrst.jl +++ b/docs/genrst.jl @@ -23,20 +23,74 @@ function printrst(io,md) end end -API_list = [Prior, PriorArray, PriorContainer, addPrior] +to_gen = Dict( + "replay" => [Prior, PriorArray, PriorContainer, addPrior] +) + cd(joinpath(dirname(@__FILE__),"source")) do - for API in API_list - fname = replace("$(string(API))", "Turing.", "") + for fname in keys(to_gen) open("$fname.rst","w") do f - md = Base.doc(API) - if isa(md,Markdown.MD) - isa(md.content[1].content[1],Markdown.Code) || error("Incorrect docstring format: $D") + for fun in to_gen[fname] + md = Base.doc(fun) + if isa(md,Markdown.MD) + isa(md.content[1].content[1],Markdown.Code) || error("Incorrect docstring format: $D") - printrst(f,md) - else - warn("$D is not documented.") + printrst(f,md) + else + warn("$D is not documented.") + end end end end end + +api_str = "" +for fname in keys(to_gen) + api_str *= "$fname\n" +end + +rst = """ +Welcome to Turing.jl's documentation! +===================================== + +Contents +^^^^^^^^ + +.. toctree:: + :maxdepth: 2 + :caption: Getting Started + + installation + usage + demos + +.. toctree:: + :maxdepth: 2 + :caption: Development Notes + + language + compiler + sampler + coroutines + tarray + workflow + +.. toctree:: + :maxdepth: 2 + :caption: APIs + + $api_str +.. toctree:: + :maxdepth: 2 + :caption: License + + license + +""" + +cd(joinpath(dirname(@__FILE__),"source")) do + open("index.rst","w") do f + println(f,rst) + end +end diff --git a/docs/source/Prior.rst b/docs/source/Prior.rst deleted file mode 100644 index 24da72c25b..0000000000 --- a/docs/source/Prior.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. function:: Prior(sym) - - A wrapper of symbol type representing priors. - - Usage: - - .. code-block:: julia - - p = Prior(:somesym) - strp = string(p) - diff --git a/docs/source/PriorArray.rst b/docs/source/PriorArray.rst deleted file mode 100644 index 92bcc15939..0000000000 --- a/docs/source/PriorArray.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. function:: PriorArray(array, count, currSetIdx, currGetIdx) - - Type for a rotated array (used for prior replay purpose). - - This type of array support set and get without specifying indices. Instead, an inner index pointer is used to iterate the array. The pointers for set and get are separate. - - Usage: - - .. code-block:: julia - - pa = PriorArray() # [] - add(pa, 1) # [1] - add(pa, 2) # [1, 2] - get(pa) # 1 - get(pa) # 2 - set(pa, 3) # [3, 2] - get(pa) # 3 - get(pa) # 2 - diff --git a/docs/source/PriorContainer.rst b/docs/source/PriorContainer.rst deleted file mode 100644 index b056a9498c..0000000000 --- a/docs/source/PriorContainer.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. function:: PriorContainer() - - A container to store priors based on dictionary. - - This type is basically a dictionary supporting adding new priors by creating a PriorArray and indexing using pc[] syntax - - Usage: - - .. code-block:: julia - - pc = PriorContainer() - p1 = Prior(:a) - p2 = Prior(:b) - - addPrior(pc, p1, 1) - addPrior(pc, p1, 2) - addPrior(pc, p1, 3) - addPrior(pc, p2, 4) - - pc[p1] # 1 - pc[p1] # 2 - pc[p1] # 3 - pc[p1] # 1 - pc[p1] # 2 - pc[p1] # 3 - - pc[p2] # 4 - - pc[p1] = 5 - pc[p1] = 6 - pc[p1] = 7 - - pc[p1] # 5 - pc[p1] # 6 - pc[p1] # 7 - - keys(pc) # create a key interator in the container, i.e. all the priors - diff --git a/docs/source/index.rst b/docs/source/index.rst index 7b391e641f..74c6979534 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,8 +23,16 @@ Contents tarray workflow +.. toctree:: + :maxdepth: 2 + :caption: APIs + + replay + .. toctree:: :maxdepth: 2 :caption: License license + + diff --git a/docs/source/replay.rst b/docs/source/replay.rst new file mode 100644 index 0000000000..6256054268 --- /dev/null +++ b/docs/source/replay.rst @@ -0,0 +1,72 @@ +.. function:: Prior(sym) + + A wrapper of symbol type representing priors. + + Usage: + + .. code-block:: julia + + p = Prior(:somesym) + strp = string(p) + +.. function:: PriorArray(array, count, currSetIdx, currGetIdx) + + Type for a rotated array (used for prior replay purpose). + + This type of array support set and get without specifying indices. Instead, an inner index pointer is used to iterate the array. The pointers for set and get are separate. + + Usage: + + .. code-block:: julia + + pa = PriorArray() # [] + add(pa, 1) # [1] + add(pa, 2) # [1, 2] + get(pa) # 1 + get(pa) # 2 + set(pa, 3) # [3, 2] + get(pa) # 3 + get(pa) # 2 + +.. function:: PriorContainer() + + A container to store priors based on dictionary. + + This type is basically a dictionary supporting adding new priors by creating a PriorArray and indexing using pc[] syntax + + Usage: + + .. code-block:: julia + + pc = PriorContainer() + p1 = Prior(:a) + p2 = Prior(:b) + + addPrior(pc, p1, 1) + addPrior(pc, p1, 2) + addPrior(pc, p1, 3) + addPrior(pc, p2, 4) + + pc[p1] # 1 + pc[p1] # 2 + pc[p1] # 3 + pc[p1] # 1 + pc[p1] # 2 + pc[p1] # 3 + + pc[p2] # 4 + + pc[p1] = 5 + pc[p1] = 6 + pc[p1] = 7 + + pc[p1] # 5 + pc[p1] # 6 + pc[p1] # 7 + + keys(pc) # create a key interator in the container, i.e. all the priors + +.. function:: addPrior(pc::PriorContainer, idx::Prior, val) + + Add a *new* value of a given prior to the container. *new* here means force appending to the end of the corresponding array of the prior. + From ce1c284d2a591db60709762e43ee63db497c0d44 Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 12:03:13 +0000 Subject: [PATCH 02/15] remove default theme --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 62f2d22f7b..ad93cc8e0d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -30,7 +30,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', 'juliadoc.julia', 'juliadoc.jlhelp' + 'juliadoc.julia', 'juliadoc.jlhelp' ] # Add any paths that contain templates here, relative to this directory. From 3bce2cb78f7e6824efb5c5d379009fccdb45af14 Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 12:16:25 +0000 Subject: [PATCH 03/15] Add title --- docs/genrst.jl | 8 ++++++-- docs/source/replay.rst | 3 +++ 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/genrst.jl b/docs/genrst.jl index 0065abb6b2..8ba2fef2b2 100644 --- a/docs/genrst.jl +++ b/docs/genrst.jl @@ -24,14 +24,18 @@ function printrst(io,md) end to_gen = Dict( - "replay" => [Prior, PriorArray, PriorContainer, addPrior] + "replay" => Dict( + :title => "Replay", + :list => [Prior, PriorArray, PriorContainer, addPrior] + ) ) cd(joinpath(dirname(@__FILE__),"source")) do for fname in keys(to_gen) open("$fname.rst","w") do f - for fun in to_gen[fname] + println(f,"$(to_gen[fname][:title])\n=========\n") + for fun in to_gen[fname][:list] md = Base.doc(fun) if isa(md,Markdown.MD) isa(md.content[1].content[1],Markdown.Code) || error("Incorrect docstring format: $D") diff --git a/docs/source/replay.rst b/docs/source/replay.rst index 6256054268..988ce495f6 100644 --- a/docs/source/replay.rst +++ b/docs/source/replay.rst @@ -1,3 +1,6 @@ +Replay +========= + .. function:: Prior(sym) A wrapper of symbol type representing priors. From e6d1758b0d40c323e624805f145105b6d33ecaaa Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 12:21:07 +0000 Subject: [PATCH 04/15] Update conf.py --- docs/source/conf.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index ad93cc8e0d..2a9191e95c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -49,8 +49,8 @@ # General information about the project. project = u'Turing.jl' -copyright = u'2016, Hong Ge, Adam Scibior, Matej Balog, Zoubin Ghahramani' -author = u'Hong Ge, Adam Scibior, Matej Balog, Zoubin Ghahramani' +copyright = u'2016, Hong Ge, Adam Scibior, Matej Balog, Zoubin Ghahramani, Kai Xu' +author = u'Hong Ge, Adam Scibior, Matej Balog, Zoubin Ghahramani, Kai Xu' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -111,8 +111,8 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -# html_theme = 'julia' -html_theme = 'alabaster' +html_theme = 'julia' +# html_theme = 'alabaster' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -229,7 +229,7 @@ # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'Turingjl.tex', u'Turing.jl Documentation', - u'Hong Ge, Adam Scibior, Matej Balog, Zoubin Ghahramani', 'manual'), + u'Hong Ge, Adam Scibior, Matej Balog, Zoubin Ghahramani, Kai Xu', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of From 6d8dabe0e67ee6e9a9e87692a23e3f72dfb9711d Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 12:24:07 +0000 Subject: [PATCH 05/15] Rename doc --- {docs => doc}/Makefile | 0 {docs => doc}/README.md | 0 {docs => doc}/genrst.jl | 0 {docs => doc}/make.bat | 0 {docs => doc}/requirements.txt | 0 {docs => doc}/source/addPrior.rst | 0 {docs => doc}/source/compiler.rst | 0 {docs => doc}/source/conf.py | 0 {docs => doc}/source/coroutines.rst | 0 {docs => doc}/source/demos.rst | 0 {docs => doc}/source/file_list.rst | 0 {docs => doc}/source/gettingstarted.rst | 0 {docs => doc}/source/index.rst | 0 {docs => doc}/source/installation.rst | 0 {docs => doc}/source/language.rst | 0 {docs => doc}/source/license.rst | 0 {docs => doc}/source/replay.rst | 0 {docs => doc}/source/sampler.rst | 0 {docs => doc}/source/tarray.rst | 0 {docs => doc}/source/usage.rst | 0 {docs => doc}/source/workflow.rst | 0 21 files changed, 0 insertions(+), 0 deletions(-) rename {docs => doc}/Makefile (100%) rename {docs => doc}/README.md (100%) rename {docs => doc}/genrst.jl (100%) rename {docs => doc}/make.bat (100%) rename {docs => doc}/requirements.txt (100%) rename {docs => doc}/source/addPrior.rst (100%) rename {docs => doc}/source/compiler.rst (100%) rename {docs => doc}/source/conf.py (100%) rename {docs => doc}/source/coroutines.rst (100%) rename {docs => doc}/source/demos.rst (100%) rename {docs => doc}/source/file_list.rst (100%) rename {docs => doc}/source/gettingstarted.rst (100%) rename {docs => doc}/source/index.rst (100%) rename {docs => doc}/source/installation.rst (100%) rename {docs => doc}/source/language.rst (100%) rename {docs => doc}/source/license.rst (100%) rename {docs => doc}/source/replay.rst (100%) rename {docs => doc}/source/sampler.rst (100%) rename {docs => doc}/source/tarray.rst (100%) rename {docs => doc}/source/usage.rst (100%) rename {docs => doc}/source/workflow.rst (100%) diff --git a/docs/Makefile b/doc/Makefile similarity index 100% rename from docs/Makefile rename to doc/Makefile diff --git a/docs/README.md b/doc/README.md similarity index 100% rename from docs/README.md rename to doc/README.md diff --git a/docs/genrst.jl b/doc/genrst.jl similarity index 100% rename from docs/genrst.jl rename to doc/genrst.jl diff --git a/docs/make.bat b/doc/make.bat similarity index 100% rename from docs/make.bat rename to doc/make.bat diff --git a/docs/requirements.txt b/doc/requirements.txt similarity index 100% rename from docs/requirements.txt rename to doc/requirements.txt diff --git a/docs/source/addPrior.rst b/doc/source/addPrior.rst similarity index 100% rename from docs/source/addPrior.rst rename to doc/source/addPrior.rst diff --git a/docs/source/compiler.rst b/doc/source/compiler.rst similarity index 100% rename from docs/source/compiler.rst rename to doc/source/compiler.rst diff --git a/docs/source/conf.py b/doc/source/conf.py similarity index 100% rename from docs/source/conf.py rename to doc/source/conf.py diff --git a/docs/source/coroutines.rst b/doc/source/coroutines.rst similarity index 100% rename from docs/source/coroutines.rst rename to doc/source/coroutines.rst diff --git a/docs/source/demos.rst b/doc/source/demos.rst similarity index 100% rename from docs/source/demos.rst rename to doc/source/demos.rst diff --git a/docs/source/file_list.rst b/doc/source/file_list.rst similarity index 100% rename from docs/source/file_list.rst rename to doc/source/file_list.rst diff --git a/docs/source/gettingstarted.rst b/doc/source/gettingstarted.rst similarity index 100% rename from docs/source/gettingstarted.rst rename to doc/source/gettingstarted.rst diff --git a/docs/source/index.rst b/doc/source/index.rst similarity index 100% rename from docs/source/index.rst rename to doc/source/index.rst diff --git a/docs/source/installation.rst b/doc/source/installation.rst similarity index 100% rename from docs/source/installation.rst rename to doc/source/installation.rst diff --git a/docs/source/language.rst b/doc/source/language.rst similarity index 100% rename from docs/source/language.rst rename to doc/source/language.rst diff --git a/docs/source/license.rst b/doc/source/license.rst similarity index 100% rename from docs/source/license.rst rename to doc/source/license.rst diff --git a/docs/source/replay.rst b/doc/source/replay.rst similarity index 100% rename from docs/source/replay.rst rename to doc/source/replay.rst diff --git a/docs/source/sampler.rst b/doc/source/sampler.rst similarity index 100% rename from docs/source/sampler.rst rename to doc/source/sampler.rst diff --git a/docs/source/tarray.rst b/doc/source/tarray.rst similarity index 100% rename from docs/source/tarray.rst rename to doc/source/tarray.rst diff --git a/docs/source/usage.rst b/doc/source/usage.rst similarity index 100% rename from docs/source/usage.rst rename to doc/source/usage.rst diff --git a/docs/source/workflow.rst b/doc/source/workflow.rst similarity index 100% rename from docs/source/workflow.rst rename to doc/source/workflow.rst From 9de80ec34d975612afe45ca6627e65e4f9872670 Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 12:53:39 +0000 Subject: [PATCH 06/15] Docs for compiler --- doc/genrst.jl | 22 +++-- doc/source/compilerapi.rst | 79 ++++++++++++++++++ doc/source/index.rst | 5 +- doc/source/{replay.rst => replayapi.rst} | 0 src/core/compiler.jl | 101 +++++++++++++++++++---- 5 files changed, 181 insertions(+), 26 deletions(-) create mode 100644 doc/source/compilerapi.rst rename doc/source/{replay.rst => replayapi.rst} (100%) diff --git a/doc/genrst.jl b/doc/genrst.jl index 8ba2fef2b2..ceb6903604 100644 --- a/doc/genrst.jl +++ b/doc/genrst.jl @@ -24,19 +24,22 @@ function printrst(io,md) end to_gen = Dict( - "replay" => Dict( + "replayapi" => Dict( :title => "Replay", - :list => [Prior, PriorArray, PriorContainer, addPrior] + :list => ["Prior", "PriorArray", "PriorContainer", "addPrior"] + ), + "compilerapi" => Dict( + :title => "Macros for Compiler", + :list => ["@assume", "@observe", "@predict", "@model"] ) ) - cd(joinpath(dirname(@__FILE__),"source")) do for fname in keys(to_gen) open("$fname.rst","w") do f println(f,"$(to_gen[fname][:title])\n=========\n") - for fun in to_gen[fname][:list] - md = Base.doc(fun) + for api in to_gen[fname][:list] + md = include_string("@doc $api") if isa(md,Markdown.MD) isa(md.content[1].content[1],Markdown.Code) || error("Incorrect docstring format: $D") @@ -49,9 +52,11 @@ cd(joinpath(dirname(@__FILE__),"source")) do end end -api_str = "" -for fname in keys(to_gen) - api_str *= "$fname\n" +# Generate API filenames +fnames = [fname for fname in keys(to_gen)] +api_str = "$(shift!(fnames))" +for fname in fnames + api_str *= "\n $fname" end rst = """ @@ -85,6 +90,7 @@ Contents :caption: APIs $api_str + .. toctree:: :maxdepth: 2 :caption: License diff --git a/doc/source/compilerapi.rst b/doc/source/compilerapi.rst new file mode 100644 index 0000000000..d91e77c8fb --- /dev/null +++ b/doc/source/compilerapi.rst @@ -0,0 +1,79 @@ +Macros for Compiler +========= + +.. function:: assume(ex) + + Operation for defining the prior. + + Usage: + + .. code-block:: julia + + @assume x ~ Dist + + Here ``x`` is a **symbol** to be used and ``Dist`` is a valid distribution from the Distributions.jl package. Optional parameters can also be passed (see examples below). + + Example: + + .. code-block:: julia + + @assume x ~ Normal(0, 1) + @assume x ~ Binomial(0, 1) + @assume x ~ Normal(0, 1; :static=true) + @assume x ~ Binomial(0, 1; :param=true) + +.. function:: observe(ex) + + Operation for defining the likelihood. + + Usage: + + .. code-block:: julia + + @observe x ~ Dist + + Here ``x`` is a **concrete value** to be used and ``Dist`` is a valid distribution from the Distributions.jl package. Optional parameters can also be passed (see examples below). + + Example: + + .. code-block:: julia + + @observe x ~ Normal(0, 1) + @observe x ~ Binomial(0, 1) + @observe x ~ Normal(0, 1; :static=true) + @observe x ~ Binomial(0, 1; :param=true) + +.. function:: predict(ex...) + + Operation for defining the the variable(s) to return. + + Usage: + + .. code-block:: julia + + @predict x y z + + Here ``x``\ , ``y``\ , ``z`` are symbols. + +.. function:: model(name, fbody) + + Wrapper for models. + + Usage: + + .. code-block:: julia + + @model f body + + Example: + + .. code-block:: julia + + @model gauss begin + @assume s ~ InverseGamma(2,3) + @assume m ~ Normal(0,sqrt(s)) + @observe 1.5 ~ Normal(m, sqrt(s)) + @observe 2.0 ~ Normal(m, sqrt(s)) + @predict s m + end + diff --git a/doc/source/index.rst b/doc/source/index.rst index 74c6979534..f2e2c79ac6 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -27,12 +27,11 @@ Contents :maxdepth: 2 :caption: APIs - replay + replayapi + compilerapi .. toctree:: :maxdepth: 2 :caption: License license - - diff --git a/doc/source/replay.rst b/doc/source/replayapi.rst similarity index 100% rename from doc/source/replay.rst rename to doc/source/replayapi.rst diff --git a/src/core/compiler.jl b/src/core/compiler.jl index fdc8b6a134..e1dd26f7f7 100644 --- a/src/core/compiler.jl +++ b/src/core/compiler.jl @@ -1,4 +1,7 @@ -# Helper function +################### +# Helper function # +################### + doc""" has_ops(ex) @@ -22,12 +25,32 @@ function has_ops(ex) true end +########## +# Macros # +########## + +doc""" + assume(ex) + +Operation for defining the prior. + +Usage: -# Operation for defining the prior -# Usage: -# @assume x ~ Dist -# , where x is a symbol to be used -# and Dist is a valid distribution from the Distributions package +```julia +@assume x ~ Dist +``` + +Here `x` is a **symbol** to be used and `Dist` is a valid distribution from the Distributions.jl package. Optional parameters can also be passed (see examples below). + +Example: + +```julia +@assume x ~ Normal(0, 1) +@assume x ~ Binomial(0, 1) +@assume x ~ Normal(0, 1; :static=true) +@assume x ~ Binomial(0, 1; :param=true) +``` +""" macro assume(ex) dprintln(1, "marco assuming...") @assert ex.args[1] == Symbol("@~") @@ -57,10 +80,28 @@ macro assume(ex) ) end -# Operation for defining the likelihood -# Usage: -# @observe(x ~ Dist) -# , where x is a value and Dist is a valid distribution +doc""" + observe(ex) + +Operation for defining the likelihood. + +Usage: + +```julia +@observe x ~ Dist +``` + +Here `x` is a **concrete value** to be used and `Dist` is a valid distribution from the Distributions.jl package. Optional parameters can also be passed (see examples below). + +Example: + +```julia +@observe x ~ Normal(0, 1) +@observe x ~ Binomial(0, 1) +@observe x ~ Normal(0, 1; :static=true) +@observe x ~ Binomial(0, 1; :param=true) +``` +""" macro observe(ex) dprintln(1, "marco observing...") @assert ex.args[1] == Symbol("@~") @@ -91,9 +132,19 @@ macro observe(ex) ) end -# Usage: -# @predict x y z -# , where x, y, z are symbols +doc""" + predict(ex...) + +Operation for defining the the variable(s) to return. + +Usage: + +```julia +@predict x y z +``` + +Here `x`, `y`, `z` are symbols. +""" macro predict(ex...) dprintln(1, "marco predicting...") ex_funcs = Expr(:block) @@ -113,9 +164,29 @@ macro predict(ex...) esc(ex_funcs) end +doc""" + model(name, fbody) + +Wrapper for models. + +Usage: + +```julia +@model f body +``` -# Usage: -# @model f body +Example: + +```julia +@model gauss begin + @assume s ~ InverseGamma(2,3) + @assume m ~ Normal(0,sqrt(s)) + @observe 1.5 ~ Normal(m, sqrt(s)) + @observe 2.0 ~ Normal(m, sqrt(s)) + @predict s m +end +``` +""" macro model(name, fbody) dprintln(1, "marco modelling...") # Functions defined via model macro have an implicit varinfo array. From 072e0340fc790cfa723aee045c25431c92ce4abb Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 13:54:18 +0000 Subject: [PATCH 07/15] Add sampler APIs --- doc/genrst.jl | 27 ++++++------ doc/source/compilerapi.rst | 2 +- doc/source/index.rst | 20 +++++---- doc/source/sampler.rst | 2 - doc/source/samplerapi.rst | 83 +++++++++++++++++++++++++++++++++++++ doc/source/samplerintro.rst | 2 + src/samplers/hmc.jl | 21 ++++++++++ src/samplers/is.jl | 22 ++++++++++ src/samplers/pgibbs.jl | 21 ++++++++++ src/samplers/smc.jl | 22 ++++++++++ 10 files changed, 198 insertions(+), 24 deletions(-) delete mode 100644 doc/source/sampler.rst create mode 100644 doc/source/samplerapi.rst create mode 100644 doc/source/samplerintro.rst diff --git a/doc/genrst.jl b/doc/genrst.jl index ceb6903604..66bbc0c371 100644 --- a/doc/genrst.jl +++ b/doc/genrst.jl @@ -25,12 +25,16 @@ end to_gen = Dict( "replayapi" => Dict( - :title => "Replay", - :list => ["Prior", "PriorArray", "PriorContainer", "addPrior"] + :title => "Replay", + :list => ["Prior", "PriorArray", "PriorContainer", "addPrior"] ), "compilerapi" => Dict( - :title => "Macros for Compiler", - :list => ["@assume", "@observe", "@predict", "@model"] + :title => "Compiler", + :list => ["@assume", "@observe", "@predict", "@model"] + ), + "samplerapi" => Dict( + :title => "Sampler", + :list => ["IS", "SMC", "PG", "HMC"] ) ) @@ -74,23 +78,22 @@ Contents usage demos +.. toctree:: + :maxdepth: 2 + :caption: APIs + + $api_str + .. toctree:: :maxdepth: 2 :caption: Development Notes language compiler - sampler - coroutines + samplerintro tarray workflow -.. toctree:: - :maxdepth: 2 - :caption: APIs - - $api_str - .. toctree:: :maxdepth: 2 :caption: License diff --git a/doc/source/compilerapi.rst b/doc/source/compilerapi.rst index d91e77c8fb..31bcb78320 100644 --- a/doc/source/compilerapi.rst +++ b/doc/source/compilerapi.rst @@ -1,4 +1,4 @@ -Macros for Compiler +Compiler ========= .. function:: assume(ex) diff --git a/doc/source/index.rst b/doc/source/index.rst index f2e2c79ac6..6bde76a576 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -12,26 +12,28 @@ Contents usage demos +.. toctree:: + :maxdepth: 2 + :caption: APIs + + replayapi + samplerapi + compilerapi + .. toctree:: :maxdepth: 2 :caption: Development Notes language compiler - sampler - coroutines + samplerintro tarray workflow -.. toctree:: - :maxdepth: 2 - :caption: APIs - - replayapi - compilerapi - .. toctree:: :maxdepth: 2 :caption: License license + + diff --git a/doc/source/sampler.rst b/doc/source/sampler.rst deleted file mode 100644 index 0bdb593b9b..0000000000 --- a/doc/source/sampler.rst +++ /dev/null @@ -1,2 +0,0 @@ -Samplers -============ diff --git a/doc/source/samplerapi.rst b/doc/source/samplerapi.rst new file mode 100644 index 0000000000..227fdaf25e --- /dev/null +++ b/doc/source/samplerapi.rst @@ -0,0 +1,83 @@ +Sampler +========= + +.. function:: IS(n_particles::Int) + + Importance sampler. + + Usage: + + .. code-block:: julia + + IS(1000) + + Example: + + .. code-block:: julia + + @model example begin + ... + end + + sample(example, IS(1000)) + +.. function:: SMC(n_particles::Int) + + Sequential Monte Carlo sampler. + + Usage: + + .. code-block:: julia + + SMC(1000) + + Example: + + .. code-block:: julia + + @model example begin + ... + end + + sample(example, SMC(1000)) + +.. function:: PG(n_particles::Int, n_iterations::Int) + + Particle Gibbs sampler. + + Usage: + + .. code-block:: julia + + PG(100, 100) + + Example: + + .. code-block:: julia + + @model example begin + ... + end + + sample(example, PG(100, 100)) + +.. function:: HMC(n_samples::Int64, lf_size::Float64, lf_num::Int64) + + Hamiltonian Monte Carlo sampler. + + Usage: + + .. code-block:: julia + + HMC(1000, 0.05, 10) + + Example: + + .. code-block:: julia + + @model example begin + ... + end + + sample(example, HMC(1000, 0.05, 10)) + diff --git a/doc/source/samplerintro.rst b/doc/source/samplerintro.rst new file mode 100644 index 0000000000..d4a8d7d905 --- /dev/null +++ b/doc/source/samplerintro.rst @@ -0,0 +1,2 @@ +Breif Introduction to Supported Samplers +============ diff --git a/src/samplers/hmc.jl b/src/samplers/hmc.jl index 66c5516b5a..b71b2b7901 100644 --- a/src/samplers/hmc.jl +++ b/src/samplers/hmc.jl @@ -4,6 +4,27 @@ else RerunThreshold = 1 end +doc""" + HMC(n_samples::Int64, lf_size::Float64, lf_num::Int64) + +Hamiltonian Monte Carlo sampler. + +Usage: + +```julia +HMC(1000, 0.05, 10) +``` + +Example: + +```julia +@model example begin + ... +end + +sample(example, HMC(1000, 0.05, 10)) +``` +""" immutable HMC <: InferenceAlgorithm n_samples :: Int64 # number of samples lf_size :: Float64 # leapfrog step size diff --git a/src/samplers/is.jl b/src/samplers/is.jl index a0069cdb82..376c281a81 100644 --- a/src/samplers/is.jl +++ b/src/samplers/is.jl @@ -1,3 +1,25 @@ + +doc""" + IS(n_particles::Int) + +Importance sampler. + +Usage: + +```julia +IS(1000) +``` + +Example: + +```julia +@model example begin + ... +end + +sample(example, IS(1000)) +``` +""" immutable IS <: InferenceAlgorithm n_samples :: Int end diff --git a/src/samplers/pgibbs.jl b/src/samplers/pgibbs.jl index cd8422a49d..289a2c93fc 100644 --- a/src/samplers/pgibbs.jl +++ b/src/samplers/pgibbs.jl @@ -1,5 +1,26 @@ # Particle Gibbs sampler +doc""" + PG(n_particles::Int, n_iterations::Int) + +Particle Gibbs sampler. + +Usage: + +```julia +PG(100, 100) +``` + +Example: + +```julia +@model example begin + ... +end + +sample(example, PG(100, 100)) +``` +""" immutable PG <: InferenceAlgorithm n_particles :: Int n_iterations :: Int diff --git a/src/samplers/smc.jl b/src/samplers/smc.jl index 8793589000..ae33460ae8 100644 --- a/src/samplers/smc.jl +++ b/src/samplers/smc.jl @@ -1,3 +1,25 @@ + +doc""" + SMC(n_particles::Int) + +Sequential Monte Carlo sampler. + +Usage: + +```julia +SMC(1000) +``` + +Example: + +```julia +@model example begin + ... +end + +sample(example, SMC(1000)) +``` +""" immutable SMC <: InferenceAlgorithm n_particles :: Int resampler :: Function From 17b6d1733814b6bba8a6e9d7d8044520f228cf00 Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 14:02:02 +0000 Subject: [PATCH 08/15] Copy front page --- doc/genrst.jl | 4 +- doc/source/demos.rst | 2 - doc/source/getstarted.rst | 128 ++++++++++++++++++++++++++++++++++++ doc/source/installation.rst | 2 - doc/source/usage.rst | 2 - 5 files changed, 129 insertions(+), 9 deletions(-) delete mode 100644 doc/source/demos.rst create mode 100644 doc/source/getstarted.rst delete mode 100644 doc/source/installation.rst delete mode 100644 doc/source/usage.rst diff --git a/doc/genrst.jl b/doc/genrst.jl index 66bbc0c371..444a209691 100644 --- a/doc/genrst.jl +++ b/doc/genrst.jl @@ -74,9 +74,7 @@ Contents :maxdepth: 2 :caption: Getting Started - installation - usage - demos + getstarted .. toctree:: :maxdepth: 2 diff --git a/doc/source/demos.rst b/doc/source/demos.rst deleted file mode 100644 index 9ea6166b72..0000000000 --- a/doc/source/demos.rst +++ /dev/null @@ -1,2 +0,0 @@ -Demos -==================== diff --git a/doc/source/getstarted.rst b/doc/source/getstarted.rst new file mode 100644 index 0000000000..89059228c9 --- /dev/null +++ b/doc/source/getstarted.rst @@ -0,0 +1,128 @@ +Get Started +========= + +Turing is a Julia library for probabilistic programming. A Turing +probabilistic program is just a normal Julia program, wrapped in a +``@model`` macro, that uses some of the special macros listed below. +Available inference methods include Importance Sampling, Sequential +Monte Carlo, Particle Gibbs. + +Authors: `Hong Ge `__, `Adam +Scibior `__, `Matej +Balog `__, `Zoubin +Ghahramani `__ + +Relevant papers +~~~~~~~~~~~~~~~ + +1. Ghahramani, Zoubin. "Probabilistic machine learning and artificial + intelligence." Nature 521, no. 7553 (2015): 452-459. + (`pdf `__) +2. Ge, Hong, Adam Scibior, and Zoubin Ghahramani "Turing: A fast + imperative probabilistic programming language." (In submission). + +Example +~~~~~~~ + +.. code:: julia + + @model gaussdemo begin + # Define a simple Normal model with unknown mean and variance. + @assume s ~ InverseGamma(2,3) + @assume m ~ Normal(0,sqrt(s)) + @observe 1.5 ~ Normal(m, sqrt(s)) + @observe 2.0 ~ Normal(m, sqrt(s)) + @predict s m + end + +Installation +------------ + +You will need Julia 0.4, which you can get from the official Julia +`website `__. We recommend that you +install a pre-compiled package, as Turing may not work correctly with +Julia built form source. + +Turing is an officially registered Julia package, so the following +should work: + +.. code:: julia + + Pkg.update() + Pkg.add("Turing") + Pkg.test("Turing") + +If Turing can not be located, you can try the following instead: + +.. code:: julia + + Pkg.clone("https://github.com/yebai/Turing.jl") + Pkg.build("Turing") + Pkg.test("Turing") + +If all tests pass, you're ready to start using Turing. + +Modelling API +------------- + +A probabilistic program is Julia code wrapped in a ``@model`` macro. It +can use arbitrary Julia code, but to ensure correctness of inference it +should not have external effects or modify global state. Stack-allocated +variables are safe, but mutable heap-allocated objects may lead to +subtle bugs when using task copying. To help avoid those we provide a +Turing-safe datatype ``TArray`` that can be used to create mutable +arrays in Turing programs. + +For probabilistic effects, Turing programs should use the following +macros: + +``@assume x ~ distr`` where ``x`` is a symbol and ``distr`` is a +distribution. Inside the probabilistic program this puts a random +variable named ``x``, distributed according to ``distr``, in the current +scope. ``distr`` can be a value of any type that implements +``rand(distr)``, which samples a value from the distribution ``distr``. + +``@observe y ~ distr`` This is used for conditioning in a style similar +to Anglican. Here ``y`` should be a value that is observed to have been +drawn from the distribution ``distr``. The likelihood is computed using +``pdf(distr,y)`` and should always be positive to ensure correctness of +inference algorithms. The observe statements should be arranged so that +every possible run traverses all of them in exactly the same order. This +is equivalent to demanding that they are not placed inside stochastic +control flow. + +``@predict x`` Registers the current value of ``x`` to be inspected in +the results of inference. + +Inference API +------------- + +Inference methods are functions which take the probabilistic program as +one of the arguments. + +.. code:: julia + + # run sampler, collect results + chain = sample(gaussdemo, SMC(500)) + chain = sample(gaussdemo, PG(10,500)) + +Task copying +------------ + +Turing `copies `__ Julia +tasks to deliver efficient inference algorithms, but it also provides +alternative slower implementation as a fallback. Task copying is enabled +by default. Task copying requires building a small C program, which +should be done automatically on Linux and Mac systems that have GCC and +Make installed. + +.. |Build Status| image:: https://travis-ci.org/yebai/Turing.jl.svg?branch=master + :target: https://travis-ci.org/yebai/Turing.jl +.. |Build status| image:: https://ci.appveyor.com/api/projects/status/fvgi21998e1tfx0d/branch/master?svg=true + :target: https://ci.appveyor.com/project/yebai/turing-jl/branch/master +.. |Coverage Status| image:: https://coveralls.io/repos/github/yebai/Turing.jl/badge.svg?branch=master + :target: https://coveralls.io/github/yebai/Turing.jl?branch=master +.. |Turing| image:: http://pkg.julialang.org/badges/Turing_0.4.svg + :target: http://pkg.julialang.org/?pkg=Turing +.. |Gitter| image:: https://badges.gitter.im/gitterHQ/gitter.svg + :target: https://gitter.im/Turing-jl/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge diff --git a/doc/source/installation.rst b/doc/source/installation.rst deleted file mode 100644 index f1ae994f3b..0000000000 --- a/doc/source/installation.rst +++ /dev/null @@ -1,2 +0,0 @@ -Installation Notes -================= diff --git a/doc/source/usage.rst b/doc/source/usage.rst deleted file mode 100644 index 257d3d724f..0000000000 --- a/doc/source/usage.rst +++ /dev/null @@ -1,2 +0,0 @@ -Usage -========= From 449244b763c1f8b870abc310b0bb68054f479beb Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 14:04:17 +0000 Subject: [PATCH 09/15] Re-gen docs --- doc/source/gettingstarted.rst | 11 ----------- doc/source/index.rst | 4 +--- 2 files changed, 1 insertion(+), 14 deletions(-) delete mode 100644 doc/source/gettingstarted.rst diff --git a/doc/source/gettingstarted.rst b/doc/source/gettingstarted.rst deleted file mode 100644 index 56d1d9a6b9..0000000000 --- a/doc/source/gettingstarted.rst +++ /dev/null @@ -1,11 +0,0 @@ -Getting Started -=============== - -Try Turing ----------- - -Learning --------- - -Need help? ----------- diff --git a/doc/source/index.rst b/doc/source/index.rst index 6bde76a576..88b66dbb8c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,9 +8,7 @@ Contents :maxdepth: 2 :caption: Getting Started - installation - usage - demos + getstarted .. toctree:: :maxdepth: 2 From 487adefb44ee55e3e5e54ea877b1e286f836bc1b Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 14:14:09 +0000 Subject: [PATCH 10/15] Add comments --- doc/genrst.jl | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/genrst.jl b/doc/genrst.jl index 444a209691..cf91f959f5 100644 --- a/doc/genrst.jl +++ b/doc/genrst.jl @@ -1,4 +1,6 @@ -using Turing +#################### +# Helper functions # +#################### if VERSION < v"0.5.0-" function Markdown.rstinline(io::IO, md::Markdown.Link) @@ -23,6 +25,10 @@ function printrst(io,md) end end +# Load the package to bind docs +using Turing + +# NOTE: this is the to-generate list. Each key-value mapping will be convereted into a .rst file. :title is the title of this .rst file and :list contains APIs to be generated. to_gen = Dict( "replayapi" => Dict( :title => "Replay", @@ -38,6 +44,7 @@ to_gen = Dict( ) ) +# Generate all APIs cd(joinpath(dirname(@__FILE__),"source")) do for fname in keys(to_gen) open("$fname.rst","w") do f @@ -63,6 +70,7 @@ for fname in fnames api_str *= "\n $fname" end +# Generate index.rst rst = """ Welcome to Turing.jl's documentation! ===================================== From 5c860d86a212ec499086369bba1d4ec9cf4534f5 Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 16:15:44 +0000 Subject: [PATCH 11/15] Add comments --- doc/genrst.jl | 4 ++++ src/trace/tarray.jl | 47 +++++++++++++++++++++++++++++++++++++++------ 2 files changed, 45 insertions(+), 6 deletions(-) diff --git a/doc/genrst.jl b/doc/genrst.jl index cf91f959f5..b5ed1af8dd 100644 --- a/doc/genrst.jl +++ b/doc/genrst.jl @@ -41,6 +41,10 @@ to_gen = Dict( "samplerapi" => Dict( :title => "Sampler", :list => ["IS", "SMC", "PG", "HMC"] + )， + "tarray" => Dict( + :title => "TArray", + :list => ["TArray", "tzeros"] ) ) diff --git a/src/trace/tarray.jl b/src/trace/tarray.jl index fbe3bfc4ee..b913c2a9e6 100644 --- a/src/trace/tarray.jl +++ b/src/trace/tarray.jl @@ -1,8 +1,28 @@ -# Implementation of data structures that automatically -# perform copy-on-write after task copying. +########## +# TArray # +########## -# If current_task is an existing key in s, then return s[current_task]. -# Otherwise, return s[current_task] = s[last_task]. +doc""" + TArray{T}(dims, ...) + +Implementation of data structures that automatically perform copy-on-write after task copying. + +If current_task is an existing key in `s`, then return `s[current_task]`. Otherwise, return `s[current_task] = s[last_task]`. + +Usage: + +```julia +TArray(dim) +``` + +Example: + +```julia +ta = TArray(4) # init +for i in 1:4 ta[i] = i end # assign +Array(ta) # convert to 4-element Array{Int64,1}: [1, 2, 3, 4] +``` +""" immutable TArray{T,N} <: DenseArray{T,N} ref :: Symbol # object_id TArray() = new(gensym()) @@ -91,12 +111,26 @@ Base.ndims(S::TArray) = Base.ndims(task_local_storage(S.ref)[2]) Base.get(t::Task, S) = S Base.get(t::Task, S::TArray) = (t.storage[S.ref][2]) -## convenience constructors ## +########## +# tzeros # +########## -""" +doc""" tzeros(dims, ...) + Construct a distributed array of zeros. Trailing arguments are the same as those accepted by `TArray`. + +```julia +tzeros(dim) +``` + +Example: + +```julia +tz = tzeros(4) # construct +Array(tz) # convert to 4-element Array{Int64,1}: [0, 0, 0, 0] +``` """ function tzeros(T::Type, dim) res = TArray{T,length(dim)}(); @@ -105,6 +139,7 @@ function tzeros(T::Type, dim) task_local_storage(res.ref, (t,d)) res end + tzeros{T}(::Type{T}, d1::Integer, drest::Integer...) = tzeros(T, convert(Dims, tuple(d1, drest...))) tzeros(d1::Integer, drest::Integer...) = tzeros(Float64, convert(Dims, tuple(d1, drest...))) tzeros(d::Dims) = tzeros(Float64, d) From 2ac407060c97832914c332e8e51dc6b844f6a9c8 Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 16:16:22 +0000 Subject: [PATCH 12/15] Gen doc --- doc/genrst.jl | 2 +- doc/source/index.rst | 1 + doc/source/tarray.rst | 37 +++++++++++++++++++++++++++++++++++++ 3 files changed, 39 insertions(+), 1 deletion(-) diff --git a/doc/genrst.jl b/doc/genrst.jl index b5ed1af8dd..519bea83a2 100644 --- a/doc/genrst.jl +++ b/doc/genrst.jl @@ -41,7 +41,7 @@ to_gen = Dict( "samplerapi" => Dict( :title => "Sampler", :list => ["IS", "SMC", "PG", "HMC"] - )， + ), "tarray" => Dict( :title => "TArray", :list => ["TArray", "tzeros"] diff --git a/doc/source/index.rst b/doc/source/index.rst index 88b66dbb8c..5adaeb7583 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -16,6 +16,7 @@ Contents replayapi samplerapi + tarray compilerapi .. toctree:: diff --git a/doc/source/tarray.rst b/doc/source/tarray.rst index 8b13789179..df4d0a9517 100644 --- a/doc/source/tarray.rst +++ b/doc/source/tarray.rst @@ -1 +1,38 @@ +TArray +========= + +.. function:: TArray{T}(dims, ...) + + Implementation of data structures that automatically perform copy-on-write after task copying. + + If current_task is an existing key in ``s``\ , then return ``s[current_task]``\ . Otherwise, return ``s[current_task] = s[last_task]``\ . + + Usage: + + .. code-block:: julia + + TArray(dim) + + Example: + + .. code-block:: julia + + ta = TArray(4) # init + for i in 1:4 ta[i] = i end # assign + Array(ta) # convert to 4-element Array{Int64,1}: [1, 2, 3, 4] + +.. function:: tzeros(dims, ...) + + Construct a distributed array of zeros. Trailing arguments are the same as those accepted by ``TArray``\ . + + .. code-block:: julia + + tzeros(dim) + + Example: + + .. code-block:: julia + + tz = tzeros(4) # construct + Array(tz) # convert to 4-element Array{Int64,1}: [0, 0, 0, 0] From 06a65ef4258e54c78a09cccb703f0767d679a561 Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 16:36:26 +0000 Subject: [PATCH 13/15] Add comments --- doc/genrst.jl | 8 +++- doc/source/chainapi.rst | 47 ++++++++++++++++++ doc/source/index.rst | 3 +- doc/source/{tarray.rst => tarrayapi.rst} | 0 src/Turing.jl | 2 +- src/core/io.jl | 61 +++++++++++++++++++++++- 6 files changed, 115 insertions(+), 6 deletions(-) create mode 100644 doc/source/chainapi.rst rename doc/source/{tarray.rst => tarrayapi.rst} (100%) diff --git a/doc/genrst.jl b/doc/genrst.jl index 519bea83a2..1c074ab295 100644 --- a/doc/genrst.jl +++ b/doc/genrst.jl @@ -42,9 +42,13 @@ to_gen = Dict( :title => "Sampler", :list => ["IS", "SMC", "PG", "HMC"] ), - "tarray" => Dict( + "tarrayapi" => Dict( :title => "TArray", :list => ["TArray", "tzeros"] + ), + "chainapi" => Dict( + :title => "Chain", + :list => ["Chain", "Sample"] ) ) @@ -56,7 +60,7 @@ cd(joinpath(dirname(@__FILE__),"source")) do for api in to_gen[fname][:list] md = include_string("@doc $api") if isa(md,Markdown.MD) - isa(md.content[1].content[1],Markdown.Code) || error("Incorrect docstring format: $D") + isa(md.content[1].content[1],Markdown.Code) || error("Incorrect docstring format: $api") printrst(f,md) else diff --git a/doc/source/chainapi.rst b/doc/source/chainapi.rst new file mode 100644 index 0000000000..441d76a57f --- /dev/null +++ b/doc/source/chainapi.rst @@ -0,0 +1,47 @@ +Chain +========= + +.. function:: Chain(weight::Float64, value::Array{Sample}) + + A wrapper of output trajactory of samplers. + + Example: + + .. code-block:: julia + + # Define a model + @model xxx begin + ... + @predict mu sigma + end + + # Run the inference engine + chain = sample(xxx, SMC(1000)) + + chain[:logevidence] # show the log model evidence + chain[:mu] # show the weighted trajactory for :mu + chain[:sigma] # show the weighted trajactory for :sigma + mean(chain[:mu]) # find the mean of :mu + mean(chain[:sigma]) # find the mean of :sigma + +.. function:: Sample(weight::Float64, value::Dict{Symbol,Any}) + + A wrapper of output samples. + + Example: + + .. code-block:: julia + + # Define a model + @model xxx begin + ... + @predict mu sigma + end + + # Run the inference engine + chain = sample(xxx, SMC(1000)) + + sample = chain[:mu][1] # get the first sample + sample.weight # show the weight of this sample + sample.value # show the value of this sample (a dictionary) + diff --git a/doc/source/index.rst b/doc/source/index.rst index 5adaeb7583..00501bb89e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -16,8 +16,9 @@ Contents replayapi samplerapi - tarray + tarrayapi compilerapi + chainapi .. toctree:: :maxdepth: 2 diff --git a/doc/source/tarray.rst b/doc/source/tarrayapi.rst similarity index 100% rename from doc/source/tarray.rst rename to doc/source/tarrayapi.rst diff --git a/src/Turing.jl b/src/Turing.jl index 153d90a3c8..c9117b5e50 100644 --- a/src/Turing.jl +++ b/src/Turing.jl @@ -24,7 +24,7 @@ StatsFuns.gammalogpdf(k::Real, θ::Real, x::Real) = -log(gamma(k)) - k * log(θ) ########################################### # Turing essentials - modelling macros and inference algorithms -export @model, @assume, @observe, @predict, InferenceAlgorithm, HMC, IS, SMC, PG, sample +export @model, @assume, @observe, @predict, InferenceAlgorithm, HMC, IS, SMC, PG, sample, Chain, Sample # Turing-safe data structures and associated functions export TArray, tzeros, localcopy, IArray diff --git a/src/core/io.jl b/src/core/io.jl index 5be5626f28..e15a7e734c 100644 --- a/src/core/io.jl +++ b/src/core/io.jl @@ -1,16 +1,73 @@ -# Some utility functions for extracting results. +######################### +# Sampler I/O Interface # +######################### +########## +# Sample # +########## + +doc""" + Sample(weight::Float64, value::Dict{Symbol,Any}) + +A wrapper of output samples. + +Example: + +```julia +# Define a model +@model xxx begin + ... + @predict mu sigma +end + +# Run the inference engine +chain = sample(xxx, SMC(1000)) + +sample = chain[:mu][1] # get the first sample +sample.weight # show the weight of this sample +sample.value # show the value of this sample (a dictionary) +``` +""" type Sample - weight :: Float64 # particle weight + weight :: Float64 # particle weight value :: Dict{Symbol,Any} end Base.getindex(s::Sample, v::Symbol) = Base.getindex(s.value, v) +######### +# Chain # +######### + +doc""" + Chain(weight::Float64, value::Array{Sample}) + +A wrapper of output trajactory of samplers. + +Example: + +```julia +# Define a model +@model xxx begin + ... + @predict mu sigma +end + +# Run the inference engine +chain = sample(xxx, SMC(1000)) + +chain[:logevidence] # show the log model evidence +chain[:mu] # show the weighted trajactory for :mu +chain[:sigma] # show the weighted trajactory for :sigma +mean(chain[:mu]) # find the mean of :mu +mean(chain[:sigma]) # find the mean of :sigma +``` +""" type Chain weight :: Float64 # log model evidence value :: Array{Sample} end + Chain() = Chain(0, Vector{Sample}()) function Base.show(io::IO, ch1::Chain) From fa0efb12b79b5601ea94ab4964ff76b8d5b4831c Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 16:43:29 +0000 Subject: [PATCH 14/15] Add comments --- src/Turing.jl | 27 ++++++++++++++++++--------- src/core/util.jl | 2 ++ 2 files changed, 20 insertions(+), 9 deletions(-) diff --git a/src/Turing.jl b/src/Turing.jl index c9117b5e50..caec731b54 100644 --- a/src/Turing.jl +++ b/src/Turing.jl @@ -1,15 +1,12 @@ module Turing -# Code associated with running probabilistic programs as tasks +# Code associated with running probabilistic programs as tasks. REVIEW: can we find a way to move this to where the other included files locate. include("trace/trace.jl") import Distributions: sample # to orverload sample() -using ForwardDiff: Dual, npartials +using ForwardDiff: Dual, npartials # for automatic differentiation using Turing.Traces -# TODO: move this to seperate AD module -Base.convert(::Type{Float64}, d::Dual{0,Float64}) = d.value - ########### # Warning ################################# # The following overloadings is temporary # @@ -23,6 +20,10 @@ StatsFuns.gammalogpdf(k::Real, θ::Real, x::Real) = -log(gamma(k)) - k * log(θ) ########################################### +################# +# Turing module # +################# + # Turing essentials - modelling macros and inference algorithms export @model, @assume, @observe, @predict, InferenceAlgorithm, HMC, IS, SMC, PG, sample, Chain, Sample @@ -32,16 +33,24 @@ export TArray, tzeros, localcopy, IArray # Debugging helpers export dprintln -## global data structures +# Global data structures const TURING = Dict{Symbol, Any}() global sampler = nothing global debug_level = 0 -# debugging print function: The first argument controls the verbosity of message, -# e.g. larger v leads to more verbose debugging messages. +########## +# Helper # +########## +doc""" + dprintln(v, args...) + +Debugging print function: The first argument controls the verbosity of message, e.g. larger v leads to more verbose debugging messages. +""" dprintln(v, args...) = v < Turing.debug_level ? println(args...) : nothing -# Inference code +################## +# Inference code # +################## include("core/util.jl") include("core/compiler.jl") include("core/intrinsic.jl") diff --git a/src/core/util.jl b/src/core/util.jl index 9c851b8e23..11ba5dd38d 100644 --- a/src/core/util.jl +++ b/src/core/util.jl @@ -76,4 +76,6 @@ function make_dual(dim, real, idx) return Dual(real, tuple(collect(z)...)) end +Base.convert(::Type{Float64}, d::Dual{0,Float64}) = d.value + export kl, align, realpart, dualpart, make_dual From 29f580c9c0354835d104e4132837c79dbaa44003 Mon Sep 17 00:00:00 2001 From: Kai Xu Date: Tue, 15 Nov 2016 16:48:46 +0000 Subject: [PATCH 15/15] Add comments to genrst --- doc/genrst.jl | 60 +++++++++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 26 deletions(-) diff --git a/doc/genrst.jl b/doc/genrst.jl index 1c074ab295..5ebc9b1c1e 100644 --- a/doc/genrst.jl +++ b/doc/genrst.jl @@ -25,32 +25,40 @@ function printrst(io,md) end end -# Load the package to bind docs -using Turing - -# NOTE: this is the to-generate list. Each key-value mapping will be convereted into a .rst file. :title is the title of this .rst file and :list contains APIs to be generated. -to_gen = Dict( - "replayapi" => Dict( - :title => "Replay", - :list => ["Prior", "PriorArray", "PriorContainer", "addPrior"] - ), - "compilerapi" => Dict( - :title => "Compiler", - :list => ["@assume", "@observe", "@predict", "@model"] - ), - "samplerapi" => Dict( - :title => "Sampler", - :list => ["IS", "SMC", "PG", "HMC"] - ), - "tarrayapi" => Dict( - :title => "TArray", - :list => ["TArray", "tzeros"] - ), - "chainapi" => Dict( - :title => "Chain", - :list => ["Chain", "Sample"] - ) -) +######################### +# Main auto-gen routine # +######################### + +using Turing # load the package to bind docs + +####################################################################### +# NOTE: this is the to-generate list. # +# Each key-value mapping will be convereted into a .rst file. # +# :title is the title of this .rst file, and # +# :list contains APIs to be generated. # +to_gen = Dict( # + "replayapi" => Dict( # + :title => "Replay", # + :list => ["Prior", "PriorArray", "PriorContainer", "addPrior"] # + ), # + "compilerapi" => Dict( # + :title => "Compiler", # + :list => ["@assume", "@observe", "@predict", "@model"] # + ), # + "samplerapi" => Dict( # + :title => "Sampler", # + :list => ["IS", "SMC", "PG", "HMC"] # + ), # + "tarrayapi" => Dict( # + :title => "TArray", # + :list => ["TArray", "tzeros"] # + ), # + "chainapi" => Dict( # + :title => "Chain", # + :list => ["Chain", "Sample"] # + ) # +) # +####################################################################### # Generate all APIs cd(joinpath(dirname(@__FILE__),"source")) do