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: str, parents: List[Microarchitecture], vendor: str, features: Set[str], compilers: Dict[str, List[Dict[str, str]]], generation: int = 0, cpu_part: str = '')

A specific CPU micro-architecture

property ancestors: List[Microarchitecture]: All the ancestors of this microarchitecture.

property family: Microarchitecture: 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: Microarchitecture: Returns the best generic architecture that is compatible with self

optimization_flags(compiler: str, version: str) → str

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 an 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 – name of the compiler to be used
version – 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() → Dict[str, Any]: Returns a dictionary representation of this object.

tree(fp: ~typing.IO[str] = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, indent: int = 2) → None: Format the partial order of this microarchitecture’s ancestors as a tree.

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: str) → Microarchitecture

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

Parameters:: name – name of the micro-architecture

archspec.cpu.host() → Microarchitecture: Detects the host micro-architecture and returns it.

archspec.cpu.version_components(version: str) → Tuple[str, str]

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 – version to be decomposed into its components

archspec.cpu.why_not(target_name: str) → str

Returns a human-readable explanation of why the given target was not chosen as the host.

Parameters:: target_name – name of the target micro-architecture to explain.
Returns:: A human-readable string. Never raises; if the target is unknown the string describes the problem.

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: Dict[str, Callable[[Microarchitecture, Microarchitecture], bool]] = {'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 the 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() → Microarchitecture: 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, cpu_part: str = '') → 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.detect.why_not(target_name: str) → str

Returns a human-readable explanation of why the given target was not chosen as the host.

Parameters:: target_name – name of the target micro-architecture to explain.
Returns:: A human-readable string. Never raises; if the target is unknown the string describes the problem.

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: str, parents: List[Microarchitecture], vendor: str, features: Set[str], compilers: Dict[str, List[Dict[str, str]]], generation: int = 0, cpu_part: str = '')

A specific CPU micro-architecture

property ancestors: List[Microarchitecture]: All the ancestors of this microarchitecture.

property family: Microarchitecture: 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: Microarchitecture: Returns the best generic architecture that is compatible with self

optimization_flags(compiler: str, version: str) → str

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 an 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 – name of the compiler to be used
version – 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() → Dict[str, Any]: Returns a dictionary representation of this object.

tree(fp: ~typing.IO[str] = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, indent: int = 2) → None: Format the partial order of this microarchitecture’s ancestors as a tree.

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: str) → Microarchitecture

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

Parameters:: name – name of the micro-architecture

archspec.cpu.microarchitecture.version_components(version: str) → Tuple[str, str]

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 – 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