# Codegraph

> Use CodeGraph to navigate PETSc and avoid duplicating existing functionality. Use whenever writing or reviewing PETSc C, C++, or Python, especially before adding or changing a public API, package utility, object operation, implementation, backend, registration, or composed method; when finding callers and the blast radius of a change; or when comparing sibling implementations. Target PETSc's own index explicitly so queries use the intended graph. CodeGraph is optional: if the index is absent, no CodeGraph tool or CLI is available, or runtime dispatch is unresolved, continue with normal repository inspection without blocking.

- Skill: `petsc/codegraph` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add petsc/codegraph`
- Raw SKILL.md: https://api.skillmd.com/api/skills/petsc/codegraph/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: petsc (https://skillmd.com/u/petsc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/petsc/codegraph

---


# CodeGraph for PETSc

Use CodeGraph to follow PETSc's interface/implementation structure and honor the repository rule
to reuse or extend existing routines before adding new ones. Prefer `codegraph_explore`; it
returns relevant source, relationships, callers, and blast-radius information in one call.

## Select the PETSc index

Use whichever CodeGraph interface is available, and always target the PETSc repository root:

- With the `codegraph_explore` tool, pass the PETSc root as `projectPath`.
- With shell access, confirm the index with `codegraph status <petsc-root>`, then run
  `codegraph explore "..."` from the PETSc root so the query resolves against PETSc's index.
- Confirm `<petsc-root>/.codegraph/` exists before querying it.

Do not silently use an enclosing repository's index. If the PETSc index is absent, or no
CodeGraph tool or CLI is available, skip CodeGraph, continue with normal repository inspection,
and (if the index is what's missing) mention that the user can run `codegraph init` from the
PETSc root. Indexing is the user's decision; do not initialize it automatically.

## Search before implementing

Before adding a function, helper, object operation, or implementation:

1. Name the proposed symbol and state its behavior.
2. Query by both likely names and the behavior it provides. Include the PETSc package and data
   type to disambiguate common names.
3. Compare the closest existing implementation and at least one sibling in the same package or
   backend family.
4. Reuse an equivalent routine. Prefer a small extension or fix when an existing routine is
   nearly capable. Add a new routine only when semantics, performance, or compatibility genuinely
   differ.

Common reinvention hot spots include allocation and array helpers, integer casts, sorting and hash
utilities, string and options handling, object composition, viewers, logging, and package-private
`*_Private` routines.

## Trace PETSc runtime dispatch

PETSc frequently dispatches through macros, operation tables, composed functions, and registries.
CodeGraph may find both endpoints without connecting the runtime edge. Do not interpret a missing
edge as proof that the symbols are unrelated.

For `PetscUseTypeMethod()` and `PetscTryTypeMethod()`:

1. Query the public interface routine, operation-field name, likely implementation names, and
   constructor or operation-table symbol together. For example, query `MatMult mult
   MatMult_SeqAIJ MatCreate_SeqAIJ MatOps_Values`.
2. Follow the interface call to `obj->ops->operation`.
3. Locate assignments or table entries for that operation and inspect the implementation
   functions they select.
4. For repeated file-local table names such as `MatOps_Values`, include the implementation path
   in the query and verify the table in that file. Map positional initializers against the
   corresponding `struct _*Ops` field order.
5. Continue through subtype, backend, and options-driven setup that may override the base
   operation table.
6. Independently resolve the assignment or table step when CodeGraph stops at the function
   pointer.

For `PetscUseMethod()` and `PetscTryMethod()`:

1. Query the method key, the calling interface, `PetscObjectComposeFunction()`, and likely
   implementation names together.
2. Match the exact composed-function key, including its `_C` suffix.
3. Check every relevant type constructor and conversion path that composes or removes the method.

For registered types, query the public creation path, `*Register()` routine,
`PetscFunctionListAdd()`, type name, and implementation constructor together. Expect the
registry-selected function-pointer call to require verification through the exact type key and
registration entry.

## Assess blast radius

Before changing a shared symbol, use CodeGraph to find callers, references, siblings, and covering
tests. Supplement the result where PETSc's runtime structure can hide dependencies:

- Search operation-table assignments and composed-function keys for dispatch changes.
- Search registration lists and type constructors for implementation changes.
- Check public headers, documentation, bindings, examples, and tests for public API changes;
  generated or conditionally compiled surfaces may not appear as static graph edges.
- Check CPU, MPI, CUDA, HIP, and Kokkos siblings when changing behavior shared across backends.

Use these checks to scope the requested change, not to expand it into unrelated cleanup.

## Practical rules

- Treat source returned by `codegraph_explore` as already read; do not fetch the same source again.
  Before editing a file, read it directly — declaration blocks, `PetscFunctionBegin` pairing, and
  the `/*TEST*/` block lie outside a symbol-scoped snippet.
- Use other repository-inspection capabilities only for details CodeGraph did not cover,
  especially macro expansion, function-pointer assignment, generated files, preprocessor
  variants, and text-only configuration.
- Keep queries specific. Combine interface, operation, type, constructor, and implementation names
  when tracing dispatch.
- If CodeGraph reports pending re-indexing for an edited file, read that file directly until the
  index catches up. If it reports that auto-sync is disabled, directly verify all potentially
  changed files.
- Use the compiler, linter, and relevant tests for correctness. CodeGraph describes structure and
  impact; it does not validate behavior.