Initial package implementation

.codecov.yml

@@ -0,0 +1 @@
+# comment: false

.github/workflows/TagBot.yml

@@ -0,0 +1,15 @@
+name: TagBot
+on:
+  issue_comment:
+    types:
+      - created
+  workflow_dispatch:
+jobs:
+  TagBot:
+    if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: JuliaRegistries/TagBot@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+      - dev
+      - 'releases/**'
+    tags: '*'
+  pull_request:
+  release:
+
+jobs:
+  test:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.version == 'nightly' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1.0'
+          - '1'
+          - 'nightly'
+        os:
+          - ubuntu-latest
+          - macOS-latest
+          - windows-latest
+        arch:
+          - x64
+          - x86
+        exclude:
+          # 32-bit Julia binaries are not available on macOS
+          - os: macOS-latest
+            arch: x86
+          - os: windows-latest
+            arch: x86
+          - version: nightly
+            arch: x86
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - name: Cache artifacts
+        uses: actions/cache@v2
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - uses: julia-actions/julia-buildpkg@latest
+        env:
+          PYTHON: 'Conda'
+      - uses: julia-actions/julia-runtest@latest
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v1
+        with:
+          file: lcov.info
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      - name: Cache artifacts
+        uses: actions/cache@v2
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/docs/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - uses: julia-actions/julia-buildpkg@latest
+        env:
+          PYTHON: 'Conda'
+      - uses: julia-actions/julia-docdeploy@latest
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Needed due to https://github.com/JuliaDocs/Documenter.jl/issues/1177
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+          GKSwstype: 'nul'

.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+*.jl.cov
+*.jl.*.cov
+*.jl.mem
+.ipynb_checkpoints
+.vscode
+Manifest.toml

LICENSE.md

@@ -0,0 +1,24 @@
+The ChangesOfVariables.jl package is licensed under the MIT "Expat" License:
+
+> Copyright (c) 2021:
+>
+>    Oliver Schulz <[email protected]>
+> 
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+> 
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+> 
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+> 

Project.toml

@@ -0,0 +1,16 @@
+name = "ChangesOfVariables"
+uuid = "9e997f8a-9a97-42d5-a9f1-ce6bfc15e2c0"
+version = "0.1.0"
+
+[deps]
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+
+[compat]
+julia = "1"
+
+[extras]
+ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["ForwardDiff", "Test"]

README.md

@@ -0,0 +1,20 @@
+# ChangesOfVariables.jl
+
+[![Documentation for stable version](https://img.shields.io/badge/docs-stable-blue.svg)](https://oschulz.github.io/ChangesOfVariables.jl/stable)
+[![Documentation for development version](https://img.shields.io/badge/docs-dev-blue.svg)](https://oschulz.github.io/ChangesOfVariables.jl/dev)
+[![License](http://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](LICENSE.md)
+[![Build Status](https://github.com/oschulz/ChangesOfVariables.jl/workflows/CI/badge.svg?branch=master)](https://github.com/oschulz/ChangesOfVariables.jl/actions?query=workflow%3ACI)
+[![Codecov](https://codecov.io/gh/oschulz/ChangesOfVariables.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/oschulz/ChangesOfVariables.jl)
+
+
+ChangesOfVariables.jl defines functionality to calculate volume element
+changes for functions that perform a change of variables (like coordinate
+transformations).
+
+`ChangesOfVariables` is a very lightweight package and has no dependencies
+beyond `Base` and `LinearAlgebra`.
+
+## Documentation
+
+* [Documentation for stable version](https://oschulz.github.io/ChangesOfVariables.jl/stable)
+* [Documentation for development version](https://oschulz.github.io/ChangesOfVariables.jl/dev)

docs/.gitignore

@@ -0,0 +1,2 @@
+build/
+site/

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
+
+[compat]
+Documenter = "~0.27"

docs/make.jl

@@ -0,0 +1,31 @@
+# Use
+#
+#     DOCUMENTER_DEBUG=true julia --color=yes make.jl local [nonstrict] [fixdoctests]
+#
+# for local builds.
+
+using Documenter
+using ChangesOfVariables
+
+makedocs(
+    sitename = "ChangesOfVariables",
+    modules = [ChangesOfVariables],
+    format = Documenter.HTML(
+        prettyurls = !("local" in ARGS),
+        canonical = "https://oschulz.github.io/ChangesOfVariables.jl/stable/"
+    ),
+    pages = [
+        "Home" => "index.md",
+        "API" => "api.md",
+        "LICENSE" => "LICENSE.md",
+    ],
+    doctest = ("fixdoctests" in ARGS) ? :fix : true,
+    linkcheck = !("nonstrict" in ARGS),
+    strict = !("nonstrict" in ARGS),
+)
+
+deploydocs(
+    repo = "github.com/oschulz/ChangesOfVariables.jl.git",
+    forcepush = true,
+    push_preview = true,
+)

docs/src/LICENSE.md

@@ -0,0 +1,6 @@
+# LICENSE
+
+```@eval
+using Markdown
+Markdown.parse_file(joinpath(@__DIR__, "..", "..", "LICENSE.md"))
+```

docs/src/api.md

@@ -0,0 +1,32 @@
+# API
+
+```@meta
+DocTestSetup  = quote
+    using ChangesOfVariables
+end
+```
+
+## Modules
+
+```@index
+Order = [:module]
+```
+
+## Types and constants
+
+```@index
+Order = [:type, :constant]
+```
+
+## Functions and macros
+
+```@index
+Order = [:macro, :function]
+```
+
+# Documentation
+
+```@autodocs
+Modules = [ChangesOfVariables]
+Order = [:module, :type, :constant, :macro, :function]
+```

docs/src/index.md

@@ -0,0 +1,7 @@
+# ChangesOfVariables.jl
+
+This package defines the function [`with_logabsdet_jacobian`](@ref). `(y, ladj) = with_logabsdet_jacobian(f, x)` computes both the transformed value of `x` under the transformation `f` and the logarithm of the [volume element](https://en.wikipedia.org/wiki/Volume_element).
+
+`with_logabsdet_jacobian` supports mapped/broadcasted functions (via `Base.Fix1`) and (on Julia >=v1.6) function composition.
+
+Implementations of `with_logabsdet_jacobian(f)` for `identity`, `inv`, `adjoint` and `transpose` as well as for `exp`, `log`, `exp2`, `log2`, `exp10`, `log10`, `expm1` and `log1p` are included.

src/ChangesOfVariables.jl

@@ -0,0 +1,18 @@
+# This file is a part of ChangesOfVariables.jl, licensed under the MIT License (MIT).
+
+__precompile__(true)
+
+"""
+    ChangesOfVariables
+
+Lightweight package that defines functionality to calculate volume element
+changes for functions that perform a change of variables (like coordinate
+transformations).
+"""
+module ChangesOfVariables
+
+using LinearAlgebra
+
+include("with_ladj.jl")
+
+end # module

src/with_ladj.jl

@@ -0,0 +1,91 @@
+# This file is a part of ChangesOfVariables.jl, licensed under the MIT License (MIT).
+
+"""
+    with_logabsdet_jacobian(f, x)
+
+Computes both the transformed value of `x` under the transformation `f` and
+the logarithm of the [volume element](https://en.wikipedia.org/wiki/Volume_element).
+
+For `(y, ladj) = with_logabsdet_jacobian(f, x)`, the following must hold true:
+
+* `y == f(x)`
+* `ladj` is the `log(abs(det(jacobian(f, x))))`
+
+`with_logabsdet_jacobian` comes with support for broadcasted/mapped functions
+(via `Base.Fix1`) and (Julia >=v1.6 only) `ComposedFunction`.
+
+Example:
+
+```julia
+foo(x) = inv(exp(-x) + 1)
+
+function ChangesOfVariables.with_logabsdet_jacobian(::typeof(foo), x)
+    y = foo(x)
+    ladj = -x + 2 * log(y)
+    (y, ladj)
+end
+
+x = 4.2
+y, ladj_y = with_logabsdet_jacobian(foo, x)
+
+X = rand(10)
+broadcasted_foo = Base.Fix1(broadcast, foo)
+Y, ladj_Y = with_logabsdet_jacobian(broadcasted_foo, X)
+
+# Requires Julia >= v1.6:
+z, ladj_z = with_logabsdet_jacobian(log ∘ foo, x)
+z == log(foo(x))
+ladj_z == ladj_y + with_logabsdet_jacobian(log, y)[2]
+```
+"""
+function with_logabsdet_jacobian end
+export with_logabsdet_jacobian
+
+@static if VERSION >= v"1.6"
+    function with_logabsdet_jacobian(f::Base.ComposedFunction, x)
+        y_inner, ladj_inner = with_logabsdet_jacobian(f.inner, x)
+        y, ladj_outer = with_logabsdet_jacobian(f.outer, y_inner)
+        (y, ladj_inner + ladj_outer)
+    end
+end
+
+
+@inline _get_y(y_with_ladj::NTuple{2,Any,}) = y_with_ladj[1]
+@inline _get_ladj(y_with_ladj::NTuple{2,Any}) = y_with_ladj[2]
+
+_with_ladj_on_mapped(map_or_bc::Function, y_with_ladj::Tuple{Any,Real}) = y_with_ladj
+
+function _with_ladj_on_mapped(map_or_bc::Function, y_with_ladj)
+    y = map_or_bc(_get_y, y_with_ladj)
+    ladj = sum(map_or_bc(_get_ladj, y_with_ladj))
+    (y, ladj)
+end
+
+function with_logabsdet_jacobian(mapped_f::Base.Fix1{<:Union{typeof(map),typeof(broadcast)}}, X)
+    map_or_bc = mapped_f.f
+    f = mapped_f.x
+    y_with_ladj = map_or_bc(Base.Fix1(with_logabsdet_jacobian, f), X)
+    _with_ladj_on_mapped(map_or_bc, y_with_ladj)
+end
+
+
+with_logabsdet_jacobian(::typeof(identity), x) = (identity(x), zero(eltype(x)))
+
+_ndof(::Type{<:Real}) = 1
+_ndof(::Type{<:Complex}) = 2
+with_logabsdet_jacobian(::typeof(inv), x::Number) = (inv(x), -2 * _ndof(typeof(x)) * log(abs(x)))
+with_logabsdet_jacobian(::typeof(inv), A::AbstractMatrix) = (inv(A), -2 * _ndof(eltype(A)) * size(A, 1) * logabsdet(A)[1])
+
+with_logabsdet_jacobian(::typeof(adjoint), x) = (adjoint(x), zero(eltype(x)))
+with_logabsdet_jacobian(::typeof(transpose), x) = (transpose(x), zero(eltype(x)))
+
+
+with_logabsdet_jacobian(::typeof(exp), x) = (exp(x), x)
+with_logabsdet_jacobian(::typeof(exp2), x) = (exp2(x), log(2) * x + log(log(oftype(x, 2))))
+with_logabsdet_jacobian(::typeof(exp10), x) = (exp10(x), log(10) * x + log(log(oftype(x, 10))))
+with_logabsdet_jacobian(::typeof(expm1), x) = (expm1(x), x)
+
+with_logabsdet_jacobian(::typeof(log), x) = (y = log(x); (y, -y))
+with_logabsdet_jacobian(::typeof(log2), x) = (y = log2(x); (y, -log(2) * y - log(log(oftype(x, 2)))))
+with_logabsdet_jacobian(::typeof(log10), x) = (y = log10(x); (y, -log(10) * y - log(log(oftype(x, 10)))))
+with_logabsdet_jacobian(::typeof(log1p), x) = (y = log1p(x); (y, -y))

test/runtests.jl

@@ -0,0 +1,7 @@
+# This file is a part of ChangesOfVariables.jl, licensed under the MIT License (MIT).
+
+import Test
+
+Test.@testset "Package ChangesOfVariables" begin
+    include("test_with_ladj.jl")
+end # testset