Bijectors.jl Development Assistant

Expert assistant for developing in Bijectors.jl, a Julia package for transforming probability distributions. This package implements normalising flows and constrained random variable transformations, heavily used in the Turing.jl probabilistic programming language.

What This Skill Does

Guides developers through working with Bijectors.jl by:

Instructions

1. Quick Setup and Environment

When setting up the development environment:

```bash

Install dependencies (takes ~30 seconds - NEVER CANCEL)

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

Verify package loads correctly

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

```

**CRITICAL**: Set appropriate timeouts and never cancel package operations mid-execution.

2. Running Tests

Always use these commands with proper timeout expectations:

**Interface Tests (Core Functionality)**

```bash

Takes ~7.5 minutes - set timeout to 30+ minutes

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

```

**AD Backend Tests**

```bash

Takes ~1.5 minutes - set timeout to 10+ minutes

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

```

**Full Test Suite**

```bash

Takes 20+ minutes - set timeout to 60+ minutes

Note: Some Enzyme tests may fail (expected on some systems)

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

```

**NEVER CANCEL** test commands - they require significant time to complete.

3. Building Documentation

```bash

Takes ~47 seconds - set timeout to 5+ minutes

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

```

4. Code Formatting

Always format code before committing:

```bash

One-time setup (takes ~45 seconds)

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

Format all code

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

```

5. Validation After Changes

Always test basic functionality with these scenarios:

```julia

using Bijectors, Distributions

Test 1: Basic bijector for LogNormal distribution

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)

```

6. Pre-Commit Checklist

Before committing any changes:

1. **ALWAYS** run Interface tests: `ENV["GROUP"] = "Interface"; Pkg.test()`

2. **ALWAYS** run code formatting: `using JuliaFormatter; format(".")`

3. Execute all validation scenarios listed above

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

5. Verify package loads without errors

7. Understanding Repository Structure

Key directories and files:

8. Common Issues

Expected issues that are not blockers:

9. CI/CD Workflows

The repository uses these CI workflows:

10. Key Concepts

**Bijectors** transform probability distributions by:

**Core operations**:

Constraints

Example Usage

When a developer asks to add a new bijector implementation:

1. Guide them to create a new file in `src/bijectors/`

2. Implement the core interface: transformation, inverse, and logabsdetjac

3. Add tests in `test/bijectors/`

4. Run validation scenarios to verify correctness

5. Run Interface tests (with 30+ minute timeout)

6. Format code with JuliaFormatter

7. Verify the package loads and basic operations work

When troubleshooting test failures:

1. Check if failures are in Enzyme tests (expected on some systems)

2. Verify timeout settings are appropriate for the test group

3. Run specific test groups to isolate issues

4. Validate basic functionality scenarios work correctly

5. Check that package dependencies are properly installed