Paper Organization

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.

Naming convention

Paper names (i.e. the repo name on overleaf) should follow the format PaperDescriptiveTitle. For example:

PaperReactiveFlowComparison PaperTurbulentJetValidation PaperShockTubeIgnitionStudy paper-reactive-flow-comparison ReactiveFlowComparison Paper Reactive Flow Comparison

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/

Postprocessing

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:

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

Design scripts to run from the results directory:

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

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

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.

small_data.saveplot("output1.pdf") small_data.saveplot("./TestCaseA/output1/thermal_contours.pdf")

When possible, give the plot the same name as the output it generates.

Use PDF whenever possible unless a raster format is necessary.

Including Figures in LaTeX

Use paths that make the source of the figure clear:

\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.