Skip to content

Commit

Permalink
Options -> Config
Browse files Browse the repository at this point in the history
  • Loading branch information
@jrevels
jrevels committed Nov 10, 2016
1 parent b2d1150 commit 602805f
Show file tree
Hide file tree
Showing 28 changed files with 362 additions and 362 deletions.
12 changes: 6 additions & 6 deletions benchmark/ForwardDiffBenchmarks.jl
View file
Expand Up @@ -39,12 +39,12 @@ for f in (DiffBase.VECTOR_TO_NUMBER_FUNCS..., DiffBase.MATRIX_TO_NUMBER_FUNCS...
fval[length(x)] = @benchmarkable $(f)($x)

gout = DiffBase.DiffResult(y, similar(x, typeof(y)))
gopts = ForwardDiff.Options(x)
fgrad[length(x)] = @benchmarkable ForwardDiff.gradient!($gout, $f, $x, $gopts)
gcfg = ForwardDiff.Config(x)
fgrad[length(x)] = @benchmarkable ForwardDiff.gradient!($gout, $f, $x, $gcfg)

hout = DiffBase.DiffResult(y, similar(x, typeof(y)), similar(x, typeof(y), length(x), length(x)))
hopts = ForwardDiff.HessianOptions(hout, x)
fhess[length(x)] = @benchmarkable ForwardDiff.hessian!($hout, $f, $x, $hopts)
hcfg = ForwardDiff.HessianConfig(hout, x)
fhess[length(x)] = @benchmarkable ForwardDiff.hessian!($hout, $f, $x, $hcfg)
end
end

Expand All @@ -56,8 +56,8 @@ for f in DiffBase.ARRAY_TO_ARRAY_FUNCS
fval[length(x)] = @benchmarkable $(f)($x)

out = DiffBase.JacobianResult(y, x)
opts = ForwardDiff.Options(x)
fjac[length(x)] = @benchmarkable ForwardDiff.jacobian!($out, $f, $x, $opts)
cfg = ForwardDiff.Config(x)
fjac[length(x)] = @benchmarkable ForwardDiff.jacobian!($out, $f, $x, $cfg)
end
end

Expand Down
24 changes: 12 additions & 12 deletions docs/_rst/source/advanced_usage.rst
View file
Expand Up @@ -57,37 +57,37 @@ For example:
# output buffer
julia> out = similar(x);
# construct Options with chunk size of 1
julia> opts1 = ForwardDiff.Options{1}(x);
# construct Config with chunk size of 1
julia> cfg1 = ForwardDiff.Config{1}(x);
# construct Options with chunk size of 4
julia> opts4 = ForwardDiff.Options{4}(x);
# construct Config with chunk size of 4
julia> cfg4 = ForwardDiff.Config{4}(x);
# construct Options with chunk size of 10
julia> opts10 = ForwardDiff.Options{10}(x);
# construct Config with chunk size of 10
julia> cfg10 = ForwardDiff.Config{10}(x);
# (input length of 10000) / (chunk size of 1) = (10000 1-element chunks)
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, opts1);
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, cfg1);
0.408305 seconds (4 allocations: 160 bytes)
# (input length of 10000) / (chunk size of 4) = (2500 4-element chunks)
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, opts4);
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, cfg4);
0.295764 seconds (4 allocations: 160 bytes)
# (input length of 10000) / (chunk size of 10) = (1000 10-element chunks)
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, opts10);
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, cfg10);
0.267396 seconds (4 allocations: 160 bytes)
If you do not explicity provide a chunk size, ForwardDiff will try to guess one for you
based on your input vector:

.. code-block:: julia
# The Options constructor will automatically select a
# The Config constructor will automatically select a
# chunk size in one is not explicitly provided
julia> opts = ForwardDiff.Options(x);
julia> cfg = ForwardDiff.Config(x);
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, opts);
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, cfg);
0.266920 seconds (4 allocations: 160 bytes)
If your input dimension is a constant, you should explicitly select a chunk size rather than
Expand Down
58 changes: 29 additions & 29 deletions docs/_rst/source/basic_api.rst
View file
Expand Up @@ -19,12 +19,12 @@ Gradients of :math:`f(x) : \mathbb{R}^{n_1} \times \dots \times \mathbb{R}^{n_k}

Use ``ForwardDiff.gradient`` to differentiate functions of the form ``f(::AbstractArray)::Real``.

.. function:: ForwardDiff.gradient!(out, f, x, opts = ForwardDiff.Options(x))
.. function:: ForwardDiff.gradient!(out, f, x, cfg = ForwardDiff.Config(x))

Compute :math:`\nabla f(\vec{x})`, storing the output in ``out``. It is highly
advised to preallocate ``opts`` yourself (see the `Options`_ section below).
advised to preallocate ``cfg`` yourself (see the `Config`_ section below).

.. function:: ForwardDiff.gradient(f, x, opts = ForwardDiff.Options(x))
.. function:: ForwardDiff.gradient(f, x, cfg = ForwardDiff.Config(x))

Compute and return :math:`\nabla f(\vec{x})`.

Expand All @@ -33,22 +33,22 @@ Jacobians of :math:`f(x) : \mathbb{R}^{n_1} \times \dots \times \mathbb{R}^{n_k}

Use ``ForwardDiff.jacobian`` to differentiate functions of the form ``f(::AbstractArray)::AbstractArray``.

.. function:: ForwardDiff.jacobian!(out, f, x, opts = ForwardDiff.Options(x))
.. function:: ForwardDiff.jacobian!(out, f, x, cfg = ForwardDiff.Config(x))

Compute :math:`\mathbf{J}(f)(\vec{x})`, storing the output in ``out``. It is highly
advised to preallocate ``opts`` yourself (see the `Options`_ section below).
advised to preallocate ``cfg`` yourself (see the `Config`_ section below).

.. function:: ForwardDiff.jacobian!(out, f!, y, x, opts = ForwardDiff.Options(y, x))
.. function:: ForwardDiff.jacobian!(out, f!, y, x, cfg = ForwardDiff.Config(y, x))

Compute :math:`\mathbf{J}(f)(\vec{x})`, where :math:`f(\vec{x})` can be called as
``f!(y, x)`` such that the output of :math:`f(\vec{x})` is stored in ``y``. The output
matrix is stored in ``out``.

.. function:: ForwardDiff.jacobian(f, x, opts = ForwardDiff.Options(x))
.. function:: ForwardDiff.jacobian(f, x, cfg = ForwardDiff.Config(x))

Compute and return :math:`\mathbf{J}(f)(\vec{x})`.

.. function:: ForwardDiff.jacobian(f!, y, x, opts = ForwardDiff.Options(y, x))
.. function:: ForwardDiff.jacobian(f!, y, x, cfg = ForwardDiff.Config(y, x))

Compute and return :math:`\mathbf{J}(f)(\vec{x})`, where :math:`f(\vec{x})` can be
called as ``f!(y, x)`` such that the output of :math:`f(\vec{x})` is stored in ``y``.
Expand All @@ -58,20 +58,20 @@ Hessians of :math:`f(x) : \mathbb{R}^{n_1} \times \dots \times \mathbb{R}^{n_k}

Use ``ForwardDiff.hessian`` to perform second-order differentiation on functions of the form ``f(::AbstractArray)::Real``.

.. function:: ForwardDiff.hessian!(out, f, x, opts = ForwardDiff.HessianOptions(x))
.. function:: ForwardDiff.hessian!(out, f, x, cfg = ForwardDiff.HessianConfig(x))

Compute :math:`\mathbf{H}(f)(\vec{x})`, storing the output in ``out``. It is highly
advised to preallocate ``opts`` yourself (see the `Options`_ section below).
advised to preallocate ``cfg`` yourself (see the `Config`_ section below).

.. function:: ForwardDiff.hessian(f, x, opts = ForwardDiff.HessianOptions(x))
.. function:: ForwardDiff.hessian(f, x, cfg = ForwardDiff.HessianConfig(x))

Compute and return :math:`\mathbf{H}(f)(\vec{x})`.

Options
Config
-------

For the sake of convenience and performance, all "extra" information used by ForwardDiff's
API methods is bundled up in the ``ForwardDiff.AbstractOptions`` family of types. Theses
API methods is bundled up in the ``ForwardDiff.AbstractConfig`` family of types. Theses
types allow the user to easily feed several different parameters to ForwardDiff's API
methods, such as `chunk size <advanced_usage.html#configuring-chunk-size>`_, work buffers,
multithreading configurations, and perturbation seed configurations.
Expand All @@ -84,47 +84,47 @@ type parameter, or omitted, in which case ForwardDiff will automatically select
for you. However, it is highly recomended to `specify the chunk size manually when possible
<advanced_usage.html#configuring-chunk-size>`_.

.. function:: ForwardDiff.Options{N}(x)
.. function:: ForwardDiff.Config{N}(x)

Construct an ``Options`` instance based on the type and shape of the input vector ``x``.
The returned ``Options`` instance contains all the work buffers required by
Construct an ``Config`` instance based on the type and shape of the input vector ``x``.
The returned ``Config`` instance contains all the work buffers required by
ForwardDiff's gradient/Jacobian methods. If taking the Jacobian of a target function
with the form ``f!(y, x)``, use the constructor ``ForwardDiff.Options{N}(y, x)``
with the form ``f!(y, x)``, use the constructor ``ForwardDiff.Config{N}(y, x)``
instead.

This constructor does not store/modify ``x``.

.. function:: ForwardDiff.Options{N}(y, x)
.. function:: ForwardDiff.Config{N}(y, x)

Construct an ``Options`` instance based on the type and shape of the output vector ``y``
and the input vector ``x``. The returned ``Options`` instance contains all the work
Construct an ``Config`` instance based on the type and shape of the output vector ``y``
and the input vector ``x``. The returned ``Config`` instance contains all the work
buffers required by ``ForwardDiff.jacobian``/``ForwardDiff.jacobian!`` with a target
function of the form ``f!(y, x)``.

This constructor does not store/modify ``y`` or ``x``.

.. function:: ForwardDiff.HessianOptions{N}(x)
.. function:: ForwardDiff.HessianConfig{N}(x)

Construct a ``HessianOptions`` instance based on the type and shape of the input vector
``x``. The returned ``HessianOptions`` instance contains all the work buffers required
Construct a ``HessianConfig`` instance based on the type and shape of the input vector
``x``. The returned ``HessianConfig`` instance contains all the work buffers required
by ForwardDiff's Hessian methods. If using
``ForwardDiff.hessian!(out::DiffBase.DiffResult, args...)``, use the constructor
``ForwardDiff.HessianOptions{N}(out, x)`` instead.
``ForwardDiff.HessianConfig{N}(out, x)`` instead.

This constructor does not store/modify ``x``.

.. function:: ForwardDiff.HessianOptions{N}(out::DiffBase.DiffResult, x)
.. function:: ForwardDiff.HessianConfig{N}(out::DiffBase.DiffResult, x)

Construct an ``HessianOptions`` instance based on the type and shape of the storage in
``out`` and the input vector ``x``. The returned ``HessianOptions`` instance contains
Construct an ``HessianConfig`` instance based on the type and shape of the storage in
``out`` and the input vector ``x``. The returned ``HessianConfig`` instance contains
all the work buffers required by ``ForwardDiff.hessian!(out::DiffBase.DiffResult,
args...)``.

This constructor does not store/modify ``out`` or ``x``.

.. function:: ForwardDiff.Multithread(opts::AbstractOptions)
.. function:: ForwardDiff.Multithread(cfg::AbstractConfig)

Wrap the given ``opts`` in a ``Multithread`` instance, which can then be passed to
Wrap the given ``cfg`` in a ``Multithread`` instance, which can then be passed to
gradient or Hessian methods in order to enable experimental multithreading. Jacobian
methods do not yet support multithreading.

Expand Down
8 changes: 4 additions & 4 deletions docs/_rst/source/conf.py
View file
Expand Up @@ -106,7 +106,7 @@
todo_include_todos = False


# -- Options for HTML output ----------------------------------------------
# -- Config for HTML output ----------------------------------------------

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

Expand Down Expand Up @@ -207,7 +207,7 @@
# Output file base name for HTML help builder.
htmlhelp_basename = 'ForwardDiffjldoc'

# -- Options for LaTeX output ---------------------------------------------
# -- Config for LaTeX output ---------------------------------------------

latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
Expand Down Expand Up @@ -252,7 +252,7 @@
#latex_domain_indices = True


# -- Options for manual page output ---------------------------------------
# -- Config for manual page output ---------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
Expand All @@ -265,7 +265,7 @@
#man_show_urls = False


# -- Options for Texinfo output -------------------------------------------
# -- Config for Texinfo output -------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
Expand Down
4 changes: 2 additions & 2 deletions docs/_rst/source/upgrade.rst
View file
Expand Up @@ -34,7 +34,7 @@ Setting Chunk Size
ForwardDiff.gradient(f, x, Chunk{10}())
# current v0.3 style
ForwardDiff.gradient(f, x, ForwardDiff.Options{10}(x))
ForwardDiff.gradient(f, x, ForwardDiff.Config{10}(x))
Enabling Multithreading
-----------------------
Expand All @@ -45,7 +45,7 @@ Enabling Multithreading
ForwardDiff.gradient(f, x; multithread = true)
# current v0.3 style
ForwardDiff.gradient(f, x, ForwardDiff.Multithread(ForwardDiff.Options(x)))
ForwardDiff.gradient(f, x, ForwardDiff.Multithread(ForwardDiff.Config(x)))
Retrieving Lower-Order Results
------------------------------
Expand Down
24 changes: 12 additions & 12 deletions docs/_sources/advanced_usage.txt
View file
Expand Up @@ -57,37 +57,37 @@ For example:
# output buffer
julia> out = similar(x);

# construct Options with chunk size of 1
julia> opts1 = ForwardDiff.Options{1}(x);
# construct Config with chunk size of 1
julia> cfg1 = ForwardDiff.Config{1}(x);

# construct Options with chunk size of 4
julia> opts4 = ForwardDiff.Options{4}(x);
# construct Config with chunk size of 4
julia> cfg4 = ForwardDiff.Config{4}(x);

# construct Options with chunk size of 10
julia> opts10 = ForwardDiff.Options{10}(x);
# construct Config with chunk size of 10
julia> cfg10 = ForwardDiff.Config{10}(x);

# (input length of 10000) / (chunk size of 1) = (10000 1-element chunks)
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, opts1);
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, cfg1);
0.408305 seconds (4 allocations: 160 bytes)

# (input length of 10000) / (chunk size of 4) = (2500 4-element chunks)
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, opts4);
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, cfg4);
0.295764 seconds (4 allocations: 160 bytes)

# (input length of 10000) / (chunk size of 10) = (1000 10-element chunks)
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, opts10);
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, cfg10);
0.267396 seconds (4 allocations: 160 bytes)

If you do not explicity provide a chunk size, ForwardDiff will try to guess one for you
based on your input vector:

.. code-block:: julia

# The Options constructor will automatically select a
# The Config constructor will automatically select a
# chunk size in one is not explicitly provided
julia> opts = ForwardDiff.Options(x);
julia> cfg = ForwardDiff.Config(x);

julia> @time ForwardDiff.gradient!(out, rosenbrock, x, opts);
julia> @time ForwardDiff.gradient!(out, rosenbrock, x, cfg);
0.266920 seconds (4 allocations: 160 bytes)

If your input dimension is a constant, you should explicitly select a chunk size rather than
Expand Down

0 comments on commit 602805f

Please sign in to comment.