Package cgraph. March 11, 2019

Transcription

1 Type Package Title Computational Graphs Version Author Maintainer URL Package cgraph March 11, 2019 BugReports Allows to create, evaluate, and differentiate computational graphs in R. A computational graph is a graph representation of a multivariate function decomposed by its (elementary) operations. Nodes in the graph represent arrays while edges represent dependencies among the arrays. An advantage of epressing a function as a computational graph is that this enables to differentiate the function by automatic differentiation. The 'cgraph' package supports various operations including basic arithmetic, trigonometry operations, and linear algebra operations. It differentiates computational graphs by reverse automatic differentiation. The fleible architecture of the package makes it applicable to solve a variety of problems including local sensitivity analysis, gradient-based optimization, and machine learning. License Apache License 2.0 Encoding UTF-8 LazyData true Suggests testthat Roygen NeedsCompilation yes Repository CRAN Date/Publication :42:46 UTC R topics documented: cg_abs cg_acos

2 2 R topics documented: cg_acosh cg_add cg_asin cg_asinh cg_as_double cg_as_numeric cg_atan cg_atanh cg_colsums cg_constant cg_cos cg_cosh cg_crossprod cg_div cg_ep cg_function cg_graph cg_graph_gradients cg_graph_run cg_input cg_linear cg_ln cg_log cg_log cg_matmul cg_ma cg_mean cg_min cg_mul cg_neg cg_operator cg_parameter cg_pma cg_pmin cg_pos cg_pow cg_prod cg_rowsums cg_session_graph cg_session_set_graph cg_sigmoid cg_sin cg_sinh cg_sqrt cg_sub cg_sum cg_t cg_tan

3 cg_abs 3 cg_tanh cg_tcrossprod Inde 40 cg_abs Absolute Calculate abs(). cg_abs(, = NULL) character scalar, of the operation (optional). abs cg_acos Inverse Cosine Calculate acos(). cg_acos(, = NULL) character scalar, of the operation (optional).

4 4 cg_acosh acos cg_acosh Inverse Hyperbolic Cosine Calculate acosh(). cg_acosh(, = NULL) character scalar, of the operation (optional). acosh

5 cg_add 5 cg_add Add Calculate + y. cg_add(, y, = NULL) y character scalar, of the operation (optional). add cg_asin Inverse Sine Calculate asin(). cg_asin(, = NULL) character scalar, of the operation (optional).

6 6 cg_asinh asin cg_asinh Inverse Hyperbolic Sine Calculate asinh(). cg_asinh(, = NULL) character scalar, of the operation (optional). asinh

7 cg_as_double 7 cg_as_double Coerce to a Numeric Vector Coerce to a one-dimensional numeric vector. cg_as_double(, = NULL) either a cg_node object or a numeric matri or array. character scalar, of the operation (optional). This function is identical to cg_as_numeric. as.double cg_as_numeric Coerce to a Numeric Vector Coerce to a one-dimensional numeric vector. cg_as_numeric(, = NULL) either a cg_node object or a numeric matri or array. character scalar, of the operation (optional).

8 8 cg_atan This function is identical to cg_as_double. as.numeric cg_atan Inverse Tangent Calculate atan(). cg_atan(, = NULL) character scalar, of the operation (optional). atan

9 cg_atanh 9 cg_atanh Inverse Hyperbolic Tangent Calculate atanh(). cg_atanh(, = NULL) character scalar, of the operation (optional). atanh cg_colsums Col Sums Calculate colsums(). cg_colsums(, = NULL) either a cg_node object or a numeric matri or array. character scalar, of the operation (optional).

10 10 cg_constant Function colsums is called without changing the default value of argument na.rm and dims. colsums cg_constant Add Constant Add a constant node to the active graph. cg_constant(value, = NULL) value numeric vector or array, value of the node. character scalar, of the node (optional). In case argument is missing, the node is added to the graph under an automatically generated. cg_node object. Constant nodes are ignored when differentiating a graph.

11 cg_cos 11 Eamples # Initialize a computational graph <- cg_graph() # Add a constant with value 1 and 'a' to the graph. a <- cg_constant(1, = "a") cg_cos Cosine Calculate cos(). cg_cos(, = NULL) character scalar, of the operation (optional). cos

12 12 cg_crossprod cg_cosh Hyperbolic Cosine Calculate cosh(). cg_cosh(, = NULL) character scalar, of the operation (optional). cosh cg_crossprod Matri Crossproduct Calculate crossprod(, y). cg_crossprod(, y = NULL, = NULL) y either a cg_node object or a numeric matri. either a cg_node object or a numeric matri (optional). character scalar, of the operation (optional).

13 cg_div 13 crossprod cg_div Divide Calculate / y. cg_div(, y, = NULL) y character scalar, of the operation (optional). divide

14 14 cg_function cg_ep Eponential Function Calculate ep(). cg_ep(, = NULL) character scalar, of the operation (optional). ep cg_function Create function Initialize a new function that can be used by operators in a graph. cg_function(def, grads = list()) def grads function, the definition of the function. list of functions, the gradient functions with respect to each input (optional).

15 cg_graph 15 cg_function object. If the function consumes any inputs, then the gradient function with respect to these inputs must be provided to argument grads. These gradients must be a function of each input s gradient and take as arguments the inputs of the function including argument val and grad. These latter two arguments evaluate to the value of the function and its gradient respectively at run-time. Eamples #' # Create a custom negation function f <- cg_function( def = function() -, grads = list(function(, val, grad) -grad) ) cg_graph Computational Graph Initialize a computational graph cg_graph() cg_graph object. The graph is automatically set to be the active graph.

16 16 cg_graph_gradients Eamples # Initialize a computational graph <- cg_graph() cg_graph_gradients Calculate Gradients Differentiate a graph with respect to a given target node by reverse automatic differentiation. cg_graph_gradients(graph, target, values = new.env(), inde = 1) graph target values inde cg_graph object, graph that is differentiated. cg_node object, node in the graph that is differentiated. d list or environment, values that are subsituted for the input nodes in the graph. numeric scalar, inde of the target node that is differentiated. Defaults to the first element. environment, the gradients of all ancestors of the node (including the target node itself) with respect to the target node. All nodes required to compute the target node must have a value, or their value must be able to be computed at run-time. The values of the nodes can be obtained by first evaluating function cg_graph_run. The values obtained by this function for the nodes can then be supplied to argument values. Currently, the cgraph package can only differentiate scalar target nodes. In case the value of target node is a vector or an array, argument inde can be used to specify which element of the vector or array is differentiated. The gradients of all ancestors of the node are returned. The gradients have the same shape as the values of the nodes.

17 cg_graph_run 17 Eamples # Initialize a computational graph <- cg_graph() # Add some parameters a <- cg_parameter(2, = "a") b <- cg_parameter(4, = "b") # Perform some operations on the parameters c <- cg_sin(a) + cg_cos(b) - cg_tan(a) # Differentiate the graph with respect to c grads <- cg_graph_gradients(, c, cg_graph_run(, c)) # Retrieve the gradient of c with respect to a grads$a cg_graph_run Evaluate the Graph Evaluate a given target node in a graph. cg_graph_run(graph, target, values = new.env()) graph target values cg_graph object, graph that is evaluated. cg_node object, node in the graph that is evaluated. d list or environment, values that are subsituted for the input nodes in the graph. environment, the value of the node including the value of all ancestors of the node in the graph. All nodes required to compute the target node must have a value or their value must be able to be computed at run-time. Argument values can be used to substitute values for input nodes that do not have a value. Only those nodes needed to compute the node are evaluated and their values are returned.

18 18 cg_input Eamples # Initialize a computational graph <- cg_graph() # Add an input a <- cg_input( = "a") # Square the input (i.e. b = a^2) b <- cg_pow(a, 2, = "b") # Evaluate b at a = 2 values <- cg_graph_run(, b, list(a = 2)) # Retrieve the value of b values$b cg_input Add Input Add an input node to the active graph. cg_input( = NULL) character scalar, of the node (optional). In case argument is missing, the node is added to the graph under an automatically generated. cg_node object. Inputs cannot be assigned a fied value but behave as placeholders. s can be assigned to inputs when evaluating or differentiating a graph (see cg_graph_run and cg_graph_gradients for more details).

19 cg_linear 19 Eamples # Initialize a computational graph <- cg_graph() # Add a parameter with 'a' to the graph. a <- cg_input( = "a") cg_linear Linear Transformation Calculate %*% y + c(z). cg_linear(, y, z, = NULL) y z either a cg_node object or a numeric matri. either a cg_node object or a numeric matri. either a cg_node object or a numeric vector. character scalar, of the operation (optional). This function is equivalent to cg_matmul(, y) + cg_as_numeric(z).

20 20 cg_log10 cg_ln Natural Logarithm Calculate log(). cg_ln(, = NULL) character scalar, of the operation (optional). log cg_log10 Logarithm Base 10 Calculate log10(). cg_log10(, = NULL) character scalar, of the operation (optional).

21 cg_log2 21 log10 cg_log2 Logarithm Base 2 Calculate log2(). cg_log2(, = NULL) character scalar, of the operation (optional). log2

22 22 cg_ma cg_matmul Matri Multiplication Calculate %*% y. cg_matmul(, y, = NULL) y either a cg_node object or a numeric matri. either a cg_node object or a numeric matri. character scalar, of the operation (optional). matmult cg_ma Maima Calculate ma(). cg_ma(, = NULL) character scalar, of the operation (optional).

23 cg_mean 23 Function ma is called without changing the default value of argument na.rm. ma cg_mean Arithmetic Mean Calculate mean(). cg_mean(, = NULL) character scalar, of the operation (optional). Function mean is called without changing the default value of argument trim and na.rm. mean

24 24 cg_mul cg_min Minima Calculate min(). cg_min(, = NULL) character scalar, of the operation (optional). Function min is called without changing the default value of argument na.rm. min cg_mul Multiply Calculate * y. cg_mul(, y, = NULL)

25 cg_neg 25 y character scalar, of the operation (optional). multiply cg_neg Negative Calculate -. cg_neg(, = NULL) character scalar, of the operation (optional). negative

26 26 cg_operator cg_operator Add Operator Add an operation node to the active graph. cg_operator(fun, inputs, = NULL) fun inputs cg_function object, function evaluated by the node. list, the nodes that are consumed by the operation. character scalar, of the node (optional). In case argument is missing, the node is added to the graph under an automatically generated. cg_node object. Any objects that are supplied to argument inputs that are not cg_node objects are implicitly converted to cg_constant objects. Eamples # Initialize a computational graph <- cg_graph() # Create a custom negation function f <- cg_function( def = function() -, grads = list(function(, val, grad) -grad) ) # Add a an operator with the negation function to the graph. a <- cg_operator(f, list(10), = "a")

27 cg_parameter 27 cg_parameter Add Parameter Add a parameter node to the active graph. cg_parameter(value, = NULL) value numeric vector or array, value of the node. character scalar, of the node (optional). In case argument is missing, the node is added to the graph under an automatically generated. cg_node object. Parameters are assumed to be subject to some optimization process. change over time. Hence, their value might Eamples # Initialize a computational graph <- cg_graph() # Add a parameter with value 1 and 'a' to the graph. a <- cg_parameter(1, = "a")

28 28 cg_pmin cg_pma Parallel Maima Calculate pma(, y). cg_pma(, y, = NULL) y character scalar, of the operation (optional). Function pma is called without changing the default value of argument na.rm. pma cg_pmin Parallel Minima Calculate pmin(, y). cg_pmin(, y, = NULL)

29 cg_pos 29 y character scalar, of the operation (optional). Function pmin is called without changing the default value of argument na.rm. pmin cg_pos Positive Calculate. cg_pos(, = NULL) character scalar, of the operation (optional). positive

30 30 cg_prod cg_pow Power Calculate ^ y. cg_pow(, y, = NULL) y character scalar, of the operation (optional). power cg_prod Product of Vector Elements Calculate prod(). cg_prod(, = NULL) character scalar, of the operation (optional).

31 cg_rowsums 31 In contrast to the base prod function, this function only accepts a single argument. Function prod is called changing the default value of argument na.rm. prod cg_rowsums Row Sums Calculate rowsums(). cg_rowsums(, = NULL) either a cg_node object or a numeric matri or array. character scalar, of the operation (optional). Function rowsums is called without changing the default value of argument na.rm and dims. rowsums

32 32 cg_session_set_graph cg_session_graph Get Active Graph Get the graph that is currently active. cg_session_graph() cg_graph object, the graph that is currently active. Eamples # Initialize a computational graph <- cg_graph() # Retrieve the graph from the session cg_session_graph() cg_session_set_graph Change Active Graph Set a graph to be the active graph. cg_session_set_graph(graph) graph cg_graph object, the graph that is activated. none.

33 cg_sigmoid 33 Any nodes that are created are automatically added to the active graph. This also applies to operations that are created by overloaded S3 functions that do not follow the cg_<> naming convention (such as primitive infli functions + and - ). Only one graph can be active at a time. The active graph can be changed by calling this function on another cg_graph object. Eamples # Initialize a computational graph <- cg_graph() # Initialize another computational graph. It becomes the active graph. y <- cg_graph() # Set to be the active graph cg_session_set_graph() cg_sigmoid Sigmoid Calculate 1 / (1 + ep(-)). cg_sigmoid(, = NULL) character scalar, of the operation (optional).

34 34 cg_sinh cg_sin Sine Calculate sin(). cg_sin(, = NULL) character scalar, of the operation (optional). sin cg_sinh Hyperbolic Sine Calculate sinh(). cg_sinh(, = NULL) character scalar, of the operation (optional).

35 cg_sqrt 35 sinh cg_sqrt Square Root Calculate sqrt(). cg_sqrt(, = NULL) character scalar, of the operation (optional). sqrt

36 36 cg_sum cg_sub Subtract Calculate - y. cg_sub(, y, = NULL) y character scalar, of the operation (optional). subtract cg_sum Sum of Vector Elements Calculate sum(). cg_sum(, = NULL) character scalar, of the operation (optional).

37 cg_t 37 In contrast to the base sum function, this function only accepts a single argument. Function sum is called without changing the default value of argument na.rm. sum cg_t Matri Transpose Perform t(). cg_t(, = NULL) either a cg_node object or a numeric matri. character scalar, of the operation (optional). t

38 38 cg_tanh cg_tan Tangent Calculate tan(). cg_tan(, = NULL) character scalar, of the operation (optional). tan cg_tanh Hyperbolic Tangent Calculate tanh(). cg_tanh(, = NULL) character scalar, of the operation (optional).

39 cg_tcrossprod 39 tanh cg_tcrossprod Transpose Matri Crossproduct Calculate tcrossprod(, y). cg_tcrossprod(, y = NULL, = NULL) y either a cg_node object or a numeric matri. either a cg_node object or a numeric matri (optional). character scalar, of the operation (optional). tcrossprod

40 Inde abs, 3 acos, 4 acosh, 4 add, 5 as.double, 7 as.numeric, 8 asin, 6 asinh, 6 atan, 8 atanh, 9 cg_abs, 3 cg_acos, 3 cg_acosh, 4 cg_add, 5 cg_as_double, 7 cg_as_numeric, 7 cg_asin, 5 cg_asinh, 6 cg_atan, 8 cg_atanh, 9 cg_colsums, 9 cg_constant, 10 cg_cos, 11 cg_cosh, 12 cg_crossprod, 12 cg_div, 13 cg_ep, 14 cg_function, 14 cg_graph, 15 cg_graph_gradients, 16, 18 cg_graph_run, 16, 17, 18 cg_input, 18 cg_linear, 19 cg_ln, 20 cg_log10, 20 cg_log2, 21 cg_matmul, 22 cg_ma, 22 cg_mean, 23 cg_min, 24 cg_mul, 24 cg_neg, 25 cg_operator, 26 cg_parameter, 27 cg_pma, 28 cg_pmin, 28 cg_pos, 29 cg_pow, 30 cg_prod, 30 cg_rowsums, 31 cg_session_graph, 32 cg_session_set_graph, 32 cg_sigmoid, 33 cg_sin, 34 cg_sinh, 34 cg_sqrt, 35 cg_sub, 36 cg_sum, 36 cg_t, 37 cg_tan, 38 cg_tanh, 38 cg_tcrossprod, 39 colsums, 10 cos, 11 cosh, 12 crossprod, 13 divide, 13 ep, 14 log, 20 log10, 21 log2, 21 matmult, 22 ma, 23 mean, 23 min, 24 40

41 INDEX 41 multiply, 25 negative, 25 pma, 28 pmin, 29 positive, 29 power, 30 prod, 31 rowsums, 31 sin, 34 sinh, 35 sqrt, 35 subtract, 36 sum, 37 t, 37 tan, 38 tanh, 39 tcrossprod, 39