finn.interface

This page contains the complete API reference for all modules in the finn.interface package.

finn.interface.interface_utils

Utilities for the FINN command line interface.

resolve_module_path

def resolve_module_path(name: str) -> str

Resolve the path to modules which are not part of the FINN package hierarchy.

NullablePath Objects

class NullablePath(click.ParamType)

If the passed parameter is an empty string return None, otherwise a Path.

init

def __init__(expand_user: bool = True) -> None

Initialize a NullablePath.

convert

def convert(value: str, param: Any, ctx: Any) -> Path | None

Convert a string value into a Path or None, depending on the contents.

error

def error(msg: str) -> None

Print an error.

warning

def warning(msg: str, critical: bool = False) -> None

Print a warning.

status

def status(msg: str) -> None

Print a status message.

success

def success(msg: str) -> None

Print a success message.

debug

def debug(msg: str, with_rich: bool = True) -> None

Print a debug message. Only done when the flag is set.

table

def table(data: dict[Any, Any], key_header: str, value_header: str) -> None

Print the data as a table.

assert_path_valid

def assert_path_valid(p: Path) -> None

Check if the path exists, if not print an error message and exit with an error code.

set_synthesis_tools_paths

def set_synthesis_tools_paths() -> None

Check that all synthesis tools can be found. If not, give a warning.

finn.interface.manage_deps

Manage dependencies. Called by run_finn.py.

Dependency Objects

class Dependency()

Baseclass for all dependencies.

GitDependency Objects

class GitDependency(BaseModel, Dependency)

Data model for a Git-based dependency.

url: Git repository URL. commit: Commit to checkout. pip_install: Whether to install the repository using pip.

editable_install_requires_pip

@model_validator(mode="after")
def editable_install_requires_pip() -> GitDependency

Validate that editable installs can only be done on pip installed repos.

BoardfileDependency Objects

class BoardfileDependency(BaseModel, Dependency)

Data model for a Boardfile dependency.

url: Git repository URL. commit: Commit to checkout. subdirectory: Path inside the repository from which to copy to the boardfiles directoty.

DirectDownloadDependency Objects

class DirectDownloadDependency(BaseModel, Dependency)

Data model for a direct download dependency.

url: URL to download from. do_unzip: Whether to unzip the downloaded data. target_directory: Where to place the downloaded (uncompressed) data.

DependencyData Objects

class DependencyData(BaseModel)

Data model that stores all dependencies.

get_all_dependencies

def get_all_dependencies() -> list[str]

Return a list of all packages, across dependency types.

get_dependency_count

def get_dependency_count() -> int

Return the total number of dependencies.

assert_unique_dependency_names

def assert_unique_dependency_names() -> None

Assert that all dependencies across categories have unique names. Raise AssertionError otherwise.

dependency_type_str

def dependency_type_str(package_name: str) -> str

Return a string to tell which type this dependency is.

get_dependency_data

def get_dependency_data(package_name: str) -> Dependency | None

Return the dependency data for the given package. If no such package exists return None.

get_fields

def get_fields(package_name: str, *field_names: str) -> tuple

Return a tuple with all required fields from the data. If one of the fields does not exist, raise an exception.

_StatusTracker Objects

class _StatusTracker()

Small helper class to thread-safely organize status data.

init

def __init__(names_types: list[tuple[str, str]],
             live: Live | contextlib.nullcontext) -> None

Create a status tracker.

Arguments:

names_types - List of tuples that associate dependency names with their type.
live - The rich.live.Live object that is used to display the status data.

update_status

def update_status(name: str, status: str, color: str) -> None

Update the status dict. If name doesnt exist, do nothing.

update_live

def update_live() -> None

Update the associated live rich display. Also refreshes it.

set_updating

def set_updating(name: str) -> None

Set the package to updating and update the live display. If name doesnt exist, do nothing.

set_finish

def set_finish(name: str, successful: bool) -> None

Set the package to finished and update the live display. If name doesnt exist, do nothing.

DependencyUpdater Objects

class DependencyUpdater()

Manage non-python dependencies.

init

def __init__(dependency_location: Path,
             dependency_definition_file: Path,
             git_timeout_s: float,
             non_interactive: bool = False) -> None

Create a new updater.

Boardfiles will be downloaded to the specified location at /boardfiles_downloads/. This is used to check whether they are outdated.

Arguments:

dependency_location - Path to the directory where all files are placed / checked.
dependency_definition_file - This points to the yaml file containing all dependencies.
git_timeout_s - Timeout for git requests in seconds.
non_interactive - If set, don't generate a live status report.

install_dependency

def install_dependency(package_name: str) -> bool

Install the dependency in the dependency location. If no definition for this dependency exists or the installation failed, return False. If the installation was successful return true.

is_outdated

def is_outdated(package_name: str, installed: bool = False) -> bool

Return whether the a package is outdated. If no such package exist return False too.

get_outdated_dependencies

def get_outdated_dependencies() -> list[str]

Return a list of the names of all outdated packages. For Git dependencies this means an outdated commit hash, for the others a different URL or target directory.

update

def update() -> None

With a live display and multithreading update all dependencies that are outdated.

finn.interface.manage_tests

Manage FINNs testsuite.

resolve_tests_dir

def resolve_tests_dir(tests_dir: Path | None) -> Path

Locate the test suite and check that its tooling is installed.

The suite is the tests/ directory of a repository checkout and is not part of the pip package. It is taken from the argument, or else from ./tests of the current directory. The environment is deliberately not consulted: a FINN_TESTS variable exported by a shell profile would silently point every other checkout or worktree at the wrong suite. Raises a FINNUserError explaining what is missing otherwise.

run_doctests

def run_doctests(num_workers: int) -> bool

Run all doctests in FINN and report if any failed.

run_test

def run_test(variant: str,
             num_workers: str,
             tests_dir: Path,
             args: str = "") -> None

Run a given test variant with the given number of workers.

The test suite at tests_dir (see resolve_tests_dir) is run against the installed finn package: pytest picks up the pyproject.toml of the checkout as its configuration and puts the checkout root on sys.path for the tests package, while "import finn" resolves like in any other process of this interpreter.

finn.interface.run_finn

Run FINN+.

edit_file

def edit_file(p: Path) -> None

Try to open the given file in the editor of choice. If none is found exit.

output

def output(f: Callable) -> Callable[..., Any]

Add a click parameter named --output (-o) that defaults to None if the param is empty, and a path otherwise.

finn_deps

def finn_deps(f: Callable) -> Callable[..., Any]

Add a click parameter named --dependency-path (-d) (finn_deps) that defaults to None if the param is empty, and a path otherwise.

finn_deps_definitions

def finn_deps_definitions(f: Callable) -> Callable[..., Any]

Add a click parameter named --dependency-definitions (-D) (finn_deps_definitions) that defaults to None if the param is empty, and a path otherwise.

finn_build_dir

def finn_build_dir(f: Callable) -> Callable[..., Any]

Add a click parameter named --build-path (-b) (finn_build_dir) that defaults to None if the param is empty, and a path otherwise.

flow_config

def flow_config(f: Callable) -> Callable[..., Any]

Add a click parameter named config (type pathlib.Path).

model

def model(f: Callable) -> Callable[..., Any]

Add a click parameter named model (type pathlib.Path).

verify_input

def verify_input(f: Callable) -> Callable[..., Any]

Add a click parameter named verify_input (type NullablePath).

verify_output

def verify_output(f: Callable) -> Callable[..., Any]

Add a click parameter named verify_output (type NullablePath).

num_default_workers

def num_default_workers(f: Callable) -> Callable[..., Any]

Add a click parameter called --num-workers (-n) (num_default_workers). Defaults to -1.

skip_dep_update

def skip_dep_update(f: Callable) -> Callable[..., Any]

Add a click parameter called --skip-dep-update (-s). Defaults to False.

accept_defaults

def accept_defaults(f: Callable) -> Callable[..., Any]

Add a click parameter called --accept-defaults. Defaults to False.

tests_path

def tests_path(f: Callable) -> Callable[..., Any]

Add a click parameter called --tests-path (tests_path) that defaults to None if the param is empty, and a path otherwise.

batch

def batch(f: Callable) -> Callable[..., Any]

Add a click parameter called --batch. Defaults to False.

run_flow_wizard

def run_flow_wizard() -> None

Interactively create a flow config with the user and save it.

run_setup_wizard

def run_setup_wizard(settings: FINNSettings) -> None

Interactively ask the user to confirm / change / reject the default settings if no settings file was found. Saves the edited settings. IMPORTANT: This method does not check whether the file exists, or if the passed settings contain the default values. It simply runs the wizard without questions.

xilinx_ld_library_paths

def xilinx_ld_library_paths() -> list[str]

Collect the library directories needed to load the Xilinx simulation libraries.

Returns an empty list if the Xilinx environment has not been sourced.

prepend_ld_library_paths

def prepend_ld_library_paths(paths: list[str]) -> bool

Prepend the missing entries of paths to LD_LIBRARY_PATH. True if it changed.

ensure_ld_library_path

def ensure_ld_library_path() -> None

Put the Xilinx library paths into LD_LIBRARY_PATH, restarting FINN+ if necessary.

ld.so reads LD_LIBRARY_PATH once, while the process starts, so assigning to os.environ only ever affects subprocesses (xelab, xvlog, pytest, ...). The finn_xsi pybind11 extension however dlopens the XSI simulator kernel inside this process, and the kernel's transitive dependencies (libxv_wavedata.so and friends) are resolved against the search path the loader captured at startup. An RPATH on xsi.so does not fix that: it is consulted for the direct dlopen only, not for the dependencies of the library that dlopen brings in. So the process image has to be replaced by one that starts out with the corrected environment.

prepare_finn

def prepare_finn(settings: FINNSettings,
                 accept_defaults: bool,
                 batch: bool = False,
                 create_build_dir: bool = True) -> None

Prepare FINN to run.

main_group

@click.group(
    help=
    'Produce hardware designs from ONNX models. To get started use "finn build" '
    "(or run or auto) to start a FINN flow.",
    invoke_without_command=True,
)
@click.option("--version", "-v", is_flag=True)
def main_group(version: bool) -> None

Main click group.

get_function_args

def get_function_args() -> dict

Return key-values for the calling functions arguments. Filtered, so that no arguments accidentally get returned.

read_model_path

def read_model_path(flowconfig: Path) -> Path | None

Try to read the model path from the flow config.

build

@click.command(help="Build a hardware design")
@output
@accept_defaults
@finn_deps
@finn_deps_definitions
@finn_build_dir
@flow_config
@model
@verify_input
@verify_output
@num_default_workers
@skip_dep_update
@click.option(
    "--start",
    default="",
    help="If no start_step is given in the dataflow build config, "
    "this starts the flow from the given step.",
)
@click.option(
    "--stop",
    default="",
    help="If no stop_step is given in the dataflow build config, "
    "this stops the flow at the given step.",
)
@batch
def build(output: Path | None, accept_defaults: bool, finn_deps: Path | None,
          finn_deps_definitions: Path | None, finn_build_dir: Path | None,
          verify_input: Path | None, verify_output: Path | None,
          num_default_workers: int, skip_dep_update: bool, start: str,
          stop: str, batch: bool, flow_config: Path,
          model: Path | None) -> None

Launch a FINN hardware build.

run

@click.command(help="Run a script in a FINN environment", deprecated=True)
@accept_defaults
@finn_deps
@finn_deps_definitions
@finn_build_dir
@num_default_workers
@skip_dep_update
@batch
@click.argument(
    "script",
    type=click.Path(exists=True,
                    file_okay=True,
                    dir_okay=False,
                    executable=True,
                    path_type=Path),
)
def run(accept_defaults: bool, finn_deps: Path | None,
        finn_deps_definitions: Path | None, finn_build_dir: Path | None,
        skip_dep_update: bool, num_workers: int, script: Path,
        batch: bool) -> None

Click command line option to run a script in a FINN+ context.

Can be used for backwards compability with old FINN build flows.

auto

@click.command(
    help=
    "Best effort to automatically start FINN without further configuration.")
@batch
def auto(batch: bool) -> None

Try to run FINN guessing which files to use for config and model.

wizard

@click.group(help="Run setup wizards for various tasks.")
def wizard() -> None

Command group for wizards that help setup FINN.

flow_wizard

@click.command(name="flow")
def flow_wizard() -> None

Run the wizard helping to setup a flow config.

settings_wizard

@click.command(name="settings")
def settings_wizard() -> None

Run the wizard helping to set up the FINN+ settings.

bench

@click.command(help="Run a given benchmark configuration.")
@click.option("--bench_config",
              help="Name or path of experiment configuration file",
              required=True)
@finn_deps
@finn_deps_definitions
@finn_build_dir
@num_default_workers
@batch
def bench(bench_config: str, finn_deps: Path | None,
          finn_deps_definitions: Path | None, num_default_workers: int,
          finn_build_dir: Path | None, batch: bool) -> None

Run a benchmark.

test

@click.command(help=(
    "Run the FINN+ test suite from a repository checkout (see --tests-path). Uses "
    "/tmp/FINN_TEST_BUILD_DIR as the temporary file location. Requires the test tooling: "
    "part of 'poetry install' in a checkout, or pip install finn-plus[test]."))
@finn_deps
@finn_deps_definitions
@finn_build_dir
@num_default_workers
@skip_dep_update
@tests_path
@click.option(
    "--variant",
    "-v",
    help=(
        "Which test to execute (quick, quicktest_ci, full_ci, doctest, custom)."
        "'custom' ignores all parameters expect for --args ..."),
    default="quick",
    show_default=True,
    type=click.Choice(
        ["quick", "quicktest_ci", "full_ci", "custom", "doctest", "doctest"]),
)
@click.option(
    "--args",
    default="",
    required=False,
    help="Arguments to pass to pytest. Only usable with '--variant custom'. ",
)
@click.option("--num-test-workers", "-t", default="auto", show_default=True)
@batch
def test(variant: str, args: str, finn_deps: Path | None,
         finn_deps_definitions: Path | None, num_default_workers: int,
         skip_dep_update: bool, tests_path: Path | None, num_test_workers: str,
         finn_build_dir: Path | None, batch: bool) -> None

Run a selected subset of the FINN(+) testsuite.

deps

@click.group(help="Dependency management")
def deps() -> None

Click group collecting depenency related commands.

update

@click.command(help="Update or install dependencies to the given path")
@accept_defaults
@finn_deps
@finn_deps_definitions
@batch
@click.option(
    "--force",
    "-f",
    help="Overwrite any existing dependencies and make a clean install.",
    is_flag=True,
)
def update(accept_defaults: bool, finn_deps: Path | None,
           finn_deps_definitions: Path | None, batch: bool,
           force: bool) -> None

Update all FINN+ dependencies and then exit.

deps_edit

@click.command("edit", help="Edit the dependency definition file.")
@finn_deps_definitions
def deps_edit(finn_deps_definitions: Path | None) -> None

Edit the dependency definition file.

deps_show

@click.command(name="show", help="Show the dependencies")
@finn_deps_definitions
def deps_show(finn_deps_definitions: Path | None) -> None

Show the dependencies.

settings

@click.group(help="Manage FINN settings")
def settings() -> None

Click group for config related commands.

config_show

@click.command("show", help="List the settings files contents")
def config_show() -> None

List all settings found in the current settings file.

config_edit

@click.command(name="edit", help="Open the settings in your default editor.")
def config_edit() -> None

Edit the settings in an editor.

config_create

@click.command("create",
               help="Create a configuration. Same as 'finn wizard config'.")
def config_create() -> None

Run the configuration wizard.

finn_check

@click.command(
    "check",
    help=
    "Check that FINN starts up as expected and exit. Does not update dependencies."
)
def finn_check() -> None

Start FINN and close it after loading the environment.

main

def main() -> None

Clicks entrypoint function.

finn.interface.settings

Manage settings for FINN+.

path_repr

def path_repr(dumper, data)

Represent a given object as a string.

resolve_relative

def resolve_relative(path: Path | str, to: Path | str | None) -> Path

If path is absolute, return it. If relative, return the combined absolute path. If to is None, just return path (absolute).

FINNSettings Objects

class FINNSettings(BaseModel)

Keeps track of FINN+ settings. Instantiate with FINNSettings.init().

num_default_workers

@computed_field
@property
def num_default_workers() -> int

Number of default parallel workers.

num_default_workers

@num_default_workers.setter
def num_default_workers(new_value: int | str) -> None

Set number of default workers.

finn_build_dir

@computed_field
@property
def finn_build_dir() -> Path

Absolute path to the FINN_BUILD_DIR.

finn_build_dir

@finn_build_dir.setter
def finn_build_dir(new_path: str | Path | None) -> None

Set the FINN_BUILD_DIR.

finn_deps

@computed_field
@property
def finn_deps() -> Path

Absolute path to the FINN_DEPS dir.

finn_deps

@finn_deps.setter
def finn_deps(new_path: str | Path) -> None

Set the FINN_DEPS dir.

finn_deps_definitions

@computed_field
@property
def finn_deps_definitions() -> Path

Absolute path to the FINN_DEPS_DEFINITIONS.

finn_deps_definitions

@finn_deps_definitions.setter
def finn_deps_definitions(new_path: str | Path) -> None

Set the FINN_DEPS_DEFINITIONS.

update_environment

def update_environment() -> None

Update the environment variables according to field values.

resolve_settings_file

@staticmethod
def resolve_settings_file(override_settings_path: Path | None) -> Path

Resolve the location of the settings file. Checks the following locations in the following order.

Override (method argument)
FINN_SETTINGS environment variable
In the FINN+ repository root
In ~/.finn/ If the file does not exist, the function will still return the path for 1,2 and 4. It must then be created by another function.

init

@staticmethod
def init(override_settings_path: Path | None = None,
         must_exist: bool = False,
         flow_config: Path | None = None,
         auto_set_environment_vars: bool = True,
         **kwargs: Any) -> FINNSettings

Create a settings object. Tries to resolve the settings path.

The settings file directory is resolved in this order: FINN_SETTINGS environment variable -> Repository Root -> ~/.finn/. If override_settings_path exists, it is used instead.

The settings are updated with the lowest priority first. (Defaults -> Settings file -> Environment -> Command line param) Thus, if a command line param is given, it is used over the others.

Validation on whether the paths exist should be done by components using the settings, not the settings themselves.

If auto_set_environment_vars is True, the envvars get set automatically when setting a value.

Arguments:

**kwargs - A dictionary with initial values for the settings.
override_settings_path - If set, overrides the resolution of the settings file.
must_exist - If True, object creation fails if the settings file does not exist.
flow_config - If given, this can be used to resolve finn_build_dir. If not given, relative FINN_BUILD_DIR settings cannot be resolved.
auto_set_environment_vars - If True, set the environment variables too when assigning a setting.

Returns:

FINNSettings

update_from

def update_from(data: dict[str, Any],
                update_type: str | None = None) -> FINNSettings

Update the model from the given data (Environment, custom dict, ...) and return it.

Arguments:

data - The data to update from.
update_type - If set, this is used in the error raised in case validation fails.
ignore - List of dict keys to NOT update from.

Returns:

FINNSettings - Newly validated settings.

settingsfile_exists

def settingsfile_exists() -> bool

Return whether the settings file exists.

save

def save(installation_independent: bool, path: Path | None = None) -> None

Save settings. If None is given saves to resolved path.

Arguments:

installation_independent - If True, remove attributes specific to the installation calling this command. This refers to the modules resolved when creating the settings.
path - Where to store the settings. If None, saves at the initially resolved path.

Important: Although the getter methods of the settings path return the resolved absolute paths, this method saves the relative path originally given. This is so that we don't switch from a relative path to an absolute one on saving and restoring.

get_settings_keys

@staticmethod
def get_settings_keys() -> list[str]

Return all settings keys there are.

get_path

def get_path() -> Path

Get the settings file path.

📚 Navigation: ← Back to API Documentation

This page was generated automatically from source code documentation.

FINN+ Wiki

🏠 Home

📖 User Guide

Using FINN+ to compile a network.

Getting started

Building

Tuning

Checking

Reference

🛠️ Developer Guide

Working on the FINN+ compiler itself.

Getting started

Extending FINN+

Compiler internals

Testing

Reference

API Documentation

🔗 External Links

FINN+ Repository
Brevitas - Quantization library
QONNX - Model format
finn-examples - Pre-built accelerators

finn.interface

Table of Contents

finn.interface.interface_utils

resolve_module_path

NullablePath Objects

__init__

convert

error

warning

status

success

debug

table

assert_path_valid

set_synthesis_tools_paths

finn.interface.manage_deps

Dependency Objects

GitDependency Objects

editable_install_requires_pip

BoardfileDependency Objects

DirectDownloadDependency Objects

DependencyData Objects

get_all_dependencies

get_dependency_count

assert_unique_dependency_names

dependency_type_str

get_dependency_data

get_fields

_StatusTracker Objects

__init__

update_status

update_live

set_updating

set_finish

DependencyUpdater Objects

__init__

install_dependency

is_outdated

get_outdated_dependencies

update

finn.interface.manage_tests

resolve_tests_dir

run_doctests

run_test

finn.interface.run_finn

edit_file

output

finn_deps

finn_deps_definitions

finn_build_dir

flow_config

model

verify_input

verify_output

num_default_workers

skip_dep_update

accept_defaults

tests_path

batch

run_flow_wizard

run_setup_wizard

xilinx_ld_library_paths

prepend_ld_library_paths

ensure_ld_library_path

prepare_finn

main_group

get_function_args

read_model_path

build

run

auto

wizard

flow_wizard

settings_wizard

bench

test

deps

update

deps_edit

deps_show

init

init

init