[doc] Add autograd docstring

[Routhleck]

This pull request adds example usage to several functions in the brainunit/autograd module to improve documentation and clarify how to use these functions with physical unit-aware computations. The most important changes include the addition of examples for the hessian, jacrev, jacfwd, and vector_grad functions.

Documentation improvements:

• brainunit/autograd/_hessian.py: Added example usage for the hessian function to demonstrate how to compute the Hessian of a function with physical units.
• brainunit/autograd/_jacobian.py: Added example usage for the jacrev function to show how to compute the Jacobian of a function with physical units.
• brainunit/autograd/_jacobian.py: Added example usage for the jacfwd function to illustrate how to compute the forward-mode Jacobian of a function with physical units.
• brainunit/autograd/_vector_grad.py: Added example usage for the vector_grad function to explain how to compute the gradient of a vector with respect to the input and handle physical units.

Summary by Sourcery

Documentation:

• Document how to use the hessian, jacrev, jacfwd, and vector_grad functions with physical unit-aware computations.

[sourcery-ai]

Reviewer's Guide by Sourcery

This pull request enhances the documentation of the brainunit/autograd module by adding example usage to several functions, including hessian, jacrev, jacfwd, and vector_grad. These examples demonstrate how to use these functions with physical unit-aware computations, improving clarity and usability.

Sequence diagram for autograd function calls with physical units

sequenceDiagram
    participant User
    participant AutogradFunction
    participant JAX
    participant UnitHandler

    User->>AutogradFunction: Call with unit-aware input
    AutogradFunction->>UnitHandler: Strip units
    AutogradFunction->>JAX: Compute derivative
    JAX-->>AutogradFunction: Return raw result
    AutogradFunction->>UnitHandler: Apply appropriate units
    AutogradFunction-->>User: Return unit-aware result

Loading

Class diagram for autograd module functions

classDiagram
    class autograd {
        +hessian(fun, argnums)
        +jacrev(fun, argnums)
        +jacfwd(fun, argnums)
        +vector_grad(fun, argnums, return_value)
    }

    note for autograd "All functions are unit-aware"

    class hessian {
        +__call__(x: Quantity) Quantity
    }

    class jacrev {
        +__call__(x: Quantity) Quantity
    }

    class jacfwd {
        +__call__(x: Quantity) Quantity
    }

    class vector_grad {
        +__call__(x: Quantity) Quantity
    }

    autograd ..> hessian
    autograd ..> jacrev
    autograd ..> jacfwd
    autograd ..> vector_grad

Loading

File-Level Changes

Change	Details	Files
Added example usage for the hessian function.	Included examples demonstrating how to compute the Hessian of functions with physical units.	brainunit/autograd/_hessian.py
Added example usage for the jacrev and jacfwd functions.	Included examples showing how to compute the Jacobian (both reverse and forward mode) of functions with physical units.	brainunit/autograd/_jacobian.py
Added example usage for the vector_grad function.	Included examples explaining how to compute the gradient of a vector with respect to the input and handle physical units, with and without returning the function's value.	brainunit/autograd/_vector_grad.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time. You can also use
  this command to specify where the summary should be inserted.

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @Routhleck - I've reviewed your changes - here's some feedback:

Overall Comments:

• Consider standardizing the example function names across docstrings (e.g., simple_function1 vs simple_function) to maintain consistency

Here's what I looked at during the review

• 🟢 General issues: all looks good
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}