User Settings

SiliconCompiler provides a robust system for managing persistent user configuration across different sessions and tools. This system allows you to define default behaviors—such as your preferred scheduler, remote processing credentials, or compilation flags—once, and have them automatically applied to every new Project.

The settings are managed by a centralized SettingsManager which ensures thread-safe and process-safe access to the configuration file using file locking. This is particularly important in environments where multiple SiliconCompiler processes (e.g., parallel build steps) might attempt to read or write settings simultaneously. The user is not expected to directly interact with the SettingsManager, but instead should set and save the settings via the associated classes.

Storage Format

Settings are stored in a JSON file (typically located at ~/.sc/settings.json). The file is organized into categories, allowing different tools and subsystems within SiliconCompiler to maintain their own isolated configuration spaces.

The JSON structure generally looks like this:

{
    "schema-options": {
        "scheduler,name": "slurm",
        "scheduler,queue": "hw_queue",
        "remote": true,
        "optmode": "2"
    },
    "other-category": {
        "setting_name": "value"
    }
}

Note

The settings manager uses a “last-write-wins” policy per key and protects file integrity with strict error handling. If the settings file becomes malformed, the manager will log an error and start with an empty configuration to prevent crashes.

System-Wide Defaults

In addition to the per-user file, SiliconCompiler can read a system-wide settings file managed by an administrator. This is useful on shared machines—such as an HPC login node—where an administrator wants to provide sensible defaults (for example, cluster-wide Slurm sharedpaths) to every user without asking each of them to configure their own ~/.sc/settings.json.

The system-wide file uses the same JSON structure as the per-user file. Its location is resolved in the following order:

1. The SC_SYSTEM_SETTINGS environment variable, if set, is used verbatim as the path to the file. This is the recommended override for non-root installs, virtual environments, containers, and continuous integration.

2. Otherwise, a platform-specific default location is used:

   • Linux/macOS: /etc/siliconcompiler/settings.json

   • Windows: %PROGRAMDATA%\siliconcompiler\settings.json (typically C:\ProgramData\siliconcompiler\settings.json)

Note

The default system location (/etc) requires administrator privileges to write, which is intentional: only an administrator should be able to change machine-wide defaults. Users who need their own machine-wide file without root access should point SC_SYSTEM_SETTINGS at a writable location.

Precedence and System Priority

By default, system-wide values act as defaults that a user may override in their own ~/.sc/settings.json. When resolving a setting, SiliconCompiler applies the following precedence:

1. If the setting has system priority, the system value is used and the user value is ignored.

2. Otherwise, the user value is used if present.

3. Otherwise, the (plain) system default is used if present.

4. Otherwise, the built-in default is used.

An administrator can promote any default to a system-priority (non-overridable) value by co-locating a flag with the value. Instead of writing a bare value, write an object with a "system_priority" flag (and, optionally, a "value"):

{
    "record": {
        "region": {"value": "us-east-1", "system_priority": true}
    },
    "scheduler-slurm": {
        "sharedpaths": ["/nfs/tools"]
    }
}

In this example every user is pinned to region = us-east-1 (it cannot be overridden), while sharedpaths is a plain default that users may override. Attempts to change or delete a system-priority setting are ignored with a warning. A priority wrapper may also omit "value" (e.g. {"system_priority": true}) to force a setting to stay unset, so callers fall back to their built-in default.

Note

Priority flags are only honored in the system file. A value written in this {"value": ..., "system_priority": ...} shape inside a user’s settings.json is treated as an ordinary dictionary value, so existing user files are unaffected by this feature. User files are never modified to include system defaults; saving only ever writes the user’s own values.

Concurrency & Safety

The underlying SettingsManager utilizes a file lock (.lock) alongside the JSON file. This ensures that:

1. Atomic Writes: Partial writes are prevented.

2. Process Safety: Multiple independent SiliconCompiler runs can safely read/write defaults without race conditions.

3. Error Recovery: If the lock cannot be acquired within a timeout (default 1.0s), the operation logs an error and proceeds safely (e.g., by skipping the load or failing the save gracefully) to ensure your build pipeline doesn’t hang indefinitely.

Schema Defaults (The ‘schema-options’ Category)

The most common use case for user settings is defining default values for the SiliconCompiler OptionSchema. When a new Project is initialized, it automatically queries the settings manager for the schema-options category.

Key Mapping

Because the Schema is hierarchical (e.g., [option,scheduler,name]), the keys in the JSON settings file are flattened using comma separation.

• Schema path: [option,scheduler,name] \(\rightarrow\) JSON key: "scheduler,name"

• Schema path: [option,remote] \(\rightarrow\) JSON key: "remote"

Workflow: Schema Defaults

1. Loading Defaults: When you instantiate a project, SiliconCompiler automatically loads values from the settings file. These values act as the baseline defaults.

   # If settings.json contains "scheduler,name": "slurm"
   project = siliconcompiler.Project()
   
   # The project starts with slurm enabled
   print(project.option.scheduler.get_name())
   # Output: slurm
   

2. Saving Defaults: You can programmatically save your current configuration as the new user default using OptionSchema.write_defaults(). This method compares your current configuration against the built-in defaults and saves only the modified parameters to the schema-options category in the settings file.

   import siliconcompiler
   
   project = siliconcompiler.Project()
   
   # Configure your preferred environment
   project.option.scheduler.set_name("slurm")
   project.option.scheduler.set_queue("priority_queue")
   project.option.set_quiet(True)
   
   # Persist these settings to disk
   project.option.write_defaults()
   
   # Now, any future script you run will default to using Slurm on the 'priority_queue'
   # with quiet logging enabled.
   

Slurm Scheduler Settings (The ‘scheduler-slurm’ Category)

In addition to the standard schema options, specific schedulers may require their own configuration settings. For example, the Slurm scheduler uses the scheduler-slurm category to manage cluster-specific behaviors.

Shared Paths

One key setting for Slurm is sharedpaths. This defines a list of directory prefixes that are available on all nodes in the cluster (e.g., via NFS or GPFS). When SiliconCompiler runs on a compute node, it checks if input files are located within these shared paths. If they are, the files are used directly; otherwise, they are copied to the build directory to ensure accessibility. This optimization significantly reduces network traffic and disk usage for large designs.

{
    "scheduler-slurm": {
        "sharedpaths": ["/nfs/tools", "/work/project"]
    }
}

Workflow: Slurm Settings

Unlike standard schema options, scheduler-specific settings (like sharedpaths) are stored in their own category. The SlurmSchedulerNode provides static helper methods to manage these configurations safely without needing to manually interact with the settings manager.

from siliconcompiler.scheduler.slurm import SlurmSchedulerNode

# 1. Set the shared paths
# These paths must be visible on all compute nodes.
SlurmSchedulerNode._set_user_config("sharedpaths", ["/nfs/tools", "/work/project"])

# 2. Persist changes to ~/.sc/settings.json
SlurmSchedulerNode._write_user_config()

Show Task Preferences (The ‘showtask’ Category)

SiliconCompiler allows you to define preferred viewers for specific file extensions. This is useful when multiple tools are capable of opening a specific file type (e.g., both KLayout and OpenROAD can view .def files) and you want to enforce a specific default.

This configuration is stored in the showtask category of your settings.json file. The key is the file extension (without the dot), and the value is the name of the tool (and optionally the task).

Example Configuration

{
    "showtask": {
        "gds": "klayout",
        "def": "openroad/show",
        "vcd": "gtkwave"
    }
}

In this example:

• .gds files will always open with KLayout.

• .def files will always open with OpenROAD, specifically using the show task.

• .vcd files will always open with GTKWave.

If the preferred tool is not found or not registered, SiliconCompiler will fall back to its default discovery mechanism.

Record Settings (The ‘record’ Category)

The record category allows you to define metadata about the execution environment, which is useful for tracking and aggregating results across different cloud regions or clusters.

Example Configuration

{
    "record": {
        "region": "us-east-1"
    }
}

In this example, the region key specifies the cloud region. This information is retrieved by the schema support tools to tag records with the appropriate environment details. If omitted, the region defaults to local.