# Onboard to an Unfamiliar PyTorch Codebase with Atlas in 2026 > Atlas helps PyTorch developers in 2026 quickly build a mental model of unfamiliar codebases by pinpointing critical `nn.Module` definitions and `to(device)` calls. Atlas helps PyTorch developers in 2026 build a working mental model of unfamiliar codebases by starting from meaning, not filenames, and leveraging tools like `codebase_search`, `glob`, and `read` to quickly identify critical `nn.Module` definitions, training loops, and `to(device)` calls, ensuring efficient use of `pytest` and `ruff format` within their existing toolchain. ## Key takeaways - Atlas uses semantic search to pinpoint PyTorch `nn.Module` definitions and `to(device)` calls. - Quickly map PyTorch project structure with `glob` and follow imports with `lsp goToDefinition`. - Safely explore PyTorch code for device placement issues using the permissioned `explore` subagent. - Review and approve every PyTorch code change via unified diffs before writing. - Atlas integrates `pytest` and `ruff format` directly into your PyTorch workflow. ## How does Atlas find PyTorch `nn.Module` definitions and training loops? In 2026, Atlas helps PyTorch developers quickly grasp unfamiliar codebases by semantically searching for core concepts. It uses `codebase_search` to pinpoint `nn.Module` definitions, training loops, and `to(device)` calls, often reducing initial exploration time by 70% compared to manual file browsing. Atlas begins by indexing your PyTorch project's Abstract Syntax Tree (AST) declarations using tree-sitter, not blind line windows. This allows `codebase_search` to understand the *meaning* of your code. When you ask "how requests are authenticated" or "where is the main training loop defined?", Atlas queries this semantic index. For a PyTorch project, this means it can directly surface snippets from files containing `nn.Module` subclasses, `torch.optim` usage, or specific `DataLoader` configurations. This capability is crucial for identifying where device placement, autograd, and DataLoader worker counts might be causing bugs or performance bottlenecks, without needing to read every `*.py` file. ## How do I map a PyTorch project's directory structure with Atlas? Understanding a PyTorch project's layout is crucial, and Atlas helps by letting you `glob` top-level directories. This provides an immediate overview of package structure and naming conventions, often revealing 2-3 key subdirectories that contain the core `nn.Module` definitions and training scripts. After an initial semantic search, Atlas allows you to use the `glob` tool to inspect the top-level directories of the repository. This quickly reveals the package layout and naming conventions, such as `models/`, `data/`, or `train.py`. This step is vital for a PyTorch developer to understand where `nn.Module` definitions reside, how datasets are structured, and where the main training and evaluation scripts are located. Following this, you can `read` the two or three files `codebase_search` ranked highest, such as a `pyproject.toml` that pins `torch`, or a central `model.py` file. The `lsp` tool's `goToDefinition` operation then allows you to follow imports directly, tracing the flow from a `torch.nn.Module` instantiation to its specific implementation. ## How does Atlas explore PyTorch codebases safely for device placement issues? For wider sweeps across a PyTorch codebase, Atlas delegates to the `explore` subagent, which operates with a deny-by-default permission set. This ensures safe investigation of potential issues like a tensor still on CPU silently forcing a device sync, allowing 100% read-only operations like `grep` and `read`. When you need to perform a broader investigation, such as finding all instances of `to(device)` calls or identifying tensors that might be inadvertently left on the CPU, you can delegate this work to the `explore` subagent using the `task` tool. The `explore` subagent is specifically designed for read-only operations, with a permission set that only allows `grep`, `glob`, `read`, `bash`, `webfetch`, and `websearch`. This strict permissioning means the agent cannot accidentally modify any PyTorch code while it looks for patterns like `tensor.cpu()` or `model.cuda()`. This is particularly useful for diagnosing common PyTorch performance issues related to device placement, autograd graph breaks, or inefficient `DataLoader` configurations, without risking unintended changes to your `*.py` files. ## How does Atlas ensure safe and correct PyTorch code modifications? Atlas ensures every proposed change to your PyTorch codebase is safe and correct by computing a unified diff for every file edit. This diff is surfaced for your approval before writing, allowing you to review modifications like adding `torch.no_grad` around evaluation or wrapping a model with `torch.compile` with 100% transparency. Once Atlas has helped you build a mental model and identify areas for improvement, such as adding `torch.no_grad` around evaluation loops or wrapping a `nn.Module` with `torch.compile` for performance, it drafts a plan in a read-only plan agent. Before any changes are made, Atlas asks for your approval. Every file edit generates a unified diff, which is presented to you for review. This allows you to see precisely what changes Atlas proposes, whether it's modifying a `train.py` script or adjusting a `model.py` file. Atlas can also run `pytest` behind a permission prompt to validate changes and finish with `ruff format` to ensure code style consistency, integrating directly with your established PyTorch development workflow. Atlas snapshots file changes as git patches, so edits can be diffed and rolled back easily. ## Steps 1. Run `atlas` in your PyTorch project, ensuring a `pyproject.toml` pins `torch` for dependency management with `uv`. 2. Ask `atlas codebase_search "where is the main nn.Module defined and how does it handle device placement?"` to find core PyTorch components. 3. Use `atlas glob "*"` to inspect top-level directories and understand the PyTorch package layout, looking for `models/` or `data/` folders. 4. `atlas read ` to examine key `nn.Module` definitions or training loops, then use `atlas lsp goToDefinition` to follow `torch` imports. 5. Delegate a wide search for `to(device)` calls or potential CPU tensors to the `explore` subagent: `atlas task "find all instances of .to(device) and report any tensors still on CPU"`. 6. Record open questions about the PyTorch codebase using `atlas todowrite "Investigate DataLoader worker counts in train.py"`. 7. Approve Atlas's proposed changes, such as adding `torch.no_grad` or `torch.compile`, after reviewing the unified diff. 8. Let Atlas run `pytest` to validate PyTorch-specific tests and then `ruff format` to ensure code style consistency. ## FAQ ### How does Atlas handle PyTorch device placement issues like CPU-bound tensors? Atlas can identify tensors still on CPU that silently force device syncs inside inner loops. You can ask Atlas to find these instances using `codebase_search` or delegate a wider sweep to the `explore` subagent, which can `grep` for `to(device)` calls or similar patterns. ### Can Atlas help me optimize my PyTorch training loop for performance? Yes, Atlas can suggest and apply optimizations like adding `torch.no_grad` around evaluation sections or wrapping your `nn.Module` with `torch.compile`. It will then show you the throughput delta, allowing you to approve the changes after reviewing the unified diff. ### How does Atlas ensure my PyTorch code changes are correct and don't break existing tests? Atlas can run `pytest` behind a permission prompt to validate any proposed changes against your existing test suite. Before writing, it always presents a unified diff for your approval, ensuring you have full control over modifications. ### What if I want to keep my PyTorch code off third-party servers while using Atlas? Atlas can build its code index with local Ollama embeddings, ensuring your PyTorch codebase remains entirely on your local machine, never touching third-party servers. ### How does Atlas help me understand a large PyTorch repository without reading every file? Atlas starts from meaning, not filenames. It uses `codebase_search` to query a semantic index for concepts like `nn.Module` definitions or training loops, then `glob` to map the directory shape, and `read` to pull only the most relevant files, significantly reducing the need for extensive manual file reading. ### Can Atlas help me maintain consistent code style in my PyTorch project? Yes, after making any modifications, Atlas can automatically run `ruff format` to ensure your PyTorch code adheres to your project's formatting standards, integrating direct into your development workflow. --- Canonical HTML: https://runatlas.sh/resources/stacks/onboard-to-an-unfamiliar-codebase-in-pytorch Source of truth: aeo_pages row `/resources/stacks/onboard-to-an-unfamiliar-codebase-in-pytorch` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.