diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml new file mode 100644 index 0000000..69929b8 --- /dev/null +++ b/.github/workflows/Documentation.yml @@ -0,0 +1,28 @@ +name: Documentation + +on: + push: + branches: + - main + tags: '*' + pull_request: + +jobs: + build: + permissions: + contents: write + statuses: write + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: julia-actions/setup-julia@v1 + with: + version: '1' + - uses: julia-actions/cache@v1 + - name: Install dependencies + run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()' + - name: Build and deploy + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token + DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key + run: julia --project=docs/ docs/make.jl \ No newline at end of file diff --git a/.gitignore b/.gitignore index b067edd..7465bf7 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ -/Manifest.toml +Manifest.toml +/docs/build/ \ No newline at end of file diff --git a/README.md b/README.md index c067efb..26ad8e8 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,32 @@ # ADTypes.jl: Multi-Valued Logic for Automatic Differentiation Choices -[![Build Status](https://github.com/Vaibhavdixit02/ADTypes.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/Vaibhavdixit02/ADTypes.jl/actions/workflows/CI.yml?query=branch%3Amain) - -ADTypes.jl is a common system for implementing multi-valued logic for choosing which -automatic differentiation library to use. - -## Which libraries are supported? - -Just run the following code in a Julia REPL to find out: - -```julia -julia> using ADTypes - -julia> names(ADTypes) -16-element Vector{Symbol}: - :ADTypes - :AutoChainRules - :AutoEnzyme - :AutoFiniteDiff - :AutoFiniteDifferences - :AutoForwardDiff - :AutoModelingToolkit - :AutoPolyesterForwardDiff - :AutoReverseDiff - :AutoSparseFiniteDiff - :AutoSparseForwardDiff - :AutoSparsePolyesterForwardDiff - :AutoSparseReverseDiff - :AutoSparseZygote - :AutoTracker - :AutoZygote -``` - -Use the help mode of the Julia REPL to find out more about a specific library. - -## Why Should Packages Adopt This? - -The current standard is to have a keyword argument with `autodiff = true` or `autodiff = false`. -However, boolean logic is not sufficient to be able to do all of the choices that are -required. For example for forward-mode AD there is ForwardDiff vs Enzyme, and thus `true` -is ambgiuous. As libraries begin to support more and more of these autodiff mechanisms -for their trade-offs, every library will have their own version of `ChooseForwardDiff()` -etc. which would be a mess. Hence ADTypes.jl giving a single set of shared types for this. -`ADTypes.AutoForwardDiff()` is the way to do it. - -## Why are they types instead of enums? Or EnumX? - -If they were enums then they would not be dispatch type-level information. This is needed -for the internals of many of the packages to be type-stable because the choice of `config` -type is different per package, i.e. what needs to be cached in order to use everything in -a non-allocating manner. - -## My AD Package is Missing? - -Sure, give a PR to add it. +[![Docs stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://SciML.github.io/ADTypes.jl/stable/) +[![Docs dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://SciML.github.io/ADTypes.jl/dev/) +[![Build Status](https://github.com/SciML/ADTypes.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/SciML/ADTypes.jl/actions/workflows/CI.yml?query=branch%3Amain) + +ADTypes.jl is a multi-valued logic system specifying the choice of an automatic differentiation (AD) library and its parameters. + +## Which AD libraries are supported? + +See the API reference in the documentation. + +## Why should packages adopt this standard? + +A common practice is the use of a boolean keyword argument like `autodiff = true/false`. +However, boolean logic is not precise enough for all the choices required. +For instance, forward mode AD is implemented by both ForwardDiff and Enzyme, which makes `autodiff = true` ambiguous. +Something like `ChooseForwardDiff()` is thus required, possibly with additional parameters depending on the library. + +The risk is that every package developer might develop their own version of `ChooseForwardDiff()`, which would ruin interoperability. +This is why ADTypes.jl provides a single set of shared types for this task, as an extremely lightweight dependency. +Wonder no more: `ADTypes.AutoForwardDiff()` is the way to go. + +## Why define types instead of enums? + +If we used enums, they would not contain type-level information useful for dispatch. +This is needed by many AD libraries to ensure type stability. +Notably, the choice of config or cache type is different with each AD, so we must know statically which AD library is chosen. + +## Why is this AD package missing? + +Feel free to open a pull request adding it. diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..07013e9 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,6 @@ +[deps] +ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b" +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" + +[compat] +Documenter = "1.3" \ No newline at end of file diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..bc8d672 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,12 @@ +using Documenter +using ADTypes + +makedocs( + sitename = "ADTypes", + format = Documenter.HTML(), + modules = [ADTypes] +) + +deploydocs( + repo = "https://github.com/SciML/ADTypes.jl.git" +) diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..23b06a0 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,22 @@ +```@meta +CurrentModule = ADTypes +CollapsedDocStrings = true +``` + +# ADTypes.jl + +Documentation for [ADTypes.jl](https://github.com/SciML/ADTypes.jl/). + +## Public + +```@autodocs +Modules = [ADTypes] +Private = false +``` + +## Internal + +```@autodocs +Modules = [ADTypes] +Public = false +```