Submissions

The client.submissions resource maps to the Submissions endpoint. Every method returns a typed Submission (or a Page of them).

Create a submission¶

submission = client.submissions.create(
    name="from script",
    fitness_func=(
        "def fitness_func(ga, sol, idx):\n"
        "    return sum(sol)\n"
    ),
    num_genes=5,
    num_generations=100,
    sol_per_pop=50,
)

Arguments¶

REST equivalent: POST /api/v1/submissions/. The body shape is the same as the table.

Quick submission types¶

When you set submission_type to one of the values below, Vilvik fills in the fitness function and parameter defaults for that problem. You only need to provide the input data the problem needs.

The 9 non-ML types (subset sum, the linear objectives, knapsack, bin packing, 2D clustering, and the two travelling salesman variants) can be created over the REST API and the SDK today. The 10 ML types (quick_sklearn_rfc_hyperparameters and the rest) can now be created over the API and SDK too, using a built-in dataset: pass dataset_name as iris, breast_cancer, or random (the XOR type uses its own built-in data). 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 dict, with {"tune": True, "min": a, "max": b} to search a range or {"fixed": v} to pin a value:

client.submissions.create(
    submission_type="quick_sklearn_rfc_hyperparameters",
    dataset_name="iris",
    hyperparameters={"n_estimators": {"tune": True, "min": 50, "max": 150}, "max_depth": {"fixed": 10}},
)

See Quick submission types for the dataset names, the hyperparameters shape, and the per-type fields.

For some types, you may pass the problem data explicitly or send a count and let the service generate it. Either way, the 202 response echoes the data actually used under a generated key, so a run is reproducible from the response alone:

result = client.submissions.create(
    submission_type="quick_binary_subset_sum",
    num_integers=8,   # let the service pick 8 integers
    target=20,
)
# result.raw["generated"]["integers"] shows the integers that were chosen

Each quick type accepts its problem-specific inputs as extra keyword arguments. For example:

client.submissions.create(
    submission_type="quick_knapsack",
    num_generations=50,
    item_names=["gold bar", "silver bar", "bronze"],
    item_values=[10, 6, 3],
    item_weights=[[3], [2], [1]],
    dimension_names=["weight"],
    dimension_capacities=[5],
)

See Quick submission types for the full REST API reference with every field and its constraints. See Creating a submission for the UI-side quick problems guide, and Submission parameters for what every GA parameter controls.

Return value¶

create returns a Submission:

Fetch a single submission¶

submission = client.submissions.get("abcDEF123456")
print(submission.status)

REST equivalent: GET /api/v1/submissions/<id>.

List submissions¶

page = client.submissions.list(limit=20)
for sub in page:
    print(sub.id, sub.name, sub.status)

if page.next_cursor:
    next_page = client.submissions.list(cursor=page.next_cursor)

list returns a Page with items, next_cursor, and raw. Pages are iterable and support len().

REST equivalent: GET /api/v1/submissions/ with ?cursor=…&limit=….

Iterate every submission¶

When you want every submission without thinking about cursors:

for sub in client.submissions.iter_all(limit=50):
    print(sub.id)

The generator follows next_cursor automatically and stops when there are no more rows. See Filtering submissions and results for query filters.

Cancel or delete a submission¶

client.submissions.delete("abcDEF123456")

The worker stops at the next checkpoint. The submission moves to cancelled. Credits already used are still billed.

REST equivalent: DELETE /api/v1/submissions/<id>.

Re-execute a submission¶

Re-execute repeats a run with the same parameters, or with overrides you supply:

sub = client.submissions.reexecute(
    "abcDEF123456",
    num_generations=200,
    mutation_probability=0.05,
)

Pass any GA parameter to override it. The new run is a child of the original.

REST equivalent: POST /api/v1/submissions/<id>/reexecute.

Related pages¶

• Results
• The vilvik.run helper
• Errors and exceptions
• Submissions endpoint
• Creating a submission
• Submission parameters