Bijectors.jl Development

Development workflow and guidelines for Bijectors.jl, a Julia package implementing normalizing flows and constrained random variable transformations for probability distributions.

Overview

Bijectors.jl provides an interface for transforming probability distributions from Distributions.jl, implementing many transformations needed for probabilistic programming. It is heavily used in the Turing.jl probabilistic programming language.

Instructions

1. Initial Setup

Before starting development, install dependencies:

```bash

julia --project=. -e "using Pkg; Pkg.instantiate()"

```

Verify package loads correctly:

```bash

julia --project=. -e "using Bijectors; println(\"Package loaded successfully\")"

```

**IMPORTANT**: Installation takes approximately 30 seconds. Never cancel this process.

2. Running Tests

#### Interface Tests (Core Functionality)

Run interface tests to verify core functionality:

```bash

julia --project=. -e "ENV[\"GROUP\"] = \"Interface\"; using Pkg; Pkg.test()"

```

#### Automatic Differentiation Tests

Test specific AD backend:

```bash

julia --project=. -e "ENV[\"GROUP\"] = \"AD\"; ENV[\"AD\"] = \"ForwardDiff\"; using Pkg; Pkg.test()"

```

#### Full Test Suite

Run all tests:

```bash

julia --project=. -e "using Pkg; Pkg.test()"

```

3. Code Formatting

Install formatter (one-time):

```bash

julia --project=. -e "using Pkg; Pkg.add(\"JuliaFormatter\")"

```

Format code before committing:

```bash

julia --project=. -e "using JuliaFormatter; format(\".\")"

```

4. Building Documentation

Generate documentation:

```bash

julia --project=docs -e "using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate(); include(\"docs/make.jl\")"

```

5. Validation Testing

After making changes, always test basic functionality:

```julia

using Bijectors, Distributions

Test basic bijector for LogNormal

d = LogNormal()

b = bijector(d)

x = 1.0

y = b(x) # Should return 0.0

Test inverse transformation

x_reconstructed = inverse(b)(y) # Should return 1.0

Test log absolute determinant of Jacobian

logjac = logabsdetjac(b, x)

Test combined transformation

z, logabsdet = with_logabsdet_jacobian(b, x)

```

6. Pre-Commit Checklist

Before committing changes:

1. **Run Interface tests**: Required for all changes

2. **Run code formatter**: Ensure consistent style

3. **Test basic functionality**: Run validation scenarios above

4. **Test AD changes**: If modifying AD-related code, run specific AD backend tests

7. Repository Structure

Key directories and files:

```

src/

├── Bijectors.jl # Main module

├── interface.jl # Core interface definitions

├── chainrules.jl # AD integration

└── bijectors/ # Individual bijector implementations

test/

├── runtests.jl # Main test runner

├── ad/ # AD-specific tests

└── bijectors/ # Bijector-specific tests

docs/ # Documentation

ext/ # Package extensions for AD backends

```

8. Common Issues

9. CI Workflows

The repository uses GitHub Actions for:

Constraints

Examples

Basic Bijector Usage

```julia

using Bijectors, Distributions

Create a LogNormal distribution

d = LogNormal(0, 1)

Get the bijector

b = bijector(d)

Transform from unconstrained to constrained space

x = 0.5

y = b(x)

Inverse transformation

x_back = inverse(b)(y)

Compute log absolute determinant of Jacobian

logdet = logabsdetjac(b, x)

```

Testing Custom Bijector

```julia

Define a custom bijector

struct MyBijector <: Bijector end

Implement required methods

(b::MyBijector)(x) = exp(x)

inverse(b::MyBijector) = InverseBijector(b)

logabsdetjac(b::MyBijector, x) = x

Test it

b = MyBijector()

@assert b(0.0) ≈ 1.0

@assert inverse(b)(1.0) ≈ 0.0

```