Regression Names

Regressions can have any name, but they must be unique within Simscope.

Example regression names:

• alpha_cpu_smoke_daily/1234
• alpha_cpu_smoke_daily/2023.04.01_12.22.53 (timestamp based)
• beta_lsu_interop-202 (using - separator)

Uniqueness Constraint

If two Components launch a regression called smoke/10, these will automatically be merged into one regression, which may not be the desired behavior.

• To fix this, these regressions should have a unique prefix or suffix, like alpha_cpu_smoke_nightly/10 or beta_gpu_smoke/10.

Regression Series Name Grouping

Simscope will automatically group regressions together into a Regression Series, if they have a name suffixed by /<NUMBER> (ie slash-number).

• For example, a regression named alpha_cpu_smoke_nightly/99
  • Simscope automatically assumes this is followed by alpha_cpu_smoke_nightly/100 and is preceded by alpha_cpu_smoke_nightly/98.

You can change this separator character via simscope.config by setting the seriesseparator field.

This example changes the separator to a dash (e.g. cpu_smoke_nightly-99):

[regr]
# Regression name separator.
# Example: "nightly_smoke/123"
#seriesseparator = "/"

# Example: "nightly_smoke.123"
#seriesseparator = "."

# Example: "nightly_smoke-123"
seriesseparator = "-"

Python Regression ID from Timestamp (YMD)

If you want to generate a timestamp-based regression name (based on the regression start timestamp):

Here is a Python code snippet (assuming you have a datetime variable called regr_start):

# Note: if you need a start timestamp variable:
# regr_start = datetime.now()

run_name = 'my_block_smoke'
run_id = '%s/%s' % (run_name, regr_start.strftime('%Y.%m.%d-%H.%M.%S'))

Example run:

• my_block_smoke/2024.04.11-14.30.48

Python Series ID generator

If your regression flow does not have a unique regression series ID, you can use this Python code to create one.

Notes:

• This code is safe to use from multiple processes, as it uses OS file locking.
  • This requires the filelock Python package (see installation below).

# next_series_id: make a unique run/regression ID for Simscope.
#
# VerOps, Inc.
# https://verops.com

# Note: to install the filelock library, run:
# > python3 -mpip install filelock

import filelock
import os
import sys

def next_series_id(id_path, permissions=0o664, timeout=60):
    '''
    next_series_id returns the next series integer from an id file (returning a unique series ID).
    It auto-increments the file after completion.
    permissions: file read/write permissions (for group sharing)
    timeout: number of seconds before lock acquisition times out (or set to zero for unlimited wait time).
    Note: this uses a filelock library, to ensure safe multithreaded access.
    '''

    id = 1
    try:
        lock = filelock.FileLock(id_path + '.lock', timeout=timeout, mode=permissions)

        with lock:
            if os.path.isfile(id_path):
                f = open(id_path, 'r')
                content = f.read().strip()
                f.close()

                if content.isdigit():
                    # read-modify-write
                    id = int(content)
                    id += 1

            f = open(id_path, 'w')
            f.write(str(id))
            f.close()
            os.chmod(id_path, permissions)

    except Exception as e:
        # Lock failed, likely due to timeout or permissions
        sys.stderr.write('WARNING: failed to acquire next_series_id(%s): %s\n' % (id_path, e))
        raise

    return id

Example usage in a regression script:

run_id = next_series_id('/shared/project/alpha_my_smoke.num', timeout=30)
run_name = 'alpha_my_smoke/%d' % run_id

print(run_name)

# After running, this will print a unique regression name, similar to:

→ "alpha_my_smoke/3"