> 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/presenting-simulation-results.md).

# Presenting Simulation Results

A hallmark of good scientific computing is simulation reproducibility: computational results should be regenerable when needed.

Computational work is difficult and time-consuming, so it is easy to publish results before documenting all the steps needed to obtain them. This page describes how simulation results should be presented in paper repositories.

## Paper Repository Outline

This example uses the Alamo convention, but the principles apply to any simulation result.

```
PaperDescription/
    main.tex
    main.pdf
    main.out
    figures/
        MyFigure.svg
        MyFigure.pdf
    results/
        TestCaseA/
            output1/
                input.in
                metadata
                diff.patch
                smalldatafile.dat
                bigdatafile.dat
                pressure_profile.pdf
            output2/
            pressure_profile.py
            comparefigure.pdf
        TestCaseB/
```

The repository name should be one word beginning with `Paper`.

## Postprocessing Best Practices

Design plotting scripts so that they are easy for other people to use. Multiple people may create, revise, and regenerate figures during manuscript development and review.

Use descriptive filenames:

```
Bad:  plot.py
Good: thermal_contours.py
```

Do not use absolute file paths:

```python
# BAD: not portable
data = load_data("/home/brunnels/Research/PaperDescription/results/TestCaseA/output1/bigdatafile.dat")
```

Design scripts to run from the results directory:

```python
# GOOD
data = load_data("./TestCaseA/output1/bigdatafile.dat")
```

When possible, process large data into smaller files that can be stored in the repository:

```python
small_data = process_my_data(bigdata)
small_data.save("./TestCaseA/output1/smalldatafile.dat")
```

Then allow users to load the smaller processed data. This makes figures reproducible even when someone does not have access to the full raw dataset.

Store plots near their data and give them obvious names:

```python
# BAD
small_data.saveplot("output1.pdf")

# GOOD
small_data.saveplot("./TestCaseA/output1/thermal_contours.pdf")
```

Use PDF whenever possible unless a raster format is necessary.

## Including Figures in LaTeX

Use paths that make the source of the figure clear:

```latex
\begin{figure}
   \includegraphics{results/TestCaseA/output1/thermal_contours.pdf}
\end{figure}
```

From the filepath alone, a reader can tell that the figure is a simulation result from `TestCaseA`, in `output1`, showing thermal contours. The corresponding script should be nearby and similarly named.

## Guiding Principles

* Every paper is a Git repository.
* Simulation data is stored in the associated paper repository.
* Data too large for Git should still live in the same directory structure, but should be excluded through `.gitignore`.
* Every simulation gets its own self-contained subdirectory.
* Each simulation directory should contain everything needed to generate the simulation.
* Visualizations should be stored as close to the data as possible.
* Scripts should be stored as close to the visualizations as possible and named similarly when practical.
* The `figures` directory is for illustrations only, not scientific results.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.solids.group/research-practices/presenting-simulation-results.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.