> For the complete documentation index, see [llms.txt](https://wiki.solids.group/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.solids.group/research-practices/ai-guidance.md).

# AI Guidance

AI tools and LLMs have transformed science and scientific computation. This page outlines our policies and best practices for using AI responsibly in solid mechanics group research projects.

## <i class="fa-feather-pointed">:feather-pointed:</i> Manuscript and thesis preparation

<table data-search="false"><thead><tr><th width="160.28515625"></th><th>Manuscript and technical document preparation</th></tr></thead><tbody><tr><td><i class="fa-circle-check" style="color:$success;">:circle-check:</i></td><td><strong>Copy editing, proofing, and formatting</strong><br>Use AI to review your manuscript to identify and fix typos and minor edits.</td></tr><tr><td><i class="fa-circle-check" style="color:$success;">:circle-check:</i></td><td><strong>Manuscript feedback and evaluation</strong><br>Use AI to critically evaluate your manuscript as a reviewer or committee member might. Use this feedback to improve your paper.</td></tr><tr><td><i class="fa-circle-check" style="color:$success;">:circle-check:</i></td><td><strong>Finding literature sources</strong><br>Use AI to find relevant manuscripts that you may have missed in your literature review.</td></tr><tr><td><i class="fa-triangle-exclamation" style="color:$warning;">:triangle-exclamation:</i></td><td><strong>Direct AI manuscript access</strong><br>Using codex or claude code to solve latex bugs or fix formatting is acceptable (for instance: if the journal requires a switch to a different latex template). However, AI should not be used to fix or alter your manuscript directly, even when making minor edits.</td></tr><tr><td><i class="fa-triangle-exclamation" style="color:$warning;">:triangle-exclamation:</i></td><td><strong>AI guidance on structural manuscript changes</strong><br>Use AI as an evaluator of your manuscript, not as a co-author. You can use AI to assess how your manuscript currently flows, but should not rely on it for suggestions on how to write.</td></tr><tr><td><i class="fa-triangle-exclamation" style="color:$warning;">:triangle-exclamation:</i></td><td><strong>Scripts for generating scientific plots</strong><br>AI can be used to generate or modify python scripts for presenting results. However, you are responsible to go through the scripts line-by-line, ensuring that the data is accurately represented.</td></tr><tr><td><i class="fa-triangle-exclamation" style="color:$warning;">:triangle-exclamation:</i></td><td><strong>Creating figures</strong><br>You may use AI to assist with figure creation, provided that these are strictly for illustrative purposes. You should not rely on AI generation but should instead provide adequately descriptive prompts so that AI does not need to generate filler content for you. All figures should be created in an editable format (SVG) so that you can tweak and adjust manually.</td></tr><tr><td><i class="fa-square-xmark" style="color:$danger;">:square-xmark:</i></td><td><strong>Generation of content</strong><br>You must generate all of the content for your manuscript yourself. Do not use AI to write text for you. When it is time to write, shut down the LLM entirely and generate every equation and every word yourself. Articulation of ideas in writing is an essential part of the learning process: any use of AI in this process - even for outlining or text drafting - short-circuits this objective.</td></tr></tbody></table>

## <i class="fa-square-terminal">:square-terminal:</i> Programming and Scientific Computing

<table data-search="false"><thead><tr><th width="160.28515625"></th><th>Scientific computing</th></tr></thead><tbody><tr><td><i class="fa-circle-check" style="color:$success;">:circle-check:</i></td><td><p><strong>Debugging and error-catching</strong><br>You are encouraged to use AI to identify programmatic errors in your code such as segmentation faults and syntax errors.<br>Examples:</p><ul><li>Identifying the source of a NAN in your code</li><li>Determining the cause of a segmentation fault</li><li>Fixing a syntax error or understanding why the C++ compiler is throwing a warning</li><li>Managing conflicts when executing a complicated merge</li></ul></td></tr><tr><td><i class="fa-circle-check" style="color:$success;">:circle-check:</i></td><td><p><strong>Code building and compatibility</strong><br>AI is very useful for streamlining the code building process, especially on new platforms such as HPC systems. You are encouraged to use AI here, especially when the obstacles are primarily programmatic rather than fundamental<br>Examples:</p><ul><li>Setting up and running jobs on nova</li><li>Determining why Alamo is not building on a system</li><li>Getting VisIt set up to run on a remote system</li></ul></td></tr><tr><td><i class="fa-circle-check" style="color:$success;">:circle-check:</i></td><td><p><strong>Code instrumentation and infrastructure</strong><br>AI excels at building tooling and infrastructure that facilitates high-efficiency coding, without supplanting actual implementation. For example, AI can be used to add diagnostic tools and a dashboard for reviewing run information. AI is also useful for ensuring compliance with code infrastructure standards (such as the Alamo ParmParse system).<br>Examples:</p><ul><li>Setting up the Parse function to read in all the appropriate variables.</li><li>Fixing bugs in the autodoc system and running an audit to make sure that all parameters are read correctly</li></ul></td></tr><tr><td><i class="fa-circle-check" style="color:$success;">:circle-check:</i></td><td><p><strong>Data management and postprocessing</strong><br>Moving data between systems and analyzing results is often unnecessarily cumbersome. You should use AI to streamline this process so you can focus on the science rather than the computational infrastructure.<br>Examples:</p><ul><li>Generating on-the-fly comparisons of data from a parameter sweep</li><li>Organizing and renaming data between the Alamo repository and paper repositories</li></ul></td></tr><tr><td><i class="fa-triangle-exclamation" style="color:$warning;">:triangle-exclamation:</i></td><td><p><strong>Core code generation</strong><br>Exercise caution when generating any scientific code using LLM. Prototyping is fine, but you must work through all code line-by-line to ensure that you understand and are responsible for every part of the result.<br><em><mark style="background-color:$warning;"><strong>Rule of thumb: when considering whether to use an LLM to implement a feature, ask "would I be able to do this myself?" If the answer is "yes," then proceed with caution. If the answer is "no," you should implement it yourself.</strong></mark></em><br>Examples:</p><ul><li>You need to implement an explicit diffusion solver. If you have previously implemented a solver like this and know you could do it again if needed, it is fine to use an LLM to do it for you. If you have not implemented a solver like this before, you should implement it yourself so that you build that skill.</li><li>You need to implement a set of serendipity shape functions in 3D. You have already coded polynomial shape functions in 2D and understand the theory behind them. In this case, it would be appropriate to use an LLM.</li></ul></td></tr><tr><td><i class="fa-triangle-exclamation" style="color:$warning;">:triangle-exclamation:</i></td><td><p><strong>Capability extension</strong><br>Implementing features of research codes like Alamo, specifically HPC and performance features, can be greatly accelerated using AI. If you use AI for this, you must follow the same rule of thumb as above.<br>Examples:</p><ul><li>You have determined how to make a solid model GPU safe; the code compiles and runs successfully. You can then use an LLM to apply similar adaptation to the other solid models in the code base.</li><li>You want to get Alamo working on AMD GPUs, but you have not done any research into what is necessary to implement this capability. Before handing this task to an LLM, you should determine what changes are necessary and test it yourself. Then you can use an LLM to replicate your results elsewhere.</li></ul></td></tr><tr><td><i class="fa-square-xmark" style="color:$danger;">:square-xmark:</i></td><td><strong>Black-box implementation of production code</strong><br>As a computational methods group, we are responsible for all of the code that we create - with or without LLMs. If you are just exploring and investigating, it is fine to use LLMs to generate exploratory code. However, you are responsible for ensuring its quality once it transitions to production code (production = results used in a paper or presentation).<br><em><mark style="background-color:$danger;"><strong>Rule of thumb: you must be able to explain every line of code that you use. If there is anything in the code that you cannot explain, you should not use the code until you can explain it.</strong></mark></em></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.solids.group/research-practices/ai-guidance.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
