Quick submission types · Vilvik docs

Quick submissions bring their own fitness function and GA parameter defaults. You pick a submission_type, pass that problem's inputs, and the service fills in the rest. There is no need to write or upload a fitness_func.

For a worked example using quick_binary_subset_sum, see API examples. For SDK usage, see Submissions.

The table below is generated from the running service, so it always matches what the API accepts.

Machine learning types: dataset and hyperparameters¶

The machine learning types tune model hyperparameters (Random Forest, XGBoost, SVM, K-Nearest Neighbors, Logistic Regression) or train neural-network weights (Keras and PyTorch) with a genetic algorithm.

Over the API these types run on a built-in dataset. Pass dataset_name as one of iris, breast_cancer, or random. The XOR type (quick_keras_xor_training) uses its own built-in data and takes no dataset_name. Training on your own uploaded data is available on the website, but it is not supported over the API or SDK yet.

The hyperparameter types take a nested hyperparameters object. Each entry names one hyperparameter and says whether to search a range or hold a value:

"hyperparameters": {
  "n_estimators": {"tune": true, "min": 50, "max": 150},
  "max_depth": {"fixed": 10}
}

Use {"tune": true, "min": a, "max": b} to search a range, or {"fixed": v} to pin a value. At least one hyperparameter must be tuned.

Here is a Random Forest run on iris that tunes n_estimators and holds max_depth fixed:

curl -X POST https://beta.vilvik.com/api/v1/submissions/ \
  -H "Authorization: Bearer $VILVIK_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "rfc on iris",
    "submission_type": "quick_sklearn_rfc_hyperparameters",
    "dataset_name": "iris",
    "hyperparameters": {
      "n_estimators": {"tune": true, "min": 50, "max": 150},
      "max_depth": {"fixed": 10}
    }
  }'

The SVM, K-Nearest Neighbors, and Logistic Regression types also take a kernel, weights, or solver choice respectively. The neural-network training types take num_layers, num_neurons (a list), and activation_function (a list of relu or sigmoid); the neural-network hyperparameter types take these inside hyperparameters. See each type's table below for the exact fields and limits.

2D Data Clustering¶

submission_type: quick_2d_clustering

Input	Type	Required	Notes
`num_clusters`	int	yes	Number of clusters to find (2 to 5). Min 2. Max 5.
`cluster_num_samples`	int	no	Samples per cluster when generating synthetic data (1 to 20). Required when data_points is not provided. Min 1. Max 20.
`data_points`	list	no	Explicit 2D points to cluster, each [x, y]. When given, cluster_num_samples is ignored.
`gene_type`	str	no
`num_generations`	int	no	Min 1.
`sol_per_pop`	int	no	Min 2.
`num_parents_mating`	int	no	Min 1.
`init_range_low`	float	no
`init_range_high`	float	no
`keep_elitism`	int	no	Min 0.

Bin Packing¶

submission_type: quick_bin_packing

Input	Type	Required	Notes
`item_names`	list	yes	Names of the items to pack (2 to 60).
`item_sizes`	list	yes	Size of each item (one per item).
`bin_capacity`	float	yes	Maximum total size a single bin can hold. Min 0.0001. Max 1000000000.0.
`penalty_weight`	float	no	Penalty applied per unit of capacity violation. Min 1.0.
`gene_type`	str	no
`num_generations`	int	no	Min 1.
`sol_per_pop`	int	no	Min 2.
`num_parents_mating`	int	no	Min 1.

Binary Subset Sum¶

submission_type: quick_binary_subset_sum

Input	Type	Required	Notes
`num_integers`	int	no	How many integers to generate when you do not supply them explicitly (5 to 20). Min 5. Max 20.
`integers`	list	no	The explicit list of integers to choose a subset from. Overrides num_integers when given.
`target`	int	yes	The sum the chosen subset should get closest to.
`gene_type`	str	no
`gene_space`	str	no
`num_generations`	int	no	Min 1.
`sol_per_pop`	int	no	Min 2.
`num_parents_mating`	int	no	Min 1.

KNN Classifier Hyperparameters¶

submission_type: quick_knn_classifier_hyperparameters

Input	Type	Required	Notes
`dataset_name`	str	no	Built-in dataset to use: iris, breast_cancer, or random.
`hyperparameters`	dict	yes	Map of hyperparameter name to a tune or fixed spec.
`num_generations`	int	no	Number of GA generations (default 5). Min 1.
`sol_per_pop`	int	no	Population size (default 10). Min 2.
`num_parents_mating`	int	no	Parents mating count (default 5). Min 1.
`weights`	str	no	KNN weighting: one of ('uniform', 'distance').

Keras Multi-Class Neural Network¶

submission_type: quick_keras_nn_training

Input	Type	Required	Notes
`dataset_name`	str	no	Built-in dataset: iris, breast_cancer, or random.
`num_layers`	int	yes	Number of hidden layers (1 to 20). Min 1. Max 20.
`num_neurons`	list	yes	Number of neurons per hidden layer (one int per layer).
`activation_function`	list	yes	Activation function per layer (one of: ['relu', 'sigmoid']).
`num_generations`	int	no	Number of GA generations (default 5). Min 1.
`sol_per_pop`	int	no	Population size (default 10). Min 2.
`num_parents_mating`	int	no	Parents mating count (default 5). Min 1.
`gene_type`	str	no	Gene type (default float).
`init_range_low`	float	no	Lower bound for initial weight values (default -1.0).
`init_range_high`	float	no	Upper bound for initial weight values (default 1.0).
`random_mutation_min_val`	float	no	Minimum mutation delta (default -1.0).
`random_mutation_max_val`	float	no	Maximum mutation delta (default 1.0).

Keras Multi-Class Neural Network Hyperparameters¶

submission_type: quick_keras_nn_hyperparameters

Input	Type	Required	Notes
`dataset_name`	str	no	Built-in dataset to use: iris, breast_cancer, or random.
`hyperparameters`	dict	yes	Map of hyperparameter name to a tune or fixed spec. Must include num_layers as a fixed integer (e.g. {"num_layers": {"fixed": 2}}). num_neurons and activation_function must both be tuned or both be fixed, with one entry per layer. Tunable scalars: batch_size (int 16-256), num_epochs (int 1-100), learning_rate (float 0.0001-0.1).
`num_generations`	int	no	Number of GA generations (default 5). Min 1.
`sol_per_pop`	int	no	Population size (default 10). Min 2.
`num_parents_mating`	int	no	Parents mating count (default 5). Min 1.

Keras XOR¶

submission_type: quick_keras_xor_training

Input	Type	Required	Notes
`num_layers`	int	yes	Number of hidden layers (1 to 20). Min 1. Max 20.
`num_neurons`	list	yes	Number of neurons per hidden layer (one int per layer).
`activation_function`	list	yes	Activation function per layer (one of: ['relu', 'sigmoid']).
`num_generations`	int	no	Number of GA generations (default 5). Min 1.
`sol_per_pop`	int	no	Population size (default 10). Min 2.
`num_parents_mating`	int	no	Parents mating count (default 5). Min 1.
`gene_type`	str	no	Gene type (default float).
`init_range_low`	float	no	Lower bound for initial weight values (default -1.0).
`init_range_high`	float	no	Upper bound for initial weight values (default 1.0).
`random_mutation_min_val`	float	no	Minimum mutation delta (default -1.0).
`random_mutation_max_val`	float	no	Maximum mutation delta (default 1.0).

Knapsack¶

submission_type: quick_knapsack

Input	Type	Required	Notes
`item_names`	list	yes	Names of the items to choose from (2 to 60).
`item_values`	list	yes	Value of each item (one per item).
`item_weights`	list	yes	Weight rows for each item (one row per item; each row has one weight per dimension).
`dimension_names`	list	yes	Names for each capacity dimension (1 to 5).
`dimension_capacities`	list	yes	Capacity limit for each dimension.
`penalty_weight`	float	no	Penalty applied per unit of constraint violation. Min 1.0.
`gene_type`	str	no
`gene_space`	str	no
`num_generations`	int	no	Min 1.
`sol_per_pop`	int	no	Min 2.
`num_parents_mating`	int	no	Min 1.

Linear Many-Objective (NSGA-III)¶

submission_type: quick_multi_objective_nsga3

Input	Type	Required	Notes
`num_objectives`	int	yes	Number of objectives (2 to 10). Min 2. Max 10.
`num_parameters`	int	yes	Number of parameters (genes) per solution (1 to 10). Min 1. Max 10.
`target`	list	yes	Target value for each objective, as a list of floats.
`objective_names`	list	no	Optional names for each objective (comma-separated or list).
`gene_type`	str	no
`num_generations`	int	no	Min 1.
`sol_per_pop`	int	no	Min 2.
`num_parents_mating`	int	no	Min 1.
`init_range_low`	float	no
`init_range_high`	float	no
`random_mutation_min_val`	float	no
`random_mutation_max_val`	float	no
`parent_selection_type`	str	no
`nsga3_num_divisions`	int	no	Number of divisions per objective axis for the NSGA-III reference points (a positive integer). Min 1.

Linear Multi Objective¶

submission_type: quick_multi_objective

Input	Type	Required	Notes
`num_objectives`	int	yes	Number of objectives (2 to 10). Min 2. Max 10.
`num_parameters`	int	yes	Number of parameters (genes) per solution (1 to 10). Min 1. Max 10.
`target`	list	yes	Target value for each objective, as a list of floats.
`objective_names`	list	no	Optional names for each objective (comma-separated or list).
`gene_type`	str	no
`num_generations`	int	no	Min 1.
`sol_per_pop`	int	no	Min 2.
`num_parents_mating`	int	no	Min 1.
`init_range_low`	float	no
`init_range_high`	float	no
`random_mutation_min_val`	float	no
`random_mutation_max_val`	float	no
`parent_selection_type`	str	no

Linear Single Objective¶

submission_type: quick_single_objective

Input	Type	Required	Notes
`num_parameters`	int	no	How many coefficients to generate when you do not supply them explicitly (1 to 10). Min 1. Max 10.
`function_inputs`	list	no	Explicit list of linear coefficients. Overrides num_parameters when given.
`target`	float	yes	The output value the linear function should get closest to. Min -9999. Max 9999.
`gene_type`	str	no
`num_generations`	int	no	Min 1.
`sol_per_pop`	int	no	Min 2.
`num_parents_mating`	int	no	Min 1.
`init_range_low`	float	no
`init_range_high`	float	no
`random_mutation_min_val`	float	no
`random_mutation_max_val`	float	no

Logistic Regression Hyperparameters¶

submission_type: quick_logreg_classifier_hyperparameters

Input	Type	Required	Notes
`dataset_name`	str	no	Built-in dataset to use: iris, breast_cancer, or random.
`hyperparameters`	dict	yes	Map of hyperparameter name to a tune or fixed spec.
`num_generations`	int	no	Number of GA generations (default 5). Min 1.
`sol_per_pop`	int	no	Population size (default 10). Min 2.
`num_parents_mating`	int	no	Parents mating count (default 5). Min 1.
`solver`	str	no	LogReg solver: one of ('lbfgs', 'liblinear', 'saga').

PyTorch Multi-Class Neural Network¶

submission_type: quick_torch_nn_training

Input	Type	Required	Notes
`dataset_name`	str	no	Built-in dataset: iris, breast_cancer, or random.
`num_layers`	int	yes	Number of hidden layers (1 to 20). Min 1. Max 20.
`num_neurons`	list	yes	Number of neurons per hidden layer (one int per layer).
`activation_function`	list	yes	Activation function per layer (one of: ['relu', 'sigmoid']).
`num_generations`	int	no	Number of GA generations (default 5). Min 1.
`sol_per_pop`	int	no	Population size (default 10). Min 2.
`num_parents_mating`	int	no	Parents mating count (default 5). Min 1.
`gene_type`	str	no	Gene type (default float).
`init_range_low`	float	no	Lower bound for initial weight values (default -1.0).
`init_range_high`	float	no	Upper bound for initial weight values (default 1.0).
`random_mutation_min_val`	float	no	Minimum mutation delta (default -1.0).
`random_mutation_max_val`	float	no	Maximum mutation delta (default 1.0).

SKlearn Random Forest Classifier Hyperparameters¶

submission_type: quick_sklearn_rfc_hyperparameters

Input	Type	Required	Notes
`dataset_name`	str	no	Built-in dataset to use: iris, breast_cancer, or random.
`hyperparameters`	dict	yes	Map of hyperparameter name to a tune or fixed spec.
`num_generations`	int	no	Number of GA generations (default 5). Min 1.
`sol_per_pop`	int	no	Population size (default 10). Min 2.
`num_parents_mating`	int	no	Parents mating count (default 5). Min 1.

SVM Classifier Hyperparameters¶

submission_type: quick_svm_classifier_hyperparameters

Input	Type	Required	Notes
`dataset_name`	str	no	Built-in dataset to use: iris, breast_cancer, or random.
`hyperparameters`	dict	yes	Map of hyperparameter name to a tune or fixed spec.
`num_generations`	int	no	Number of GA generations (default 5). Min 1.
`sol_per_pop`	int	no	Population size (default 10). Min 2.
`num_parents_mating`	int	no	Parents mating count (default 5). Min 1.
`kernel`	str	no	SVM kernel: one of ('rbf', 'poly', 'sigmoid').

Timetable Scheduling¶

submission_type: quick_timetable_scheduling

Input	Type	Required	Notes
`problem`	dict	yes	The full problem definition object (tasks, slot structure, resources, conflict_attrs, hard_weight).
`gene_type`	str	no
`num_generations`	int	no	Min 1.
`sol_per_pop`	int	no	Min 2.
`num_parents_mating`	int	no	Min 1.

Torch Multi-Class Neural Network Hyperparameters¶

submission_type: quick_torch_nn_hyperparameters

Input	Type	Required	Notes
`dataset_name`	str	no	Built-in dataset to use: iris, breast_cancer, or random.
`hyperparameters`	dict	yes	Map of hyperparameter name to a tune or fixed spec. Must include num_layers as a fixed integer (e.g. {"num_layers": {"fixed": 2}}). num_neurons and activation_function must both be tuned or both be fixed, with one entry per layer. Tunable scalars: batch_size (int 16-256), num_epochs (int 1-100), learning_rate (float 0.0001-0.1).
`num_generations`	int	no	Number of GA generations (default 5). Min 1.
`sol_per_pop`	int	no	Population size (default 10). Min 2.
`num_parents_mating`	int	no	Parents mating count (default 5). Min 1.

Travelling Salesman¶

submission_type: quick_travelling_salesman_parameters

Input	Type	Required	Notes
`points`	list	yes	List of [lat, lng] pairs for the cities (lat in [-90, 90], lng in [-180, 180]; at least 2 points).
`gene_type`	str	no
`num_generations`	int	no	Min 1.
`num_parents_mating`	int	no	Min 1.
`sol_per_pop`	int	no	Min 2.
`mutation_percent_genes`	int	no
`mutation_by_replacement`	bool	no
`allow_duplicate_genes`	bool	no

Travelling Salesman Demo¶

submission_type: quick_travelling_salesman_demo_parameters

Input	Type	Required	Notes
`points`	list	no	List of [x, y] pairs (0-100 canvas coords) for the cities. When omitted, a built-in 5-city set is used.
`gene_type`	str	no
`num_generations`	int	no	Min 1.
`num_parents_mating`	int	no	Min 1.
`sol_per_pop`	int	no	Min 2.
`mutation_percent_genes`	int	no
`mutation_by_replacement`	bool	no
`allow_duplicate_genes`	bool	no

XGBoost Classifier Hyperparameters¶

submission_type: quick_xgboost_classifier_hyperparameters

Input	Type	Required	Notes
`dataset_name`	str	no	Built-in dataset to use: iris, breast_cancer, or random.
`hyperparameters`	dict	yes	Map of hyperparameter name to a tune or fixed spec.
`num_generations`	int	no	Number of GA generations (default 5). Min 1.
`sol_per_pop`	int	no	Population size (default 10). Min 2.
`num_parents_mating`	int	no	Parents mating count (default 5). Min 1.

Docs