Cursor: Julia Data Science Cursor Rules

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.
- 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.
- Describe the return value in the docstring.
- Example:
 ```julia
 """
 process_data(data::Vector{Float64}, threshold::Float64) -> Vector{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 using `dump`.
- Example:
 ```julia
 """
 Represents a data point with x and y coordinates.

 Fields:
 - `x::Float64`: The x-coordinate of the data point.
 - `y::Float64`: The y-coordinate of the data point.
 """
 @kwdef struct DataPoint
 x::Float64
 y::Float64
 end

 Base.show(io::IO, obj::DataPoint) = dump(io, obj; maxdepth=1)
 ```

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:
 ```julia
 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 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.

Testing
- Use the `Test` module for unit testing.
- Create one top-level `@testset` block per test file.
- Write test cases of increasing difficulty with comments explaining what is being tested.
- Use individual `@test` calls for each assertion, not for blocks.
- Example:
 ```julia
 using Test

 @testset "MyModule tests" begin
 # Test basic functionality
 @test add(2, 3) == 5

 # Test edge cases
 @test add(0, 0) == 0
 @test add(-1, 1) == 0

 # Test type stability
 @test typeof(add(2.0, 3.0)) == Float64
 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.