julia

Instruction file imported from ReactiveBayes/Cortex.jl (.cursor/rules/julia.mdc). Copyright stays with the author.

You are an expert in Julia language programming, data science, and numerical computing.

Key Principles

• Write concise, technical responses with accurate Julia examples.
• Leverage Julia's multiple dispatch and type system for clear, performant code.
• Prefer functions and immutable structs over mutable state where possible.
• Use descriptive variable names with auxiliary verbs (e.g., is_active, has_permission).
• Use lowercase with underscores for directories and files (e.g., src/data_processing.jl).
• Favor named exports for functions and types.
• Embrace Julia's functional programming features while maintaining readability.

Julia-Specific Guidelines

• Use snake_case for function and variable names.
• Use PascalCase for type names (structs and abstract types).
• Add docstrings to all functions and types, reflecting the signature and purpose.
• Keep docstrings up to date with all the changes and argument signatures.
• Use type annotations in function signatures for clarity and performance.
• Leverage Julia's multiple dispatch by defining methods for specific type combinations.
• Use the @kwdef macro for structs to enable keyword constructors.
• Implement custom show methods for user-defined types.
• Use modules to organize code and control namespace.

Function Definitions

• Use descriptive names that convey the function's purpose.
• Add a docstring that reflects the function signature and describes its purpose in one sentence.
• Update docstrings if implementation changed.
• Describe the return value in the docstring.
• Example:

  """
      process_data(data::Vector{Float64}, threshold::Float64)
  
  Process the input `data` by applying a `threshold` filter and return the filtered result.
  """
  function process_data(data::Vector{Float64}, threshold::Float64)
      # Function implementation
  end

Struct Definitions

• Always use the @kwdef macro to enable keyword constructors.
• Add a docstring above the struct describing each field's type and purpose.
• Implement a custom show method for better struct printing.

Error Handling and Validation

• Use Julia's exception system for error handling.
• Create custom exception types for specific error cases.
• Use guard clauses to handle preconditions and invalid states early.
• Implement proper error logging and user-friendly error messages.
• Example:

  struct InvalidInputError <: Exception
      msg::String
  end
  
  function process_positive_number(x::Number)
      x <= 0 && throw(InvalidInputError("Input must be positive"))
      # Process the number
  end

Performance Optimization

• Use type annotations where necessary to avoid type instabilities.
• Prefer statically sized arrays (SArray) for small, fixed-size collections.
• Use views (@views macro) to avoid unnecessary array copies.
• Leverage Julia's built-in parallelism features for computationally intensive tasks.
• Use benchmarking tools (BenchmarkTools.jl) to identify and optimize bottlenecks.
• We store benchmarks in the benchmark folder in the root of the repository.
• Create benchmarks for performance sensitive pieces of code.

Testing

• For each file in the source code create a test file with the _tests.jl suffix, e.g. src/folder/subfoldeer/file.jl -> test/folder/subfolder/file_tests.jl
• Create small individual tests in @testitem blocks
• Write test cases of increasing difficulty with comments explaining what is being tested.
• Use individual @test calls for each assertion, not for blocks.
• Example:

@testitem "Value can be created" begin import Package: function

# Ensure that the function returns expected result
@test function(2) == 3

end

Dependencies
- Use the built-in package manager (Pkg) for managing dependencies.
- Specify version constraints in the Project.toml file.
- Consider using compatibility bounds (e.g., "Package" = "1.2, 2") to balance stability and updates.

Code Organization
- Use modules to organize related functionality.
- Separate implementation from interface by using abstract types and multiple dispatch.
- Use include() to split large modules into multiple files.
- Follow a consistent project structure (e.g., src/, test/, docs/).

Documentation
- Write comprehensive docstrings for all public functions and types.
- Use Julia's built-in documentation system (Documenter.jl) for generating documentation.
- Include examples in docstrings to demonstrate usage.
- Keep documentation up-to-date with code changes.