Path String Formatting Overview

Ascent supports an number of special keyword values that can be used in formatting path names to generate unique file paths.

Supported Number Formats

The formatting uses c++ generic fmt formatting as a backend so it will work exactly like regular string formatting. For reference, we specifically support the following formatting values.

Note

The following examples are formatting the value 23.657

Format

Meaning

Example Input

Example Output

d

signed integer

03d

023

i

signed integer

03i

023

u

unsigned integer

03u

023

f

floating-point number (fixed-point)

3.1f

23.7

F

floating-point number (fixed-point, uppercase)

3.1F

23.7

e

decimal exponent notation (scientific, lowercase)

2.2e

2.37e+01

E

decimal exponent notation (scientific, uppercase)

2.2E

2.37E+01

g

formats as either e or f, whichever is shorter

2.4g

23.66

G

formats as either E or F, whichever is shorter

2.4G

23.66

Formatting Syntax

To use Ascent’s keyword formatting, insert the desired keyword in curly braces {} in your file path string optionally followed by a colon and the format specifier.

Syntax: {keyword:format}

If no format specifier is given, the default format for each keyword will be used (see bellow).

Formatting Keywords

Several supported keywords can be used in path formatting in Ascent. These are replaced at runtime with their corresponding values, allowing for dynamic and unique file naming.

Cycle

The current simulation cycle (integer, default format= 06d)

This is the default value used for formatting. When standard formatting convention is used in the path such as %03d, the cycle value will be inserted at runtime. Additionally, in cases where no formatting is provided, the cycle value will be appended to the end of the path name.

Input Path

Final Path Format

Resulting Paths

path

path_{cycle:06d}.png

path_000000.png, path_000001.png

path.png

path_{cycle:06d}.png

path_000000.png, path_000001.png

path_

path_{cycle:06d}.png

path_000000.png, path_000001.png

path_{cycle}

path_{cycle:06d}.png

path_000000.png, path_000001.png

path_{cycle:}

path_{cycle:06d}.png

path_000000.png, path_000001.png

path_{cycle}.png

path_{cycle:06d}.png

path_000000.png, path_000001.png

path_{cycle:03d}

path_{cycle:03d}.png

path_000.png, path_001.png

path_{cycle:03d}

path_{cycle:03d}.png

path_000.png, path_001.png

path_{cycle:03.1f}

path_{cycle:3.1f}.png

path_0.0.png, path_1.0.png

path_%03d

path_{cycle:03d}.png

path_000.png, path_001.png

Time

The simulation time (floating-point, default format= g)

Note

The following examples use 3.14159 as the time value

Input Path

Final Path Format

Resulting Paths

path_{time}

path_{time:g}.png

path_3.14159.png

path_{time:}

path_{time:g}.png

path_3.14159.png

path_{time}.png

path_{time:g}.png

path_3.14159.png

path_{time:1.3f}

path_{time:1.3f}.png

path_3.142.png

path_{time:3d}

path_{time:3d}.png

path_003.png

Family

A unique value based on existing files in the output directory (integer, default format= 06d)

The family value is used to avoid overwriting existing files in the output directory with a matching output file pattern, including those from previous runs of Ascent. It is set to one greater than the maximum detected family value of the matching file pattern, or zero if no matching files are found.

A minimum family value can be passed to ascent through the options using the family_value_seed keyword. This will force all family values to be greater than or equal to the seed value.

Listing 1 Example of setting the family_value_seed
Node ascent_opts;
ascent_opts["family_value_seed"] = 200;
ascent.open(ascent_opts);

Note

For the following examples we will assume that there is an existing file named path_0015.png in the output directory.

Input Path

Final Path Format

Resulting Paths

path_{family}

path_{family:06d}.png

path_000016.png, path_000017.png

path_{family:}

path_{family:06d}.png

path_000016.png, path_000017.png

path_{family}.png

path_{family:06d}.png

path_000016.png, path_000017.png

path_{family:03d}

path_{family:03d}.png

path_016.png, path_017.png

path_{family:03.1f}

path_{family:03.1f}.png

path_16.0.png, path_17.0.png

Warning

Family value might not behave as expected if running multiple instances of Ascent at the same time (e.g. when using parallel in time replay).

Multiple Keyword Formatting

Multiple keywords may be used in any order in the path string to create more descriptive and unique file path names.

Input Path

Final Path Format

Resulting Paths

path_{cycle}_{time}

path_{cycle:06d}_{time:g}.png

path_000000_3.14159.png

path_{cycle:03d}_{family:04d}

path_{cycle:03d}_{family:04d}.png

path_000_0016.png

path_time-{time}_cycle-{cycle}_family-{family}

path_time-{time:g}_cycle-{cycle:06d}_family-{family:06d}.png

path_time-3.14159_cycle-000000_family-000016.png

Error Handling and Edge Cases

  • If an invalid keyword is passed, Ascent will throw a warning and not format that keyword.

  • If an invalid format is passed, Ascent will throw a warning and use the default formatting for that keyword.

  • If a file with the same name already exists and the family value is not used, the file will be overwritten.

Best Practices

  • Always use zero-padding for cycle and family values to ensure files are sorted correctly.

  • Use the family keyword when you want to guarantee unique output file names across multiple runs.

  • Use descriptive prefixes and suffixes in your paths for clarity.