-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
149 lines (104 loc) · 4.78 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
# autodiffr for Automatic Differentiation in R through Julia
[](https://travis-ci.org/Non-Contradiction/autodiffr)
[](https://ci.appveyor.com/project/Non-Contradiction/autodiffr)
<!--
[](https://cran.r-project.org/package=JuliaCall)
[](https://cran.r-project.org/package=JuliaCall)
[](https://cran.r-project.org/package=JuliaCall)
-->
Package `autodiffr` provides an `R` wrapper for `Julia` packages [`ForwardDiff.jl`](https://github.com/JuliaDiff/ForwardDiff.jl) and [`ReverseDiff.jl`](https://github.com/JuliaDiff/ReverseDiff.jl) through [`JuliaCall`](https://github.com/Non-Contradiction/JuliaCall) to do **automatic differentiation** for native `R` functions.
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
## Installation
[`Julia`](https://julialang.org/) is needed to use `autodiffr`. You can download a generic `Julia` binary from
<https://julialang.org/downloads/> and add it to the path.
Pakcage `autodiffr` is not on CRAN yet. You can get the development version of `autodiffr` by
```{r eval=FALSE}
devtools::install_github("Non-Contradiction/autodiffr")
```
**Important**: Note that currently `Julia` v0.6.x, v0.7.0 and v1.0 are all supported by `autodiffr`, but to use `autodiffr` with `Julia` v0.7/1.0,
you need to get the development version of `JuliaCall` by:
```{r eval=FALSE}
devtools::install_github("Non-Contradiction/JuliaCall")
```
## Basic Usage
```{r}
library(autodiffr)
## Do initial setup
ad_setup()
## If you want to use a julia at a specific location, you could do the following:
## ad_setup(JULIA_HOME = "the folder that contains julia binary"),
## or you can set JULIA_HOME in command line environment or use `options(...)`
## Define a target function with vector input and scalar output
f <- function(x) sum(x^2L)
## Calculate gradient of f at [2,3] by
ad_grad(f, c(2, 3)) ## deriv(f, c(2, 3))
## Get a gradient function g
g <- makeGradFunc(f)
## Evaluate the gradient function g at [2,3]
g(c(2, 3))
## Calculate hessian of f at [2,3] by
ad_hessian(f, c(2, 3))
## Get a hessian function h
h <- makeHessianFunc(f)
## Evaluate the hessian function h at [2,3]
h(c(2, 3))
## Define a target function with vector input and vector output
f <- function(x) x^2
## Calculate jacobian of f at [2,3] by
ad_jacobian(f, c(2, 3))
## Get a jacobian function j
j <- makeJacobianFunc(f)
## Evaluate the gradient function j at [2,3]
j(c(2, 3))
```
## Advanced Usage
### Functions with Multiple Arguments
```{r}
## Define a target function with mulitple arguments
f <- function(a = 1, b = 2, c = 3) a * b ^ 2 * c ^ 3
## Calculate gradient/derivative of f at a = 2, when b = c = 1 by
ad_grad(f, 2, b = 1, c = 1) ## deriv(f, 2, b = 1, c = 1)
## Get a gradient/derivative function g w.r.t a when b = c = 1 by
g <- makeGradFunc(f, b = 1, c = 1)
## Evaluate the gradient/derivative function g at a = 2
g(2)
## Calculate gradient/derivative of f at a = 2, b = 3, when c = 1 by
ad_grad(f, list(a = 2, b = 3), c = 1)
## Get a gradient/derivative function g w.r.t a and b when c = 1 by
g <- makeGradFunc(f, c = 1)
## Evaluate the gradient/derivative function g at a = 2, b = 3
g(list(a = 2, b = 3))
```
## Trouble Shooting and Way to Get Help
### Julia is not found
Make sure the `Julia` installation is correct.
`autodiffr` is able to find `Julia` on PATH,
and there are three ways for `autodiffr` to find `Julia` not on PATH.
- Use `ad_setup(JULIA_HOME = "the folder that contains julia binary")`
- Use `options(JULIA_HOME = "the folder that contains julia binary")`
- Set `JULIA_HOME` in command line environment.
### How to Get Help
- The GitHub Pages for this repository host the documentation for the development
version of `autodiffr`: <https://non-contradiction.github.io/autodiffr/>.
- And you are more than welcome to contact me about `autodiffr`
at <[email protected]> or <[email protected]>.
## Suggestion and Issue Reporting
`autodiffr` is under active development now.
Any suggestion or issue reporting is welcome!
You may report it using the link: <https://github.com/Non-Contradiction/autodiffr/issues/new>.
Or email me at <[email protected]> or <[email protected]>.
## Acknowledgement
The project `autodiffr` was a Google Summer of Code
(GSoC) 2018 project for the "R Project for statistical computing" and
with mentors John Nash and Hans W Borchers.
Thanks a lot!