Imports · Vilvik docs

vilvik.push(ga) takes a finished pygad.GA instance, captures its fitness function and any callbacks, and posts them to Vilvik as an editable, continuable record. The result appears on your dashboard right away. You can edit the code or parameters and continue the run from where your local execution ended.

Authentication¶

The quickest option on your own machine is vilvik login: run it once, approve in the browser, and the SDK stores a key for you. After that, vilvik.push(ga) works with no extra setup. See Signing in with vilvik login.

The manual alternative is to create a key in the dashboard under Settings > API keys, then make it available by setting the VILVIK_API_KEY environment variable or passing api_key= directly:

import vilvik

client = vilvik.Client(api_key="vlk_live_...")

For vilvik.push() you can also pass api_key= as a keyword argument, or set VILVIK_API_KEY and omit it entirely.

Basic usage¶

import pygad
import vilvik


def fitness_func(ga_instance, solution, idx):
    return -sum(s * s for s in solution)


ga = pygad.GA(
    num_generations=100,
    sol_per_pop=50,
    num_genes=5,
    num_parents_mating=4,
    fitness_func=fitness_func,
)
ga.run()

record = vilvik.push(ga, name="sphere min experiment")
print(record.result_url)

vilvik.push() returns a vilvik.ImportRecord with the fields id, result_id, and result_url. Open result_url to see the run on your dashboard.

From PyGAD directly¶

If you have a recent PyGAD and the Vilvik SDK both installed, you can push from the GA object itself without importing vilvik:

ga.run()
ga.push_to_vilvik(name="my local run")

This is exactly the same as calling vilvik.push(ga, name="my local run") and accepts all the same keyword arguments (fitness_func=, fitness_source=, callbacks=, preamble=, dry_run=, include_population=). If the Vilvik SDK is not installed, push_to_vilvik raises a clear error with a pip install vilvik hint. See Signing in with vilvik login for authentication setup.

What gets captured automatically¶

vilvik.push() inspects the GA instance and extracts:

The fitness function source and its name.
Any lifecycle callbacks (on_generation, on_start, on_stop, and others) that are plain module-level functions.
A preamble of imports and helper functions that the fitness function references in its module globals. Helper functions defined in the same file are inlined; imported modules become import statements.
The final population, so the run can be continued on Vilvik from the last generation.

Per-role overrides¶

Capture is best-effort. Lambdas, bound methods, and functions defined in a REPL or notebook cannot be extracted automatically. You can supply any role explicitly:

Override the fitness function with a callable or source string:

vilvik.push(
    ga,
    fitness_func=my_fitness_fn,   # callable, extracted automatically
)

vilvik.push(
    ga,
    fitness_source="def fitness_func(ga, sol, idx):\n    return -sum(s*s for s in sol)\n",
)

Override individual callbacks:

vilvik.push(
    ga,
    callbacks={
        "on_generation": my_on_generation_fn,   # callable or source string
    },
)

Provide a preamble for imports and helpers the fitness function needs:

vilvik.push(
    ga,
    preamble="import numpy as np\nDATA = [1, 2, 3]",
)

Explicit overrides always win over the auto-captured value.

Dry-run: inspect what will be sent¶

Pass dry_run=True to get a capture report back without sending anything to Vilvik. This is useful for checking what the SDK extracted before you commit to pushing:

report = vilvik.push(ga, dry_run=True)
print(report)

report is a vilvik.CaptureReport. Calling str() on it lists every captured role, marks auto-extracted roles, and flags anything that needs a manual override. report.ok() returns True when the fitness function was resolved and nothing needs manual input.

A typical report output looks like this:

Vilvik import capture report:
  - fitness_func: auto-extracted
  - on_generation: auto-extracted

Population and continuability¶

By default, vilvik.push() passes include_population=True, which includes the final population in the import. That means you can open the result on Vilvik and click Continue run to pick up exactly where your local run stopped.

Pass include_population=False if you only want to record the result numbers and code without making the run continuable.

The "Imported" badge¶

Until you re-run the submission on Vilvik, the result page shows an "Imported" badge. The badge makes it clear the numbers came from your local machine rather than from a Vilvik-verified run. Re-running removes the badge and replaces the result with the Vilvik-computed output.

Error handling¶

vilvik.push() raises vilvik.CaptureError when the fitness function cannot be resolved and no explicit override was given. The exception message describes which role failed and how to fix it, for example:

CaptureError: fitness_func could not be captured: it is a lambda (lambdas have no
named, standalone source). Pass it explicitly, e.g.
vilvik.push(ga, fitness_func=my_fn) or fitness_source='...'.

Other errors (network, authentication, validation) raise the standard SDK exceptions described in Errors and exceptions.

Signing in with vilvik login
Imports endpoint - REST reference for POST /api/v1/imports/
Submissions
Results
Errors and exceptions

Docs