Improve Documentation (#16)

improve documentation

.travis.yml

@@ -11,11 +11,12 @@ julia:
 os:
  - osx
  - linux
- - windows
+ # - windows
 before_install:
  - if [ "$TRAVIS_OS_NAME" = "osx" ]; then brew update ; fi
  - if [ "$TRAVIS_OS_NAME" = "osx" ]; then brew install hdf5; fi
  - julia -e 'using Pkg; Pkg.add("NLopt"); Pkg.add("Optim"); Pkg.add("Statistics"); Pkg.add("LinearAlgebra"); Pkg.add("PyCall"); Pkg.add("SparseArrays"); Pkg.add("Test")'
+ - julia -e 'ENV["PYTHON"] = readlines(`which python`)[1]; using Pkg; Pkg.build("PyCall")'
 notifications:
  email: false
 coveralls: true
@@ -27,6 +28,7 @@ jobs:
  script:
  - julia --project=docs/ -e 'using Pkg;Pkg.add("Documenter"); Pkg.add("PyCall"); Pkg.add("LinearAlgebra"); Pkg.develop(PackageSpec(path=pwd()));
  Pkg.instantiate()'
+ - julia --project=docs/ -e 'ENV["PYTHON"] = readlines(`which python`)[1]; using Pkg; Pkg.build("PyCall")'
  - julia --project=docs/ docs/make.jl
  after_success: skip
 after_success:

Manifest.toml

@@ -83,9 +83,9 @@ uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 
 [[FFTW]]
 deps = ["AbstractFFTs", "BinaryProvider", "Conda", "Libdl", "LinearAlgebra", "Reexport", "Test"]
-git-tree-sha1 = "03f8776fbdae28c20c0d1d2ae4e090cd1dfcd247"
+git-tree-sha1 = "6c5b420da0b8c12098048561b8d58f81adea506f"
 uuid = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
-version = "1.0.0"
+version = "1.0.1"
 
 [[HDF5]]
 deps = ["BinaryProvider", "Blosc", "CMakeWrapper", "Libdl", "Mmap"]
@@ -149,9 +149,9 @@ version = "1.1.0"
 
 [[Parameters]]
 deps = ["OrderedCollections"]
-git-tree-sha1 = "1dfd7cd50a8eb06ef693a4c2bbe945943cd000c5"
+git-tree-sha1 = "b62b2558efb1eef1fa44e4be5ff58a515c287e38"
 uuid = "d96e819e-fc66-5662-9728-84c9c7592b0a"
-version = "0.11.0"
+version = "0.12.0"
 
 [[Parsers]]
 deps = ["Dates", "Test"]

Project.toml

@@ -1,7 +1,7 @@
 name = "ADCME"
 uuid = "07b341a0-ce75-57c6-b2de-414ffdc00be5"
 authors = ["Kailai Xu <[email protected]>"]
-version = "0.2.4"
+version = "0.2.5"
 
 [compat]
 julia = "1"

deps/CustomOps/Timer/gradtest.jl

@@ -16,7 +16,7 @@ A = constant(rand(2000,2000))
 u = set_tensor_flow_timer(i)
 v = get_tensor_flow_timer(i)
 A = bind(A, u)
-A, B, C = tf.svd(A)
+A, B, C = tf.linalg.svd(A)
 A = bind(A, v)
 sess = Session()
 init(sess)

deps/build.jl

@@ -1,17 +1,30 @@
+# install requirements.txt
+try
+ run(`which pip`)
+ if haskey(ENV, "REINSTALL_PIP")
+ error("Force Reinstall Pip...")
+ end
+catch
+ run(`wget -O get-pip.py https://bootstrap.pypa.io/get-pip.py`)
+ run(`python get-pip.py --user`)
+ rm("get-pip.py")
+end
+run(`pip install --user -U -r $(@__DIR__)/requirements.txt`)
+
+
 using PyCall
+if PyCall.python!=readlines(`which python`)[1]
+ error("Python version and PyCall Python version does not match. Please reinstall PyCall with the default Python version.
+PyCall Python: $(PyCall.python)
+System Python: $(readlines(`which python`)[1])
+Instruction: 
+julia -e 'ENV[\"PYTHON\"] = readlines(`which python`)[1]; using Pkg; Pkg.build(\"PyCall\")")
+end
 
 if Sys.iswindows()
  @warn "PyTorch plugin is still under construction for Windows platform and will be disabled for the current version."
 end
 
-function package_exist(s::String)
-py"""
-import pkgutil; 
-exist_ = True if pkgutil.find_loader($s) else False
-"""
-py"exist_"
-end
-
 function mksymlink()
  tf = pyimport("tensorflow")
  if Sys.isapple()
@@ -34,27 +47,4 @@ function mksymlink()
  end
 end
 
-function install_tensorflow()
- if haskey(ENV,"REINSTALL_PIP")
- @info "Reinstall pip..."
- download("https://bootstrap.pypa.io/get-pip.py", "get-pip.py")
- run(`$(PyCall.python) get-pip.py --user`)
- rm("get-pip.py")
- end
- try 
- run(`$(PyCall.python) -m pip --version`)
- catch
- @warn "pip is not installed, downloading and installing pip..."
- download("https://bootstrap.pypa.io/get-pip.py", "get-pip.py")
- run(`$(PyCall.python) get-pip.py --user`)
- rm("get-pip.py")
- end
- run(`$(PyCall.python) -m pip install --user -U numpy`)
- run(`$(PyCall.python) -m pip install --user tensorflow==1.14`)
- run(`$(PyCall.python) -m pip install --user tensorflow_probability==0.7`)
-end
-
-if !(package_exist("tensorflow") && package_exist("tensorflow_probability"))
- install_tensorflow()
-end
 mksymlink()

deps/requirements.txt

@@ -0,0 +1,5 @@
+tensorflow==1.14
+tensorflow_probability==0.7
+numpy
+scipy
+matplotlib

docs/make.jl

@@ -1,23 +1,30 @@
-using PyCall 
 
-function install_packages()
- try 
- run(`$(PyCall.python) -m pip --version`)
- catch
- @warn "pip is not installed, downloading and installing pip..."
- download("https://bootstrap.pypa.io/get-pip.py", "get-pip.py")
- run(`$(PyCall.python) get-pip.py --user`)
- rm("get-pip.py")
+try
+ run(`which pip`)
+ if haskey(ENV, "REINSTALL_PIP")
+ error("Force Reinstall Pip...")
  end
- run(`$(PyCall.python) -m pip install --user scipy`)
- run(`$(PyCall.python) -m pip install --user matplotlib`)
- run(`$(PyCall.python) -m pip install --user -U numpy`)
- run(`$(PyCall.python) -m pip install --user tensorflow==1.14`)
- run(`$(PyCall.python) -m pip install --user tensorflow_probability==0.7`)
+catch
+ run(`wget -O get-pip.py https://bootstrap.pypa.io/get-pip.py`)
+ run(`python get-pip.py --user`)
+ rm("get-pip.py")
 end
+run(`pip install --user tensorflow==1.14`)
+run(`pip install --user tensorflow_probability==0.7`)
+run(`pip install --user -U numpy`)
+run(`pip install --user -U scipy`)
+run(`pip install --user -U matplotlib`)
+
 
-install_packages()
+using PyCall 
 using Pkg; Pkg.add("PyPlot")
+if PyCall.python!=readlines(`which python`)[1]
+ error("Python version and PyCall Python version does not match. Please reinstall PyCall with the default Python version.
+PyCall Python: $(PyCall.python)
+System Python: $(readlines(`which python`)[1])
+Instruction: 
+julia -e 'ENV[\"PYTHON\"] = readlines(`which python`)[1]; using Pkg; Pkg.build(\"PyCall\")")
+end
 
 using Documenter, ADCME
 makedocs(sitename="ADCME", modules=[ADCME],
@@ -27,7 +34,6 @@ pages = Any[
 ],
 authors = "Kailai Xu")
 
-
 deploydocs(
  repo = "github.com/kailaix/ADCME.jl.git",
 )

docs/src/extra.md

@@ -20,4 +20,39 @@ run(sess, t)
 ```@docs
 tic
 toc
-```
+```
+
+## Save and Load Python Object
+```@docs
+psave
+pload
+```
+
+## Save and Load TensorFlow Session
+```@docs
+load
+save
+```
+
+## Save and Load Diary
+
+We can use TensorBoard to track a scalar value easily
+```julia
+d = Diary("test")
+p = placeholder(1.0, dtype=Float64)
+b = constant(1.0)+p
+s = scalar(b, "variable")
+for i = 1:100
+ write(d, i, run(sess, s, Dict(p=>Float64(i))))
+end
+activate(d)
+```
+
+```@docs
+Diary
+scalar
+activate
+load
+save
+write
+```

src/ADCME.jl

@@ -15,6 +15,7 @@ module ADCME
  tf = PyNULL()
  tfp = PyNULL()
  tfops = PyNULL()
+ pickle = PyNULL()
  gradients_impl = PyNULL()
  DTYPE = Dict{Type, PyObject}()
  # a list of custom operators 
@@ -27,39 +28,15 @@ module ADCME
  )
 
  libSuffix = Sys.isapple() ? "dylib" : (Sys.islinux() ? "so" : "dll")
-
- function install_tensorflow()
- if haskey(ENV,"REINSTALL_PIP")
- @info "Reinstall pip..."
- download("https://bootstrap.pypa.io/get-pip.py", "get-pip.py")
- run(`$(PyCall.python) get-pip.py --user`)
- rm("get-pip.py")
- end
- try 
- run(`$(PyCall.python) -m pip --version`)
- catch
- @warn "pip is not installed, downloading and installing pip..."
- download("https://bootstrap.pypa.io/get-pip.py", "get-pip.py")
- run(`$(PyCall.python) get-pip.py --user`)
- rm("get-pip.py")
- end
- run(`$(PyCall.python) -m pip install --user -U numpy`)
- run(`$(PyCall.python) -m pip install --user tensorflow==1.14`)
- run(`$(PyCall.python) -m pip install --user tensorflow_probability==0.7`)
- end
 
 
  function __init__()
  global AUTO_REUSE, GLOBAL_VARIABLES, TRAINABLE_VARIABLES, UPDATE_OPS, DTYPE
- if haskey(ENV,"REINSTALL_PIP")
- install_tensorflow()
- PYTHONPATH="/home/travis/.local/lib/python3.5/site-packages"
- end
-
  copy!(tf, pyimport("tensorflow"))
  copy!(tfops, pyimport("tensorflow.python.framework.ops"))
  copy!(tfp, pyimport("tensorflow_probability"))
  copy!(gradients_impl, pyimport("tensorflow.python.ops.gradients_impl"))
+ copy!(pickle, pyimport("pickle"))
  DTYPE = Dict(Float64=>tf.float64,
  Float32=>tf.float32,
  Int64=>tf.int64,

src/core.jl

@@ -1,60 +1,80 @@
 export
-Graph,
 reset_default_graph,
-get_default_graph,
 get_collection,
-add_to_collection,
-finalize_graph,
+add_collection,
 enable_eager_execution,
-value,
 control_dependencies,
 has_gpu,
 while_loop,
 if_else,
 stop_gradient,
 tensor,
-RegisterGradient
-
+tensorname
 
+# only for eager eager execution
+enable_eager_execution() = tf.enable_eager_execution()
+Base.:values(o::PyObject) = o.numpy()
 
+"""
+ reset_default_graph()
 
-Graph() = tf.Graph()
+Resets the graph by removing all the operators. 
+"""
 reset_default_graph() = tf.compat.v1.reset_default_graph()
-get_default_graph() = tf.get_default_graph()
-enable_eager_execution() = tf.enable_eager_execution()
-value(o::PyObject) = o.numpy()
-function RegisterGradient(args...;kwargs...)
- try
- tfops.RegisterGradient(args...;kwargs...)
- catch e
- @warn(e)
+"""
+ get_collection(name::Union{String, Missing})
+
+Returns the collection with name `name`. If `name` is `missing`, returns all the trainable variables.
+"""
+function get_collection(name::Union{String, Missing})
+ if ismissing(name)
+ res = tf.compat.v1.get_collection(TRAINABLE_VARIABLES)
+ else
+ res = tf.get_default_graph()._collections[name]
  end
+ return unique(res)
 end
 
 """
-finalize(s::PyObject)
+ add_collection(name::String, v::PyObject)
 
-The method can help to catch leaks like this: it marks a graph as read-only, and raises an exception if anything is added to the graph
-Reference: https://riptutorial.com/tensorflow/example/13426/use-graph-finalize---to-catch-nodes-being-added-to-the-graph
+Adds `v` to the collection with name `name`. If `name` does not exist, a new one is created.
 """
-finalize_graph(s::PyObject) = s.graph.finalize()
+function add_collection(name::String, v::PyObject)
+ tf.get_default_graph().add_to_collection(name, v)
+ nothing
+end
 
+"""
+ add_collection(name::String, vs::PyObject...)
 
-# TensorFlow Graph Collections
-function get_collection(name, args...;kwargs...)
- if !(name in [GLOBAL_VARIABLES, TRAINABLE_VARIABLES, UPDATE_OPS])
- return get_collection(GLOBAL_VARIABLES, scope=name)
- else
- return tf.get_collection(name, args...;kwargs...)
+Adds operators `vs` to the collection with name `name`. If `name` does not exist, a new one is created.
+"""
+function add_collection(name::String, vs::PyObject...)
+ for v in vs
+ add_collection(name, v)
  end
+ nothing
 end
-add_to_collection(args...;kwargs...) = tf.get_collection(args...;kwargs...)
 
+"""
+ tensor(s::String)
 
+Returns the tensor with name `s`. See [`tensorname`](@ref).
+"""
 function tensor(s::String)
  tf.get_default_graph().get_tensor_by_name(s)
 end
 
+"""
+ tensorname(o::PyObject)
+
+Returns the name of the tensor. See [`tensor`](@ref).
+"""
+function tensorname(o::PyObject)
+ o.name
+end
+
 function jlargs(kwargs)
  kwargs = Dict{Any, Any}(kwargs)
  if :axis in keys(kwargs)