The lincs package

This is the main module for the lincs library. It contains general information (version, GPU availability, etc.) and items of general usage (e.g. the exception for invalid data).

lincs.__version__: str

The version of lincs, as a string in Version Specifier format.

lincs.has_gpu: bool

True if lincs was built with CUDA support.

exception lincs.DataValidationException

Raised by constructors when called with invalid data. ex.args[0] gives a human-readable description of the error.

exception lincs.LearningFailureException

Raised by learning algorithms when they can’t reach their objective.

class lincs.UniformRandomBitsGenerator

Random number generator.

__call__() → int

Generate the next pseudo-random integer.

The lincs.classification module

This module contains everything related to classification.

class lincs.classification.Criterion

A classification criterion, to be used in a classification Problem.

__init__(name: str, values: RealValues)

Constructor for real-valued criterion.

__init__(name: str, values: IntegerValues)

Constructor for integer-valued criterion.

__init__(name: str, values: EnumeratedValues)

Constructor for criterion with enumerated values.

property name: str

The name of the criterion.

class ValueType

The different types of values for a criterion.

class property real: ValueType

Real values.

class property integer: ValueType

Integer values.

class property enumerated: ValueType

Enumerated values.

property value_type: ValueType

The type of values for this criterion.

property is_real: bool

True if the criterion is real-valued.

property is_integer: bool

True if the criterion is integer-valued.

property is_enumerated: bool

True if the criterion takes enumerated values.

class PreferenceDirection

What values are preferred for a criterion.

class property increasing: PreferenceDirection

For criteria where higher numerical values are known to be better.

class property decreasing: PreferenceDirection

For criteria where lower numerical values are known to be better.

class property single_peaked: PreferenceDirection

For criteria where intermediate numerical values are known to be better.

class property isotone: PreferenceDirection

Synonym for increasing.

class property antitone: PreferenceDirection

Synonym for decreasing.

class RealValues

Descriptor of the real values allowed for a criterion.

__init__(preference_direction: PreferenceDirection, min_value: float, max_value: float)

Parameters map exactly to attributes with identical names.

property min_value: float

The minimum value allowed for this criterion.

property max_value: float

The maximum value allowed for this criterion.

property preference_direction: PreferenceDirection

The preference direction for this criterion.

property is_increasing: bool

True if the criterion has increasing preference direction.

property is_decreasing: bool

True if the criterion has decreasing preference direction.

property is_single_peaked: bool

True if the criterion has single-peaked preference direction.

property real_values: RealValues

Descriptor of the real values allowed for this criterion, accessible if is_real.

class IntegerValues

Descriptor of the integer values allowed for a criterion.

__init__(preference_direction: PreferenceDirection, min_value: int, max_value: int)

Parameters map exactly to attributes with identical names.

property min_value: float

The minimum value allowed for this criterion.

property max_value: float

The maximum value allowed for this criterion.

property preference_direction: PreferenceDirection

The preference direction for this criterion.

property is_increasing: bool

True if the criterion has increasing preference direction.

property is_decreasing: bool

True if the criterion has decreasing preference direction.

property is_single_peaked: bool

True if the criterion has single-peaked preference direction.

property integer_values: IntegerValues

Descriptor of the integer values allowed for this criterion, accessible if is_integer.

class EnumeratedValues

Descriptor of the enumerated values allowed for a criterion.

__init__(ordered_values: list[str])

Parameters map exactly to attributes with identical names.

get_value_rank(value: str) → int

Get the rank of a given value.

property ordered_values: list[str]

The values for this criterion, from the worst to the best.

property enumerated_values: EnumeratedValues

Descriptor of the enumerated values allowed for this criterion, accessible if is_enumerated.

class lincs.classification.Category

A category of a classification Problem.

__init__(name: str)

Parameters map exactly to attributes with identical names.

property name: str

The name of this category.

class lincs.classification.Problem

A classification problem, with criteria and categories.

__init__(criteria: list[Criterion], ordered_categories: list[Category])

Parameters map exactly to attributes with identical names.

property criteria: list[Criterion]

The criteria of this problem.

property ordered_categories: list[Category]

The categories of this problem, from the worst to the best.

dump(out: object)

Dump the problem to the provided .write-supporting file-like object, in YAML format.

static load(in: object) → Problem

Load a problem from the provided .read-supporting file-like object, in YAML format.

JSON_SCHEMA: str

The JSON schema defining the format used by dump and load, as a string.

class lincs.classification.AcceptedValues

The values accepted by a model for a criterion.

__init__(values: RealThresholds)

Constructor for thresholds on a real-valued criterion.

__init__(values: IntegerThresholds)

Constructor for thresholds on an integer-valued criterion.

__init__(values: EnumeratedThresholds)

Constructor for thresholds on an enumerated criterion.

__init__(values: RealIntervals)

Constructor for intervals on a real-valued criterion.

__init__(values: IntegerIntervals)

Constructor for intervals on an integer-valued criterion.

property value_type: ValueType

The type of values for the corresponding criterion.

property is_real: bool

True if the corresponding criterion is real-valued.

property is_integer: bool

True if the corresponding criterion is integer-valued.

property is_enumerated: bool

True if the corresponding criterion takes enumerated values.

class Kind

The different kinds of descriptors for accepted values.

class property thresholds: Kind

A threshold for each category.

class property intervals: Kind

An interval for each category.

property kind: Kind

The kind of descriptor for these accepted values.

property is_thresholds: bool

True if the descriptor is a set of thresholds.

property is_intervals: bool

True if the descriptor is a set of intervals.

class RealThresholds

Descriptor for thresholds for an real-valued criterion.

__init__(thresholds: list[float | None])

Parameters map exactly to attributes with identical names.

property thresholds: list[float | None]

The thresholds for this descriptor.

property real_thresholds: RealThresholds

Descriptor of the real thresholds, accessible if is_real and is_thresholds.

class IntegerThresholds

Descriptor for thresholds for an integer-valued criterion.

__init__(thresholds: list[int | None])

Parameters map exactly to attributes with identical names.

property thresholds: list[int | None]

The thresholds for this descriptor.

property integer_thresholds: IntegerThresholds

Descriptor of the integer thresholds, accessible if is_integer and is_thresholds.

class EnumeratedThresholds

Descriptor for thresholds for a criterion taking enumerated values.

__init__(thresholds: list[str | None])

Parameters map exactly to attributes with identical names.

property thresholds: list[str | None]

The thresholds for this descriptor.

property enumerated_thresholds: EnumeratedThresholds

Descriptor of the enumerated thresholds, accessible if is_enumerated and is_thresholds.

class RealIntervals

Descriptor for intervals for an real-valued criterion.

__init__(intervals: list[tuple[float, float] | None])

Parameters map exactly to attributes with identical names.

property intervals: list[tuple[float, float] | None]

The intervals for this descriptor.

property real_intervals: RealIntervals

Descriptor of the real intervals, accessible if is_real and is_intervals.

class IntegerIntervals

Descriptor for intervals for an integer-valued criterion.

__init__(intervals: list[tuple[int, int] | None])

Parameters map exactly to attributes with identical names.

property intervals: list[tuple[int, int] | None]

The intervals for this descriptor.

property integer_intervals: IntegerIntervals

Descriptor of the integer intervals, accessible if is_integer and is_intervals.

class lincs.classification.SufficientCoalitions

The coalitions of sufficient criteria to accept an alternative in a category.

__init__(weights: Weights)

Constructor for sufficient coalitions defined by weights.

__init__(roots: Roots)

Constructor for sufficient coalitions defined by roots.

class Kind

The different kinds of descriptors for sufficient coalitions.

class property weights: Kind

For sufficient coalitions described by criterion weights.

class property roots: Kind

For sufficient coalitions described by the roots of their upset.

property kind: Kind

The kind of descriptor for these sufficient coalitions.

property is_weights: bool

True if the descriptor is a set of weights.

property is_roots: bool

True if the descriptor is a set of roots.

class Weights

Descriptor for sufficient coalitions defined by weights.

__init__(criterion_weights: list[float])

Parameters map exactly to attributes with identical names.

property criterion_weights: list[float]

The weights for each criterion.

property weights: Weights

Descriptor of the weights, accessible if is_weights.

class Roots

Descriptor for sufficient coalitions defined by roots.

__init__(problem: Problem, upset_roots: list[list[int]])

Parameters map exactly to attributes with identical names.

property upset_roots: list[list[int]]

The roots of the upset of sufficient coalitions.

property roots: Roots

Descriptor of the roots, accessible if is_roots.

class lincs.classification.Model

An NCS classification model.

__init__(problem: Problem, accepted_values: list[AcceptedValues], sufficient_coalitions: list[SufficientCoalitions])

The Model being initialized must correspond to the given Problem. Other parameters map exactly to attributes with identical names.

check_consistency_with(problem: Problem)

Raise DataValidationException if the model is not consistent with the provided problem.

property accepted_values: list[AcceptedValues]

The accepted values for each criterion.

property sufficient_coalitions: list[SufficientCoalitions]

The sufficient coalitions for each category.

dump(problem: Problem, out: object)

Dump the model to the provided .write-supporting file-like object, in YAML format.

static load(problem: Problem, in: object) → Model

Load a model for the provided Problem, from the provided .read-supporting file-like object, in YAML format.

JSON_SCHEMA: str

The JSON schema defining the format used by dump and load, as a string.

class lincs.classification.Performance

The performance of an alternative on a criterion.

__init__(performance: Real)

Constructor for a real-valued performance.

__init__(performance: Integer)

Constructor for an integer-valued performance.

__init__(performance: Enumerated)

Constructor for an enumerated performance.

property value_type: ValueType

The type of values for the corresponding criterion.

property is_real: bool

True if the corresponding criterion is real-valued.

property is_integer: bool

True if the corresponding criterion is integer-valued.

property is_enumerated: bool

True if the corresponding criterion takes enumerated values.

class Real

A performance for a real-valued criterion.

__init__(value: float)

Parameters map exactly to attributes with identical names.

property value: float

The numerical value of the real performance.

property real: Real

The real performance, accessible if is_real.

class Integer

A performance for an integer-valued criterion.

__init__(value: int)

Parameters map exactly to attributes with identical names.

property value: int

The numerical value of the integer performance.

property integer: Integer

The integer performance, accessible if is_integer.

class Enumerated

A performance for a criterion taking enumerated values.

__init__(value: str)

Parameters map exactly to attributes with identical names.

property value: str

The string value of the enumerated performance.

property enumerated: Enumerated

The enumerated performance, accessible if is_enumerated.

class lincs.classification.Alternative

An alternative, with its performance on each criterion, maybe classified.

__init__(name: str, profile: list[Performance], category_index: int | None = None)

Parameters map exactly to attributes with identical names.

property name: str

The name of the alternative.

property profile: list[Performance]

The performance profile of the alternative.

property category_index: int | None

The index of the category of the alternative, if it is classified.

class lincs.classification.Alternatives

A set of alternatives, maybe classified.

__init__(problem: Problem, alternatives: list[Alternative])

The Alternatives being initialized must correspond to the given Problem. Other parameters map exactly to attributes with identical names.

check_consistency_with(problem: Problem)

Raise DataValidationException if these alternatives are not consistent with the provided problem.

property alternatives: list[Alternative]

The Alternative objects in this set.

dump(problem: Problem, out: object)

Dump the set of alternatives to the provided .write-supporting file-like object, in CSV format.

static load(problem: Problem, in: object) → Alternatives

Load a set of alternatives (classified or not) from the provided .read-supporting file-like object, in CSV format.

lincs.classification.generate_problem(criteria_count: int, categories_count: int, random_seed: int, normalized_min_max: bool = True, allowed_preference_directions: list[PreferenceDirection] = [PreferenceDirection.increasing], allowed_value_types: list[ValueType] = [ValueType.real]) → Problem

Generate a Problem with criteria_count criteria and categories_count categories.

lincs.classification.generate_mrsort_model(problem: Problem, random_seed: int, fixed_weights_sum: float | None = None) → Model

Generate an MR-Sort model for the provided Problem.

exception lincs.classification.BalancedAlternativesGenerationException

Raised by generate_alternatives when it fails to find alternatives to balance the categories.

lincs.classification.generate_alternatives(problem: Problem, model: Model, alternatives_count: int, random_seed: int, max_imbalance: float | None = None) → Alternatives

Generate a set of alternatives_count pseudo-random alternatives for the provided Problem, classified according to the provided Model.

lincs.classification.misclassify_alternatives(problem: Problem, alternatives: Alternatives, count: int, random_seed: int)

Misclassify count alternatives from the provided Alternatives.

class lincs.classification.LearnUcncsByMaxSatByCoalitionsUsingEvalmaxsat

The “max-SAT by coalitions” approach to learn Uc-NCS models.

__init__(problem: Problem, learning_set: Alternatives, nb_minimize_threads: int = 0, timeout_fast_minimize: int = 60, coef_minimize_time: int = 2)

Constructor.

perform() → Model

Actually perform the learning and return the learned model.

class lincs.classification.LearnUcncsByMaxSatBySeparationUsingEvalmaxsat

The “max-SAT by separation” approach to learn Uc-NCS models.

__init__(problem: Problem, learning_set: Alternatives, nb_minimize_threads: int = 0, timeout_fast_minimize: int = 60, coef_minimize_time: int = 2)

Constructor.

perform() → Model

Actually perform the learning and return the learned model.

class lincs.classification.LearnUcncsBySatByCoalitionsUsingMinisat

The “SAT by coalitions” approach to learn Uc-NCS models.

__init__(problem: Problem, learning_set: Alternatives)

Constructor.

perform() → Model

Actually perform the learning and return the learned model.

class lincs.classification.LearnUcncsBySatBySeparationUsingMinisat

The “SAT by separation” approach to learn Uc-NCS models.

__init__(problem: Problem, learning_set: Alternatives)

Constructor.

perform() → Model

Actually perform the learning and return the learned model.

class lincs.classification.PreprocessedLearningSet

A representation of a learning set with its data normalized as ranks (unsigned integers).

__init__(problem: Problem, learning_set: Alternatives)

Constructor, pre-processing the learning set into a simpler form for learning.

property criteria_count: int

Number of criteria in the Problem.

property categories_count: int

Number of categories in the Problem.

property boundaries_count: int

Number of boundaries in the Problem, i.e categories_count - 1.

property alternatives_count: int

Number of alternatives in the learning_set.

property single_peaked: list[bool]

Indexed by [criterion_index]. Whether each criterion is single-peaked or not.

property values_counts: list[int]

Indexed by [criterion_index]. Number of different values for each criterion, in the learning_set and min and max values for numerical criteria.

property performance_ranks: list[list[int]]

Indexed by [criterion_index][alternative_index]. Rank of each alternative in the learning_set for each criterion.

property assignments: list[int]

Indexed by [alternative_index]. Category index of each alternative in the learning_set.

class lincs.classification.LearnMrsortByWeightsProfilesBreed

The approach described in Olivier Sobrie’s PhD thesis to learn MR-Sort models.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_being_learned: ModelsBeingLearned, profiles_initialization_strategy: ProfilesInitializationStrategy, weights_optimization_strategy: WeightsOptimizationStrategy, profiles_improvement_strategy: ProfilesImprovementStrategy, breeding_strategy: BreedingStrategy, termination_strategy: TerminationStrategy, observers: list[Observer] = [])

Constructor accepting the strategies to use for each step of the learning.

class ModelsBeingLearned

Data shared by all the strategies used in this learning.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_count: int, random_seed: int)

Constructor, allocating but not initializing data about models about to be learned.

property models_count: int

The number of in-progress models for this learning.

property random_generators: list[UniformRandomBitsGenerator]

Indexed by [model_index]. Random number generators associated to each in-progress model.

property iteration_index: int

The index of the current iteration of the WPB algorithm.

property model_indexes: list[int]

Indexed by 0 to models_count - 1. Indexes of in-progress models ordered by increasing accuracy.

property weights: list[list[int]]

Indexed by [model_index][criterion_index]. The current MR-Sort weight of each criterion for each model.

property low_profile_ranks: list[list[list[int]]]

Indexed by [model_index][boundary_index][criterion_index]. The current rank of each low profile, for each model and criterion.

property high_profile_rank_indexes: list[unsigned]

Indexed by [criterion_index]. The index in high_profile_ranks, for each single-peaked criterion.

property high_profile_ranks: list[list[list[int]]]

Indexed by [model_index][boundary_index][high_profile_rank_indexes[criterion_index]]. The current rank of each high profile, for each model and single-peaked criterion.

property accuracies: list[int]

Indexed by [model_index]. Accuracy of each in-progress model.

get_best_accuracy() → int

Return the accuracy of the best model so far.

get_best_model() → Model

Return the best model so far.

get_model(model_index: int) → Model

Return the model at the given index.

recompute_accuracy(model_index: int)

Recompute the accuracy of the model at the given index.

class ProfilesInitializationStrategy

Abstract base class for profiles initialization strategies.

initialize_profiles(model_indexes_begin: int, model_indexes_end: int)

Method to override. Should initialize all low_profile_ranks and high_profile_ranks of models at indexes in [model_indexes[i] for i in range(model_indexes_begin, model_indexes_end)].

class WeightsOptimizationStrategy

Abstract base class for weights optimization strategies.

optimize_weights(model_indexes_begin: int, model_indexes_end: int)

Method to override. Should optimize weights of models at indexes in [model_indexes[i] for i in range(model_indexes_begin, model_indexes_end)].

class ProfilesImprovementStrategy

Abstract base class for profiles improvement strategies.

improve_profiles(model_indexes_begin: int, model_indexes_end: int)

Method to override. Should improve low_profile_ranks and high_profile_ranks of models at indexes in [model_indexes[i] for i in range(model_indexes_begin, model_indexes_end)].

class BreedingStrategy

Abstract base class for breeding strategies.

breed()

Method to override.

class TerminationStrategy

Abstract base class for termination strategies.

terminate() → bool

Method to override. Should return True if the learning should stop, False otherwise.

class Observer

Abstract base class for observation strategies.

after_iteration()

Method to override. Called after each iteration. Should not change anything in the learning data.

before_return()

Method to override. Called just before returning the learned model. Should not change anything in the learning data.

perform() → Model

Actually perform the learning and return the learned model.

class lincs.classification.InitializeProfilesForProbabilisticMaximalDiscriminationPowerPerCriterion

The profiles initialization strategy described in Olivier Sobrie’s PhD thesis.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_being_learned: ModelsBeingLearned)

Constructor. Keeps a reference to the learning data.

initialize_profiles(model_indexes_begin: int, model_indexes_end: int)

Overrides the base method.

class lincs.classification.OptimizeWeightsUsingAlglib

The weights optimization strategy described in Olivier Sobrie’s PhD thesis. The linear program is solved using AlgLib.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_being_learned: ModelsBeingLearned)

Constructor. Keeps a reference to the learning data.

optimize_weights(model_indexes_begin: int, model_indexes_end: int)

Overrides the base method.

class lincs.classification.OptimizeWeightsUsingGlop

The weights optimization strategy described in Olivier Sobrie’s PhD thesis. The linear program is solved using GLOP.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_being_learned: ModelsBeingLearned)

Constructor. Keeps a reference to the learning data.

optimize_weights(model_indexes_begin: int, model_indexes_end: int)

Overrides the base method.

class lincs.classification.ImproveProfilesWithAccuracyHeuristicOnCpu

The profiles improvement strategy described in Olivier Sobrie’s PhD thesis. Run on the CPU.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_being_learned: ModelsBeingLearned)

Constructor. Keeps a reference to the learning data.

improve_profiles(model_indexes_begin: int, model_indexes_end: int)

Overrides the base method.

class lincs.classification.ImproveProfilesWithAccuracyHeuristicOnGpu

The profiles improvement strategy described in Olivier Sobrie’s PhD thesis. Run on the CUDA-capable GPU.

__init__(preprocessed_learning_set: PreprocessedLearningSet, models_being_learned: ModelsBeingLearned)

Constructor. Keeps a reference to the learning data.

improve_profiles(model_indexes_begin: int, model_indexes_end: int)

Overrides the base method.

class lincs.classification.ReinitializeLeastAccurate

The breeding strategy described in Olivier Sobrie’s PhD thesis: re-initializes count in-progress models.

__init__(models_being_learned: ModelsBeingLearned, profiles_initialization_strategy: ProfilesInitializationStrategy, weights_optimization_strategy: WeightsOptimizationStrategy, count: int)

Constructor. Keeps references to the profiles initialization strategy and the learning data.

breed()

Overrides the base method.

class lincs.classification.TerminateAfterIterations

Termination strategy. Terminates the learning after a given number of iterations.

__init__(models_being_learned: ModelsBeingLearned, max_iterations_count: int)

Constructor. Keeps a reference to the learning data.

terminate() → bool

Overrides the base method.

class lincs.classification.TerminateAfterIterationsWithoutProgress

Termination strategy. Terminates the learning after a given number of iterations without progress.

__init__(models_being_learned: ModelsBeingLearned, max_iterations_count: int)

Constructor. Keeps a reference to the learning data.

terminate() → bool

Overrides the base method.

class lincs.classification.TerminateAfterSeconds

Termination strategy. Terminates the learning after a given duration.

__init__(max_seconds: float)

Constructor.

terminate() → bool

Overrides the base method.

class lincs.classification.TerminateAfterSecondsWithoutProgress

Termination strategy. Terminates the learning after a given duration without progress.

__init__(models_being_learned: ModelsBeingLearned, max_seconds: float)

Constructor. Keeps a reference to the learning data.

terminate() → bool

Overrides the base method.

class lincs.classification.TerminateAtAccuracy

Termination strategy. Terminates the learning when the best model reaches a given accuracy.

__init__(models_being_learned: ModelsBeingLearned, target_accuracy: int)

Constructor. Keeps a reference to the learning data.

terminate() → bool

Overrides the base method.

class lincs.classification.TerminateWhenAny

Termination strategy. Terminates the learning when one or more termination strategies decide to terminate.

__init__(termination_strategies: list[TerminationStrategy])

Constructor. Keeps references to each termination strategies.

terminate() → bool

Overrides the base method.

class lincs.classification.ClassificationResult

Return type for classify_alternatives.

property changed: int

Number of alternatives that were not in the same category before and after classification.

property unchanged: int

Number of alternatives that were in the same category before and after classification.

lincs.classification.classify_alternatives(problem: Problem, model: Model, alternatives: Alternatives) → ClassificationResult

Classify the provided Alternatives according to the provided Model.

lincs.classification.describe_model(problem: Problem, model: Model) → Iterable[str]

Generate a human-readable description of a classification model.

lincs.classification.describe_problem(problem: Problem) → Iterable[str]

Generate a human-readable description of a classification problem.

lincs.classification.visualize_model(problem: Problem, model: Model, alternatives: Iterable[Alternative], axes: matplotlib.axes._axes.Axes)

Create a visual representation of a classification model and classified alternatives, using Matplotlib.