core/graph/json_ad_graph.omh

/* --------------------------------------------------------------------------
CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-20 Bradley M. Bell

  CppAD is distributed under the terms of the
               Eclipse Public License Version 2.0.

  This Source Code may also be made available under the following
  Secondary License when the conditions for such availability set forth
  in the Eclipse Public License, Version 2.0 are satisfied:
        GNU General Public License, Version 2.0 or later.
-------------------------------------------------------------------------- */
$begin json_ad_graph$$
$spell
    Json
    vec
    enum_op
    arg
    ind
    acyclic
    str
    np nx nc
$$

$section Json Representation of an AD Graph$$

$head See Also$$
$tref cpp_ad_graph$$.

$head Node Indices$$
The nodes in an AD graph have the following order:
$pre
    p_0 , ... ,  p_{np-1} ,
    x_0 , ... ,  x_{nx-1} ,
    c_0 , ... ,  c_{nc-1} ,
    r_0 , ... ,  r_{no-1}
$$

$subhead p$$
The sub-vector
$pre p_0, ... , p_{np-1}$$ is the independent dynamic parameter vector;
see $cref/n_dynamic_ind/json_ad_graph/dynamic_ind_vec/n_dynamic_ind/$$.
The node index corresponding to $icode p_0$$ is $code 1$$.

$subhead x$$
The sub-vector
$pre x_0, ... , x_{nx-1}$$ is the independent variable vector;
see $cref/n_variable_ind/json_ad_graph/variable_ind_vec/n_variable_ind/$$.
The node index corresponding to $icode x_0$$ is
the index corresponding to $icode p_0$$ plus $icode np$$.

$subhead c$$
The sub-vector
$pre c_0, ... , c_{nc-1}$$ is the constant parameter vector;
see $cref/constant_vec/json_ad_graph/constant_vec/$$.
The node index corresponding to $icode c_0$$ is
the index corresponding to $icode x_0$$ plus $icode nx$$.

$subhead r_i$$
For $icode%i%=0,%...%,%no%-1%$$
the sub-vector $pre r_i$$
is the result vector for the $th i$$ operator usage;
see $cref/op_usage_vec/json_ad_graph/op_usage_vec/$$.
The value $icode no$$ is the number of operator usages; see
$cref/n_usage/json_ad_graph/op_usage_vec/n_usage/$$ below.
All of the arguments for an the $th i$$ operator are nodes
that come before the first element of $icode r_i$$.
The node index corresponding to the first element of $icode r_0$$ is
the index corresponding to $icode c_0$$ plus $icode nc$$.
For $icode%i% > 0%$$,
The node index corresponding to the first element of $icode r_i$$ is
the index corresponding to the first element of $icode r_{i-1}$$ plus
the number of results for the $th i-1$$ operator.

$head Format$$
A complete description of the format for an AD graph is given below.
For a general description of Json format see
$href%
    https://en.wikipedia.org/wiki/JSON#Data_types_and_syntax%
    Json data types and syntax
%$$.

$head Token$$

$subhead White Space$$
Any sequence of white space, except within a string,
terminates the current token and is otherwise ignored.

$subhead Non-Negative Integer$$
A non-negative integer is a non-empty sequence of the following
characters: $code 0123456789$$.

$subhead Floating Point Number$$
A floating point number is a non-empty sequence of the following
characters: $code 0123456789+-eE.$$.
Note that there can't be any white space between a leading plus
or minus sign and the rest of the number.

$subhead String$$
A string starts with the double quote character $code "$$
and includes all the characters until the next double quote.
The value of a string is the sequence of characters between the
double quotes.
Currently there is no support using the double quote
as part of the value of a string.

$subhead Single Character$$
The following is a list of the single character tokens:
$table
Token      $cnext Usage                                           $rnext
$code ,$$  $cnext separates entries in a list                     $rnext
$code :$$  $cnext separates name from corresponding value         $rnext
$code {$$  $cnext starts a list of name $code :$$ value pairs     $rnext
$code }$$  $cnext ends a list of name $code:$$ value pairs        $rnext
$code [$$  $cnext starts a list of values                         $rnext
$code ]$$  $cnext ends a list of values
$tend

$head op_define_vec$$
This vector has the following Json format:
$codei%
    [ %n_define%, [ %first_op_define%, %...%, %last_op_define% ] ]
%$$
where the non-negative integer $icode n_define$$
is the number of operator definitions in this vector.

$subhead op_define$$
The possible operator definitions $icode op_define$$ are listed in
section $cref json_graph_op$$.
If an operator has a fixed number of arguments, one result, and
only node indices for arguments, its definition has the form
$codei%
{
    "op_code":      %op_code%,
    "name":         %name%,
    "n_arg":        %n_arg%
}
%$$
Otherwise the operator definition has the form
$codei%
{
    "op_code":      %op_code%,
    "name":         %name%
}
%$$
For example, the following is the $icode op_define$$ corresponding to the
$cref/add/json_graph_op/Binary Operators/add/$$ operator:
$codei%
{
    "op_code":      %op_code%,
    "name":         "add",
    "n_arg":        2
}
%$$

$subhead op_code$$
Note that every operator definition has a $icode op_code$$ value.
These values must start at one and increment by one for each operator
definition; i.e., the $icode op_code$$ for in $icode first_op_define$$ is
$code 1$$, the value in the next definition is $code 2$$, and so on.
The order of the definitions determines the $icode op_code$$ values
used to specify operators for this computational graph.

$subhead n_arg$$
This is the number of argument values for the operator; i.e.,
the dimension of its domain space.
If it is present in an operator definition,
it is the same value for every usage of the operator.
Otherwise it is specified by the operator usage.

$subhead n_result$$
This is the number of results for the operator; i.e.,
the dimension of its range space.
If $icode n_arg$$ is present in an operator definition,
$icode n_result$$ is one for every usage of the operator.
Otherwise it is specified by the operator usage.

$head op_usage$$
Each operation usage
has the following information:

$subhead n_arg In Definition$$
If $icode n_arg$$ is present in an operator definition,
it is not in a corresponding $icode op_usage$$ which as the form
$codei%
    [ %op_code%, %first_arg%, %...%, %last_arg% ]
%$$

$subhead n_arg Not In Definition$$
If $icode n_arg$$ is not in an operator definition,
it is in a corresponding $icode op_usage$$.
If there are no strings in a corresponding usage, it has the form
$codei%
    [ %op_code%, %n_result%, %n_arg%, [ %first_arg%, %...%, %last_arg% ] ]
%$$

$subhead Strings In Usage$$
If $icode n_arg$$ is not in an operator definition,
and there are strings in a corresponding usage,
a corresponding usage has the form
$codei%
    [ %op_code%, %first_str%, %...%, %last_str%, %n_result%, %n_arg%,
        [ %first_arg%, %...%, %last_arg% ]
    ]
%$$
where $icode first_str$$ ..., $icode last_str$$,
are a fixed number of strings that are part of the corresponding operator.

$subhead first_arg, ..., last_arg$$
The values $icode first_arg$$, ..., $icode last_arg$$,
are the node indices corresponding to each of the arguments for this operator.
They must be less than the node index corresponding to the first
result for this operator; see
$cref/r_i/json_ad_graph/Node Indices/r_i/$$ above.
They specify which previous results (results before this operator in the graph)
correspond to each of the arguments to this operator.
As a consequence, there cannot be any cycles in the graph where
the operators are represented by arcs from the argument to the result nodes;
i.e., the graph is acyclic.

$head dynamic_ind_vec$$
This is the independent dynamic parameter vector
(called $icode p$$ above); see
$cref/dynamic/Independent/dynamic/$$.
The function can depend on these parameters,
but no derivatives are computed with respect to these parameters.

$subhead n_dynamic_ind$$
We use the non-negative integer $icode n_dynamic_ind$$
for the number of elements in this vector
(called $icode np$$ above).

$head variable_ind_vec$$
This is the independent variable vector
(called $icode x$$ above); see
$cref/x/Independent/x/$$.
The function can depend on these variable and
derivatives can be computed  with respect to these variables.

$subhead n_variable_ind$$
We use the non-negative integer $icode n_variable_ind$$
for the number of element in this vector
(called $icode nx$$ above).

$head constant_vec$$
This is the constant parameter vector (called $icode c$$ above).
These parameters can be used to define the function and cannot change.
The Json format for $icode constant_vec$$ is
$codei%
    %n_constant%, [ %first_constant%, %...%, %last_constant% ]
%$$
Each of the elements of this vector,
e.g., $icode first_constant$$,
is a $cref/floating point number/json_ad_graph/Token/Floating Point Number/$$
specifying the value for the corresponding node.

$subhead n_constant$$
The non-negative integer $icode n_constant$$
is the number of elements in this vector
(called $icode nc$$ above).

$head op_usage_vec$$
The Jason format for an $icode op_usage_vec$$ is
$codei%
    [ %n_usage%, [ %first_op_usage%, %...%, %last_op_usage% ] ]
%$$
Each of the elements of this vector,
e.g. $icode first_op_usage$$,
is an $cref/op_usage/json_ad_graph/op_usage/$$.

$subhead n_usage$$
The non-negative integer $icode n_usage$$
is the number of operator usages (called $icode no$$ above).

$head dependent_vec$$
This is the vector of dependent variable node indices.
This identifies which nodes in the graph correspond to dependent variables.
The Json format for $icode dependent_vec$$ is
$codei%
    [ %n_dependent%, [ %first_dependent%, %...%, %last_dependent% ] ]
%$$
Each of the elements of this vector,
e.g. $icode first_dependent$$,
is a $cref/non-negative integer/json_ad_graph/Token/Non-Negative Integer/$$
corresponding to a node index in the graph.

$subhead n_dependent$$
The non-negative integer $icode n_dependent$$
is the number of elements in this vector.

$head AD Graph$$
Each operator corresponds to a set of arcs from its argument nodes
to its result nodes.
The graph is acyclic; see
$cref/
    first_arg, ..., last_arg/
    json_ad_graph/op_usage/
    first_arg, ..., last_arg
/$$.

$subhead function_name$$
A $icode function_name$$ is a
$cref/string/json_ad_graph/Token/String/$$ that is used to identify
the function.

$subhead function$$
The Json AD graph representation of a function is
$codei%
{
    "function_name": %function_name%,
    "op_define_vec": %op_define_vec%,
    "n_dynamic_ind": %n_dynamic_ind%,
    "n_variable_ind": %n_variable_ind%,
    "constant_vec":  %constant_vec%,
    "op_usage_vec":  %op_usage_vec%,
    "dependent_vec": %dependent_vec%
}
%$$
This represents a the $latex y = f(x, p)$$ where
$latex p$$ is the dynamic parameter vector,
$latex x$$ is the independent variable vector, and
$latex y$$ is the dependent variable vector.

$childtable%include/cppad/core/graph/json_graph_op.omh
    %include/cppad/core/graph/from_json.hpp
    %include/cppad/core/graph/to_json.hpp
    %example/json/get_started.cpp
    %example/json/sparse.cpp
%$$

$end