Bijectors.jl Development

Expert assistant for developing Bijectors.jl, a Julia package implementing normalising flows and constrained random variable transformations for probability distributions.

Package Overview

Bijectors.jl provides an interface for transforming distributions from Distributions.jl and implements many transformations needed for probabilistic programming, particularly in Turing.jl.

Quick Setup and Build

When setting up the development environment:

1. Install dependencies (takes ~30 seconds - never cancel):

```bash

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

```

2. Verify package loads correctly:

```bash

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

```

Running Tests

**CRITICAL**: Test commands can take significant time. Never cancel them prematurely and set appropriate timeouts.

Interface Tests (Core Functionality)

Takes ~7.5 minutes, timeout should be 30+ minutes:

```bash

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

```

AD Tests (Specific Backend)

Takes ~1.5 minutes, timeout should be 10+ minutes:

```bash

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

```

Full Test Suite

Takes 20+ minutes, timeout should be 60+ minutes. Note: Some Enzyme tests may fail due to system compatibility - this is expected:

```bash

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

```

Code Formatting

Before committing changes, always format the code:

1. Install formatter (one-time setup, takes ~45 seconds):

```bash

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

```

2. Format code:

```bash

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

```

Documentation

Build documentation (takes ~47 seconds, timeout 5+ minutes):

```bash

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

```

Validation Scenarios

Always test basic functionality after making changes:

```julia

using Bijectors, Distributions

Test 1: Basic bijector for LogNormal

d = LogNormal()

b = bijector(d)

x = 1.0

y = b(x) # Should return 0.0

Test 2: Inverse transformation

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

Test 3: Log absolute determinant of Jacobian

logjac = logabsdetjac(b, x)

Test 4: Combined transformation

z, logabsdet = with_logabsdet_jacobian(b, x)

```

Pre-Commit Checklist

Before committing any changes:

1. ✅ Run Interface tests: `ENV["GROUP"] = "Interface"; Pkg.test()`

2. ✅ Run code formatter: `using JuliaFormatter; format(".")`

3. ✅ Test basic functionality scenarios (see validation scenarios above)

4. ✅ If changing AD-related code, run specific AD backend tests

5. ✅ Build package successfully

6. ✅ Verify inverse transformations work correctly

7. ✅ Check log absolute determinant Jacobian calculations

Repository Structure

```

.

├── Project.toml # Package definition and dependencies

├── src/ # Main source code

│ ├── Bijectors.jl # Main module

│ ├── interface.jl # Core interface definitions

│ ├── chainrules.jl # AD integration

│ └── bijectors/ # Individual bijector implementations

├── test/ # Test suite

│ ├── runtests.jl # Main test runner

│ ├── ad/ # AD-specific tests

│ └── bijectors/ # Bijector-specific tests

├── docs/ # Documentation

├── ext/ # Package extensions for AD backends

└── .github/workflows/ # CI configuration

```

Test Groups and Timing

Common Issues

CI Workflows

The package uses several CI workflows:

Key Dependencies

Core dependencies include:

Extensions provide AD backend integration:

Important Notes