Organizing Run Directories

Why Directory Structure Matters

A model run can produce many kinds of files: the data and control files it used, execution logs, parameter estimates, diagnostic outputs, and summaries used to compare candidate runs. If these artifacts share an undifferentiated directory, a familiar filename such as “results.csv” may not reveal which run produced it or what it contains. A deliberate layout makes those distinctions visible in the filesystem itself.

The goal is not to make a directory tree elaborate. It is to make the location of an artifact predictable, preserve the boundary between one run and another, and make a group of related runs easy to locate. This tutorial assumes that each run has a stable identifier and that its manifest, execution environment, and preserved artifacts are recorded as established in the earlier material on those subjects.

This separation expresses an important boundary: a file produced by one execution belongs with that run, while a summary about several executions belongs with the set being considered. A clear boundary helps prevent a later run from overwriting an earlier result and helps a reviewer trace a summary back to the artifacts it describes.

A Practical Hierarchy

A useful starting point is one project or study root, with separate locations for runs and for comparison work. Inside each run directory, use distinct subdirectories for inputs, logs, and outputs. The precise names can differ across teams; the key requirement is consistent meaning and placement.

For example, under a study root called clearance-study, a run identified as run-20261027-a01 can be located at clearance-study/runs/run-20261027-a01/. Its inputs belong under inputs/, its execution records under logs/, and its results under outputs/. A summary involving that run and others belongs under a separate path such as clearance-study/comparisons/clearance-candidates/.

A manifest and environment record can sit at the run-directory level, alongside those three subdirectories, if that matches the team’s conventions. They should not be mixed into a generic output folder merely because they are files. Their role is to describe the run and its execution context, not to represent a model result.

Designing the Layout Around Reliable Boundaries

A layout works when the same rules apply to every run. Start with these assumptions: each run has a unique, stable identifier; run-specific inputs can be preserved separately from shared project files; and a comparison summary can identify the runs it refers to. If any of these conditions fails, a tidy directory tree alone cannot guarantee that files are correctly attributed.

The directory structure can be justified by assigning each artifact to a category before assigning it a path. First ask whether it is an input used by one run, a record of that run’s execution, a result produced by that run, or a summary about multiple runs. Then place it under the matching boundary. This simple classification reduces ambiguity because the directory path carries information about the file’s role and scope.

The logic is straightforward: a file placed in a shared output folder can be overwritten or mistaken for a result from another run; a file inside a uniquely identified run directory has a clearer owner. Similarly, a comparison summary stored inside one run may incorrectly appear to belong only to that run. Separating these scopes makes the filesystem structure reflect the work being recorded.

Keeping Comparison Summaries Separate

A comparison summary describes a relationship among runs, so store it outside the run directories. A comparison directory can contain a summary table, notes about its scope, and a list of the run identifiers it references. Keep the underlying run inputs, logs, and outputs in their original run directories rather than copying them into the comparison folder. This avoids creating multiple copies whose contents might later diverge.

Use references that a reviewer can resolve from the study root, such as a run identifier together with a relative path. Avoid relying only on a machine-specific absolute path: it may point to a location that does not exist after the project is moved. If links or shortcuts are used for convenience, treat them as pointers rather than as the authoritative copy of an artifact, and check that they still resolve.

A separate comparison directory is not a substitute for a clear run layout. If a summary points to a file named “result.csv” but several runs contain that filename, the reference needs the run identifier and the relevant subdirectory as well. A precise reference identifies both which run and which artifact are intended.

Naming, Portability, and Diagnostics

Directory names should be stable, readable, and consistent. Use the established run identifier as the run-directory name rather than inventing a second informal label. Use a separate, meaningful identifier for a comparison collection. Names should avoid spaces or characters that cause trouble for scripts and shared computing environments; a consistent pattern using letters, numbers, hyphens, or underscores is often practical.

Within each category, choose filenames that describe content rather than sequence or personal judgment. Names such as standard-output.log or parameter-estimates.csv communicate more than file2 or final-result. If a file is revised, do not silently replace an artifact that is intended to remain preserved. Keep references and descriptive records aligned with the saved artifacts.

Check a directory layout by asking whether a new team member can answer these questions without opening every file: Which run owns this artifact? Is it an input, a log, or an output? Which runs does this summary refer to? Can the referenced files still be found if the study root is moved? Difficulty answering any of these questions is evidence that the structure or references need attention.

Other warning signs include duplicate run-directory names, a summary stored inside an arbitrary run, outputs appearing in several locations with no clear authoritative copy, and input files referenced only from a mutable shared location. These problems are not solved by adding more nested folders. They call for clearer ownership, consistent placement, and references that identify the intended files.

Alternatives and Limits

A flat directory that puts every run’s files together is quick to create, but it relies on filenames to preserve run identity and is prone to collisions. A directory per run with no internal separation avoids some collisions, yet logs and outputs may still be mixed together, making it harder to distinguish execution records from results. A deeply nested hierarchy can add navigational overhead without improving attribution. For most studies, a study root, a collection of run directories, and a small set of role-based subdirectories within each run offer a useful balance.

No directory layout proves that a file is complete, unchanged, or scientifically appropriate. It also cannot guarantee that a comparison summary was computed correctly. Those properties depend on the run records, preserved artifacts, and review practices. The directory structure supports those practices by making files and their relationships easier to inspect; it does not replace them.

Common Mistake

Wrong reasoning: “These two runs are related, so I will put all their outputs in one shared output folder and use the same filenames.”

Correction: Related runs should be easy to locate together, but their run-specific artifacts still need separate ownership. Keep each run’s outputs inside its own run directory and put only collection-level summaries in the comparison directory. A shared study root provides discoverability without merging the artifact boundaries.