metaheuristic_designer.simple package#

Submodules#

Module contents#

Ready-to-run wrappers that build complete algorithms from a few hyperparameters.

genetic_algorithm_binary(objfunc, mutated_bits=1, population_size=100, encoding=None, rng=None, **kwargs)[source]#

Genetic Algorithm for binary-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

mutated_bitsint, optional

Number of bits flipped per mutation (default 1).

population_sizeint, optional

Population size (default 100).

encodingEncoding, optional

Encoding; defaults to TypeCastEncoding (int → bool).

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • mutated_bits (int)

  • population_size (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

genetic_algorithm_permutation(objfunc, swapped_positions=2, population_size=100, encoding=None, rng=None, **kwargs)[source]#

Genetic Algorithm for permutation-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

swapped_positionsint, optional

Number of positions swapped per mutation (default 2).

population_sizeint, optional

Population size (default 100).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • swapped_positions (int)

  • population_size (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

genetic_algorithm_discrete(objfunc, resampled_components=1, population_size=100, encoding=None, rng=None, **kwargs)[source]#

Genetic Algorithm for integer-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

resampled_componentsint, optional

Number of components resampled per mutation (default 1).

population_sizeint, optional

Population size (default 100).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • resampled_components (int)

  • population_size (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

genetic_algorithm_real(objfunc, mutation_strength=0.01, mutated_components=1, population_size=100, encoding=None, rng=None, **kwargs)[source]#

Genetic Algorithm for real-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

mutation_strengthfloat, optional

Standard deviation of Gaussian mutation (default 1e-2).

mutated_componentsint, optional

Number of components mutated per individual (default 1).

population_sizeint, optional

Population size (default 100).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • mutation_strength (float)

  • mutated_components (int)

  • population_size (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

hill_climb_binary(objfunc, mutated_bits=1, encoding=None, rng=None, **kwargs)[source]#

Hill Climbing for binary-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

mutated_bitsint, optional

Number of bits flipped per mutation (default 1).

encodingEncoding, optional

Encoding; defaults to TypeCastEncoding (int → bool).

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
hill_climb_permutation(objfunc, swapped_positions=2, encoding=None, rng=None, **kwargs)[source]#

Hill Climbing for permutation-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

swapped_positionsint, optional

Number of positions swapped per mutation (default 2).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • swapped_positions (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

hill_climb_discrete(objfunc, resampled_components=1, encoding=None, rng=None, **kwargs)[source]#

Hill Climbing for integer-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

resampled_componentsint, optional

Number of components resampled per mutation (default 1).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • resampled_components (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

hill_climb_real(objfunc, mutation_strength=0.01, mutated_components=1, encoding=None, rng=None, **kwargs)[source]#

Hill Climbing for real-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

mutation_strengthfloat, optional

Standard deviation of Gaussian mutation (default 1e-2).

mutated_componentsint, optional

Number of components mutated per individual (default 1).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • mutation_strength (float)

  • mutated_components (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

local_search_binary(objfunc, mutated_bits=1, samples_per_iteration=100, encoding=None, rng=None, **kwargs)[source]#

Local Search for binary-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

mutated_bitsint, optional

Number of bits flipped per mutation (default 1).

samples_per_iterationint, optional

Number of samples evaluated per iteration (default 100).

encodingEncoding, optional

Encoding; defaults to TypeCastEncoding (int → bool).

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • mutated_bits (int)

  • samples_per_iteration (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

local_search_permutation(objfunc, swapped_positions=2, samples_per_iteration=100, encoding=None, rng=None, **kwargs)[source]#

Local Search for permutation-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

swapped_positionsint, optional

Number of positions swapped per mutation (default 2).

samples_per_iterationint, optional

Number of samples evaluated per iteration (default 100).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • swapped_positions (int)

  • samples_per_iteration (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

local_search_discrete(objfunc, resampled_components=1, samples_per_iteration=100, encoding=None, rng=None, **kwargs)[source]#

Local Search for integer-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

resampled_componentsint, optional

Number of components resampled per mutation (default 1).

samples_per_iterationint, optional

Number of samples evaluated per iteration (default 100).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • resampled_components (int)

  • samples_per_iteration (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

local_search_real(objfunc, mutation_strength=0.01, mutated_components=1, samples_per_iteration=100, encoding=None, rng=None, **kwargs)[source]#

Local Search for real-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

mutation_strengthfloat, optional

Standard deviation of Gaussian mutation (default 1e-2).

mutated_componentsint, optional

Number of components mutated per individual (default 1).

samples_per_iterationint, optional

Number of samples evaluated per iteration (default 100).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • mutation_strength (float)

  • mutated_components (int)

  • samples_per_iteration (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

particle_swarm_binary(objfunc, population_size=100, w=0.7, c1=1.5, c2=1.5, encoding=None, rng=None, **kwargs)[source]#

Particle Swarm optimization for binary-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

population_sizeint, optional

Swarm size (default 100).

wfloat, optional

Inertia weight (default 0.7).

c1float, optional

Cognitive acceleration coefficient (default 1.5).

c2float, optional

Social acceleration coefficient (default 1.5).

encodingEncoding, optional

Encoding; defaults to SigmoidEncoding.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • population_size (int)

  • w (float)

  • c1 (float)

  • c2 (float)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

particle_swarm_discrete(objfunc, population_size=100, w=0.7, c1=1.5, c2=1.5, encoding=None, rng=None, **kwargs)[source]#

Particle Swarm optimization for integer-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

population_sizeint, optional

Swarm size (default 100).

wfloat, optional

Inertia weight (default 0.7).

c1float, optional

Cognitive acceleration coefficient (default 1.5).

c2float, optional

Social acceleration coefficient (default 1.5).

encodingEncoding, optional

Encoding; defaults to TypeCastEncoding (float → int).

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • population_size (int)

  • w (float)

  • c1 (float)

  • c2 (float)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

particle_swarm_real(objfunc, population_size=100, w=0.7, c1=1.5, c2=1.5, encoding=None, rng=None, **kwargs)[source]#

Particle Swarm Optimization for real-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

population_sizeint, optional

Swarm size (default 100).

wfloat, optional

Inertia weight (default 0.7).

c1float, optional

Cognitive acceleration coefficient (default 1.5).

c2float, optional

Social acceleration coefficient (default 1.5).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • population_size (int)

  • w (float)

  • c1 (float)

  • c2 (float)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

random_search_binary(objfunc, encoding=None, rng=None, **kwargs)[source]#

Random Search for binary-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

encodingEncoding, optional

Encoding; defaults to TypeCastEncoding (int → bool).

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
random_search_permutation(objfunc, encoding=None, rng=None, **kwargs)[source]#

Random Search for permutation-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
random_search_discrete(objfunc, encoding=None, rng=None, **kwargs)[source]#

Random Search for integer-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
random_search_real(objfunc, encoding=None, rng=None, **kwargs)[source]#

Random Search for real-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
evolution_strategy_binary(objfunc, mutated_bits=1, population_size=100, offspring_size=500, elitist=False, encoding=None, rng=None, **kwargs)[source]#

Evolution Strategy for binary-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

mutated_bitsint, optional

Number of bits flipped per mutation (default 1).

population_sizeint, optional

Population size (default 100).

offspring_sizeint, optional

Number of offspring per generation (default 500).

elitistbool, optional

If True, use (μ+λ) selection; otherwise (μ,λ).

encodingEncoding, optional

Encoding; defaults to TypeCastEncoding (int → bool).

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • mutated_bits (int)

  • population_size (int)

  • offspring_size (int)

  • elitist (bool)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

evolution_strategy_permutation(objfunc, swapped_positions=2, population_size=100, offspring_size=500, elitist=False, encoding=None, rng=None, **kwargs)[source]#

Evolution Strategy for permutation-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

swapped_positionsint, optional

Number of positions swapped per mutation (default 2).

population_sizeint, optional

Population size (default 100).

offspring_sizeint, optional

Number of offspring per generation (default 500).

elitistbool, optional

If True, use (μ+λ) selection; otherwise (μ,λ).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • swapped_positions (int)

  • population_size (int)

  • offspring_size (int)

  • elitist (bool)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

evolution_strategy_discrete(objfunc, resampled_components=1, population_size=100, offspring_size=500, elitist=False, encoding=None, rng=None, **kwargs)[source]#

Evolution Strategy for integer-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

resampled_componentsint, optional

Number of components resampled per mutation (default 1).

population_sizeint, optional

Population size (default 100).

offspring_sizeint, optional

Number of offspring per generation (default 500).

elitistbool, optional

If True, use (μ+λ) selection; otherwise (μ,λ).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • resampled_components (int)

  • population_size (int)

  • offspring_size (int)

  • elitist (bool)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

evolution_strategy_real(objfunc, mutation_strength=0.01, mutated_components=1, population_size=100, offspring_size=500, elitist=False, encoding=None, rng=None, **kwargs)[source]#

Evolution Strategy for integer-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

resampled_componentsint, optional

Number of components resampled per mutation (default 1).

population_sizeint, optional

Population size (default 100).

offspring_sizeint, optional

Number of offspring per generation (default 500).

elitistbool, optional

If True, use (μ+λ) selection; otherwise (μ,λ).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • mutation_strength (float)

  • mutated_components (int)

  • population_size (int)

  • offspring_size (int)

  • elitist (bool)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

differential_evolution_binary(objfunc, population_size=100, F=0.8, Cr=0.9, de_operator_name='de/rand/1', encoding=None, rng=None, **kwargs)[source]#

Differential Evolution for binary-encoded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

population_sizeint, optional

Population size (default 100).

Ffloat, optional

Mutation scale factor (default 0.8).

Crfloat, optional

Crossover probability (default 0.9).

de_operator_namestr, optional

DE variant (default "de/rand/1").

encodingEncoding, optional

Encoding; defaults to SigmoidEncoding.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • population_size (int)

  • F (float)

  • Cr (float)

  • de_operator_name (str)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

differential_evolution_discrete(objfunc, population_size=100, F=0.8, Cr=0.9, de_operator_name='de/rand/1', encoding=None, rng=None, **kwargs)[source]#

Differential Evolution for integer-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

population_sizeint, optional

Population size (default 100).

Ffloat, optional

Mutation scale factor (default 0.8).

Crfloat, optional

Crossover probability (default 0.9).

de_operator_namestr, optional

DE variant (default "de/rand/1").

encodingEncoding, optional

Encoding; defaults to TypeCastEncoding (float → int).

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • population_size (int)

  • F (float)

  • Cr (float)

  • de_operator_name (str)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

differential_evolution_real(objfunc, population_size=100, F=0.8, Cr=0.9, de_operator_name='de/rand/1', encoding=None, rng=None, **kwargs)[source]#

Differential Evolution for real-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimizes.

population_sizeint, optional

Population size (default 100).

Ffloat, optional

Mutation scale factor (default 0.8).

Crfloat, optional

Crossover probability (default 0.9).

de_operator_namestr, optional

DE variant (default "de/rand/1").

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • population_size (int)

  • F (float)

  • Cr (float)

  • de_operator_name (str)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

simulated_annealing_binary(objfunc, mutated_bits=1, initial_temperature=1.0, alpha=0.997, iterations=100, encoding=None, rng=None, **kwargs)[source]#

Simulated Annealing for binary-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

mutated_bitsint, optional

Number of bits flipped per mutation (default 1).

initial_temperaturefloat, optional

Starting temperature (default 1.0).

alphafloat, optional

Cooling factor per iteration (default 0.997).

iterationsint, optional

Number of iterations at constant temperature (default 100).

encodingEncoding, optional

Encoding; defaults to TypeCastEncoding (int → bool).

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • mutated_bits (int)

  • initial_temperature (float)

  • alpha (float)

  • iterations (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

simulated_annealing_permutation(objfunc, swapped_positions=2, initial_temperature=1.0, alpha=0.997, iterations=100, encoding=None, rng=None, **kwargs)[source]#

Simulated Annealing for permutation-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

swapped_positionsint, optional

Number of positions swapped per mutation (default 2).

initial_temperaturefloat, optional

Starting temperature (default 1.0).

alphafloat, optional

Cooling factor per iteration (default 0.997).

iterationsint, optional

Number of iterations at constant temperature (default 100).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • swapped_positions (int)

  • initial_temperature (float)

  • alpha (float)

  • iterations (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

simulated_annealing_discrete(objfunc, resampled_components=1, initial_temperature=1.0, alpha=0.997, iterations=100, encoding=None, rng=None, **kwargs)[source]#

Simulated Annealing for integer-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

resampled_componentsint, optional

Number of components resampled per mutation (default 1).

initial_temperaturefloat, optional

Starting temperature (default 1.0).

alphafloat, optional

Cooling factor per iteration (default 0.997).

iterationsint, optional

Number of iterations at constant temperature (default 100).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • resampled_components (int)

  • initial_temperature (float)

  • alpha (float)

  • iterations (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

simulated_annealing_real(objfunc, mutation_strength=0.01, mutated_components=1, initial_temperature=1.0, alpha=0.997, iterations=100, encoding=None, rng=None, **kwargs)[source]#

Simulated Annealing for real-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

mutation_strengthfloat, optional

Standard deviation of Gaussian mutation (default 1e-2).

mutated_componentsint, optional

Number of components mutated per individual (default 1).

initial_temperaturefloat, optional

Starting temperature (default 1.0).

alphafloat, optional

Cooling factor per iteration (default 0.997).

iterationsint, optional

Number of iterations at constant temperature (default 100).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters:
  • objfunc (ObjectiveFunc)

  • mutation_strength (float)

  • mutated_components (int)

  • initial_temperature (float)

  • alpha (float)

  • iterations (int)

  • encoding (Encoding | None)

  • rng (int | Generator | None)

bayesian_optimization_binary(objfunc, population_size=50, encoding=None, rng=None, **kwargs)[source]#

Bayesian optimization for binary-coded vectors (not supported yet).

Return type:

Algorithm

Parameters:
bayesian_optimization_discrete(objfunc, population_size=50, encoding=None, rng=None, **kwargs)[source]#

Bayesian optimization for integer-coded vectors (not supported yet).

Return type:

Algorithm

Parameters:
bayesian_optimization_real(objfunc, population_size=50, encoding=None, rng=None, **kwargs)[source]#

Bayesian optimization for real-coded vectors.

Return type:

Algorithm

Parameters:
objfuncObjectiveFunc

The objective function to optimize.

population_sizeint, optional

Number of individuals in the initial population (default 50).

encodingEncoding, optional

Encoding applied to the genotype.

rngRNGLike, optional

Random seed or generator.

**kwargs

Forwarded to Algorithm.

Parameters: