lenskit.config#

LensKit general configuration

Submodules#

common

Mixins with commonly-used component configuration capabilities.

Classes#

LenskitSettings

Definition of LensKit settings.

MachineSettings

Definition for a single machine.

ParallelSettings

Configuration for LensKit's parallel processing. These settings are in the

PowerQueries

Queries for requesting power consumption data from Prometheus.

PrometheusSettings

Prometheus configuration settings.

RandomSettings

Random number generator configuration.

TuneSettings

LensKit hyperparameter tuning settings.

Functions#

load_config_data(…)

General-purpose function to automatically load configuration data and

locate_configuration_root(*[, cwd, ...])

Search for a configuration root containing a lenskit.toml file.

lenskit_config()

Get the LensKit configuration.

configure(…)

Initialize LensKit configuration.

Package Contents#

lenskit.config.load_config_data(path: pathlib.Path | os.PathLike[str], model: None = None) → pydantic.JsonValue#
lenskit.config.load_config_data(path: pathlib.Path | os.PathLike[str], model: type[M]) → M

General-purpose function to automatically load configuration data and optionally validate with a model.

Parameters:

  • path – The path to the configuration file.

  • model – The Pydantic model class to validate.

lenskit.config.locate_configuration_root(*, cwd=None, abort_at_pyproject=True, abort_at_gitroot=True)#

Search for a configuration root containing a lenskit.toml file.

This searches for a lenskit.toml file, beginning in the current working directory (or the alternate cwd if provided), and searching upward until one is found. Search stops if a pyproject.toml file or .git directory is found without encountering lenskit.toml.

Parameters:
Return type:

pathlib.Path | None

class lenskit.config.LenskitSettings#

Bases: pydantic_settings.BaseSettings

Definition of LensKit settings.

LensKit supports loading various settings from configuration files and the environment as a consistent way to control LensKit’s various control surfaces.

Stability:

Experimental

model_config#
random: RandomSettings#

Random number generator configuration.

parallel: ParallelSettings#
machine: str | None = None#

The name of the machine running experiments.

This is usually set in lenskit.local.toml or the LK_MACHINE environment variable.

prometheus: PrometheusSettings#

Prometheus settings for task metric collection.

machines: dict[str, MachineSettings]#

Description of different machines used in the experiment(s), to support things like collecting power metrics.

tuning: TuneSettings#

LensKit tuning settings.

property current_machine: MachineSettings | None#
Return type:

MachineSettings | None

classmethod settings_customise_sources(settings_cls, init_settings, env_settings, dotenv_settings, file_secret_settings)#
finish_setup()#

Finalize settings, resolving default values etc. as needed.

class lenskit.config.MachineSettings#

Bases: pydantic.BaseModel

Definition for a single machine.

A “machine” is a computer (or cluster) that is in use for running LensKit experiments. Many users won’t use this, but if you want to use the power consumption monitoring, you will need to define how to measure power for the different machines in use.

description: str | None = None#

Short description for this machine.

power_queries: PowerQueries#

Prometheus queries to collect power metrics for this machine.

class lenskit.config.ParallelSettings#

Bases: pydantic_settings.BaseSettings

Configuration for LensKit’s parallel processing. These settings are in the [parallel] table in lenskit.toml.

See also

Configuring Parallelism

model_config#
num_cpus: int = 0#

The number of CPUs LensKit should consider using. This is auto-detected from the system environment, and should only be configured manually if you want to override LensKit’s CPU detection for some reason. Note that the auto-detected values do account for operating system scheduling affinities and CPU limits.

This value is not used directly as a limit, but is used to derive the default values for the other concurrency controls (threads, etc.).

use_ray: bool = False#

Use Ray to parallelize batch operations, hyperparameter tuning, etc.

num_batch_jobs: int = 0#

Number of batch inference jobs to run in parallel. Can be overridden with the LK_NUM_BATCH_JOBS environment variable.

num_procs: int = 0#

Number of processes to use.

num_threads: int = 0#

Number of threads to use. Can be overridden with the LK_NUM_THREADS environment variable. Specify -1 to use all available threads.

num_backend_threads: int = 0#

Number of threads for compute backends to use. Can be overridden with the LK_NUM_BACKEND_THREADS environment variable. Specify -1 to leave threading limits unmodified.

property total_threads#
resolve_defaults()#

Resolve default values for thread/process counts.

env_vars()#

Get the parallel configuration as a set of environment variables to configure a child process. The set also includes OMP_NUM_THREADS and related variables for BLAS and MKL to configure OMP early.

Return type:

dict[str, str]

class lenskit.config.PowerQueries#

Bases: TypedDict

Queries for requesting power consumption data from Prometheus.

Each entry is a Python format string (for str.format()), that will be used to format a dictionary {"elapsed": time_ms}. The result should be a valid Prometheus query that returns the power consumption in Joules (watt seconds) over the last time_ms milliseconds.

system: str#

Total (chassis or system) power consumption.

cpu: str#

CPU power consumption.

gpu: str#

GPU power consumption.

class lenskit.config.PrometheusSettings#

Bases: pydantic.BaseModel

Prometheus configuration settings.

LensKit’s task logging supports querying Prometheus for task-related metrics such as power consumption.

url: str | None = None#
class lenskit.config.RandomSettings#

Bases: pydantic.BaseModel

Random number generator configuration.

seed: int | None = None#

The root RNG seed.

class lenskit.config.TuneSettings#

Bases: pydantic.BaseModel

LensKit hyperparameter tuning settings.

jobs: int | None = None#

Number of allowed hyperparameter tuning jobs.

gpu_mult: Annotated[float, Gt(0), Le(1.0)] = 1.0#

Multiplier for tuning job GPU requirements. This is to coarsely adapt GPU requirements from configuration files to the local machine. If a tuning specificataion requires 1 GPU, but your machine has enough capacity to run two jobs in parallel on a single GPU, you can set this to 0.5 to modify the tuning jobs to require 0.5 GPUs each.

max_points: int | None = None#

Maximum number of search points for hyperparameter tuning.

lenskit.config.lenskit_config()#

Get the LensKit configuration.

If no configuration has been specified, returns a default settings object.

Return type:

_schema.LenskitSettings

lenskit.config.configure(cfg_dir: pathlib.Path | None = None) → _schema.LenskitSettings#
lenskit.config.configure(cfg_dir: pathlib.Path | None = None, *, settings_cls: type[SettingsClass]) → SettingsClass
lenskit.config.configure(settings: _schema.LenskitSettings, /) → _schema.LenskitSettings

Initialize LensKit configuration.

LensKit does not automatically read configuration files — if this function is never called, then configuration will entirely be done through defaults and environment varibles.

This function will automatically configure the global RNG, if a seed is specified. It does not configure logging.

Parameters:

  • cfg_dir – The directory in which to look for configuration files.. If not provided, uses the current directory.

  • settings_cls – The base LensKit settings class. Rarely used, only needed if a project wants to to extend LensKit settings with their own settings.

Returns:

The configured LensKit settings.

Exported Aliases#

exception lenskit.config.ConfigWarning#

Re-exported alias for lenskit.diagnostics.ConfigWarning.

lenskit.config.get_logger()#

Re-exported alias for lenskit.logging.get_logger().

lenskit.config.init_global_rng()#

Re-exported alias for lenskit.random.init_global_rng().