archspec

archspec.cpu

The “cpu” package permits to query and compare different CPU microarchitectures.

exception archspec.cpu.InvalidCompilerVersion

Raised when an invalid format is used for compiler versions in archspec.

class archspec.cpu.Microarchitecture(name, parents, vendor, features, compilers, generation=0)

Represents a specific CPU micro-architecture.

Parameters:

  • name (str) – name of the micro-architecture (e.g. skylake).

  • parents (list) – list of parents micro-architectures, if any. Parenthood is considered by cpu features and not chronologically. As such each micro-architecture is compatible with its ancestors. For example “skylake”, which has “broadwell” as a parent, supports running binaries optimized for “broadwell”.

  • vendor (str) – vendor of the micro-architecture

  • features (set of str) – supported CPU flags. Note that the semantic of the flags in this field might vary among architectures, if at all present. For instance x86_64 processors will list all the flags supported by a given CPU while Arm processors will list instead only the flags that have been added on top of the base model for the current micro-architecture.

  • compilers (dict) –

    compiler support to generate tuned code for this micro-architecture. This dictionary has as keys names of supported compilers, while values are list of dictionaries with fields:

    • name: name of the micro-architecture according to the

      compiler. This is the name passed to the -march option or similar. Not needed if the name is the same as that passed in as argument above.

    • versions: versions that support this micro-architecture.

  • generation (int) – generation of the micro-architecture, if relevant.

property ancestors

All the ancestors of this microarchitecture.

property family

Returns the architecture family a given target belongs to

feature_aliases = <archspec.cpu.schema.LazyDictionary object>

Aliases for micro-architecture’s features

static from_dict(data) → Microarchitecture

Construct a microarchitecture from a dictionary representation.

property generic

Returns the best generic architecture that is compatible with self

optimization_flags(compiler, version)

Returns a string containing the optimization flags that needs to be used to produce code optimized for this micro-architecture.

The version is expected to be a string of dot separated digits.

If there is no information on the compiler passed as argument the function returns an empty string. If it is known that the compiler version we want to use does not support this architecture the function raises an exception.

Parameters:

  • compiler (str) – name of the compiler to be used

  • version (str) – version of the compiler to be used

Raises:

  • UnsupportedMicroarchitecture – if the requested compiler does not support this micro-architecture.

  • ValueError – if the version doesn’t match the expected format

to_dict()

Returns a dictionary representation of this object.

exception archspec.cpu.UnsupportedMicroarchitecture

Raised if a compiler version does not support optimization for a given micro-architecture.

archspec.cpu.brand_string() → str | None

Returns the brand string of the host, if detected, or None.

archspec.cpu.generic_microarchitecture(name)

Returns a generic micro-architecture with no vendor and no features.

Parameters:

name (str) – name of the micro-architecture

archspec.cpu.host()

Detects the host micro-architecture and returns it.

archspec.cpu.version_components(version)

Decomposes the version passed as input in version number and suffix and returns them.

If the version number or the suffix are not present, an empty string is returned.

Parameters:

version (str) – version to be decomposed into its components

archspec.cpu.alias

Aliases for microarchitecture features.

class archspec.cpu.alias.FeatureAliasTest(rules)

A test that must be passed for a feature alias to succeed.

Parameters:

rules (dict) – dictionary of rules to be met. Each key must be a valid alias predicate

archspec.cpu.alias.alias_predicate(func)

Decorator to register a predicate that can be used to evaluate feature aliases.

archspec.cpu.alias.any_of(list_of_features)

Returns a predicate that is True if any of the feature in the list is in the microarchitecture being tested, False otherwise.

archspec.cpu.alias.families(list_of_families)

Returns a predicate that is True if the architecture family of the microarchitecture being tested is in the list, False otherwise.

archspec.cpu.alias.reason(_)

This predicate returns always True and it’s there to allow writing a documentation string in the JSON file to explain why an alias is needed.

archspec.cpu.detect

Detection of CPU microarchitectures

archspec.cpu.detect.COMPATIBILITY_CHECKS = {'aarch64': <function compatibility_check_for_aarch64>, 'ppc64': <function compatibility_check_for_power>, 'ppc64le': <function compatibility_check_for_power>, 'riscv64': <function compatibility_check_for_riscv64>, 'x86_64': <function compatibility_check_for_x86_64>}

Mapping from micro-architecture families (x86_64, ppc64le, etc.) to functions checking the compatibility of the host with a given target

class archspec.cpu.detect.CpuidInfoCollector

Collects the information we need on the host CPU from cpuid

brand_string() → str | None

Returns the brand string, if available.

archspec.cpu.detect.INFO_FACTORY = {'Darwin': [<function sysctl_info>], 'Linux': [<function proc_cpuinfo>], 'Windows': [<function cpuid_info>]}

Mapping from operating systems to chain of commands to obtain a dictionary of raw info on the current cpu

archspec.cpu.detect.brand_string() → str | None

Returns the brand string of the host, if detected, or None.

archspec.cpu.detect.compatibility_check(architecture_family: str | Tuple[str, ...])

Decorator to register a function as a proper compatibility check.

A compatibility check function takes a partial Microarchitecture object as a first argument, and an arbitrary target Microarchitecture as the second argument. It returns True if the target is compatible with first argument, False otherwise.

Parameters:

architecture_family – architecture family for which this test can be used

archspec.cpu.detect.compatibility_check_for_aarch64(info, target)

Compatibility check for AARCH64 architectures.

archspec.cpu.detect.compatibility_check_for_power(info, target)

Compatibility check for PPC64 and PPC64LE architectures.

archspec.cpu.detect.compatibility_check_for_riscv64(info, target)

Compatibility check for riscv64 architectures.

archspec.cpu.detect.compatibility_check_for_x86_64(info, target)

Compatibility check for x86_64 architectures.

archspec.cpu.detect.compatible_microarchitectures(info: Microarchitecture) → List[Microarchitecture]

Returns an unordered list of known micro-architectures that are compatible with the partial Microarchitecture passed as input.

archspec.cpu.detect.cpuid_info()

Returns a partial Microarchitecture, obtained from running the cpuid instruction

archspec.cpu.detect.detected_info() → Microarchitecture

Returns a partial Microarchitecture with information on the CPU of the current host.

This function calls all the viable factories one after the other until there’s one that is able to produce the requested information. Falls-back to a generic microarchitecture, if none of the calls succeed.

archspec.cpu.detect.detection(operating_system: str)

Decorator to mark functions that are meant to return partial information on the current cpu.

Parameters:

operating_system – operating system where this function can be used.

archspec.cpu.detect.host()

Detects the host micro-architecture and returns it.

archspec.cpu.detect.partial_uarch(name: str = '', vendor: str = '', features: Set[str] | None = None, generation: int = 0) → Microarchitecture

Construct a partial microarchitecture, from information gathered during system scan.

archspec.cpu.detect.proc_cpuinfo() → Microarchitecture

Returns a partial Microarchitecture, obtained from scanning /proc/cpuinfo

archspec.cpu.detect.sysctl_info() → Microarchitecture

Returns a raw info dictionary parsing the output of sysctl.

archspec.cpu.microarchitecture

Types and functions to manage information on CPU microarchitectures.

exception archspec.cpu.microarchitecture.ArchspecError

Base class for errors within archspec

exception archspec.cpu.microarchitecture.InvalidCompilerVersion

Raised when an invalid format is used for compiler versions in archspec.

class archspec.cpu.microarchitecture.Microarchitecture(name, parents, vendor, features, compilers, generation=0)

Represents a specific CPU micro-architecture.

Parameters:

  • name (str) – name of the micro-architecture (e.g. skylake).

  • parents (list) – list of parents micro-architectures, if any. Parenthood is considered by cpu features and not chronologically. As such each micro-architecture is compatible with its ancestors. For example “skylake”, which has “broadwell” as a parent, supports running binaries optimized for “broadwell”.

  • vendor (str) – vendor of the micro-architecture

  • features (set of str) – supported CPU flags. Note that the semantic of the flags in this field might vary among architectures, if at all present. For instance x86_64 processors will list all the flags supported by a given CPU while Arm processors will list instead only the flags that have been added on top of the base model for the current micro-architecture.

  • compilers (dict) –

    compiler support to generate tuned code for this micro-architecture. This dictionary has as keys names of supported compilers, while values are list of dictionaries with fields:

    • name: name of the micro-architecture according to the

      compiler. This is the name passed to the -march option or similar. Not needed if the name is the same as that passed in as argument above.

    • versions: versions that support this micro-architecture.

  • generation (int) – generation of the micro-architecture, if relevant.

property ancestors

All the ancestors of this microarchitecture.

property family

Returns the architecture family a given target belongs to

feature_aliases = <archspec.cpu.schema.LazyDictionary object>

Aliases for micro-architecture’s features

static from_dict(data) → Microarchitecture

Construct a microarchitecture from a dictionary representation.

property generic

Returns the best generic architecture that is compatible with self

optimization_flags(compiler, version)

Returns a string containing the optimization flags that needs to be used to produce code optimized for this micro-architecture.

The version is expected to be a string of dot separated digits.

If there is no information on the compiler passed as argument the function returns an empty string. If it is known that the compiler version we want to use does not support this architecture the function raises an exception.

Parameters:

  • compiler (str) – name of the compiler to be used

  • version (str) – version of the compiler to be used

Raises:

  • UnsupportedMicroarchitecture – if the requested compiler does not support this micro-architecture.

  • ValueError – if the version doesn’t match the expected format

to_dict()

Returns a dictionary representation of this object.

archspec.cpu.microarchitecture.TARGETS = <archspec.cpu.schema.LazyDictionary object>

Dictionary of known micro-architectures

exception archspec.cpu.microarchitecture.UnsupportedMicroarchitecture

Raised if a compiler version does not support optimization for a given micro-architecture.

archspec.cpu.microarchitecture.coerce_target_names(func)

Decorator that automatically converts a known target name to a proper Microarchitecture object.

archspec.cpu.microarchitecture.generic_microarchitecture(name)

Returns a generic micro-architecture with no vendor and no features.

Parameters:

name (str) – name of the micro-architecture

archspec.cpu.microarchitecture.version_components(version)

Decomposes the version passed as input in version number and suffix and returns them.

If the version number or the suffix are not present, an empty string is returned.

Parameters:

version (str) – version to be decomposed into its components

archspec.cpu.schema

Global objects with the content of the microarchitecture JSON file and its schema

archspec.cpu.schema.CPUID_JSON = <archspec.cpu.schema.LazyDictionary object>

Information on how to call ‘cpuid’ to get information on the HOST CPU

archspec.cpu.schema.CPUID_JSON_SCHEMA = <archspec.cpu.schema.LazyDictionary object>

JSON schema for cpuid.json, loaded on first access

archspec.cpu.schema.DIR_FROM_ENVIRONMENT = 'ARCHSPEC_CPU_DIR'

Environment variable that might point to a directory with a user defined JSON file

archspec.cpu.schema.EXTENSION_DIR_FROM_ENVIRONMENT = 'ARCHSPEC_EXTENSION_CPU_DIR'

Environment variable that might point to a directory with extensions to JSON files

class archspec.cpu.schema.LazyDictionary(factory, *args, **kwargs)

Lazy dictionary that gets constructed on first access to any object key

Parameters:

factory (callable) – factory function to construct the dictionary

property data

Returns the lazily constructed dictionary

archspec.cpu.schema.TARGETS_JSON = <archspec.cpu.schema.LazyDictionary object>

In memory representation of the data in microarchitectures.json, loaded on first access

archspec.cpu.schema.TARGETS_JSON_SCHEMA = <archspec.cpu.schema.LazyDictionary object>

JSON schema for microarchitectures.json, loaded on first access