Language

Decorators

FPy programs are declared using the @fpy2.fpy decorator.

fpy2.fpy(func: Callable[[P], R]) → Function[P, R]
fpy2.fpy(*, ctx: Context | None = None, spec: Any = None, meta: dict[str, Any] | None = None) → Callable[[Callable[[P], R]], Function[P, R]]

Decorator to parse a Python function into FPy.

Constructs an FPy Function from a Python function. FPy is a stricter subset of Python, so this decorator will reject any function that is not valid in FPy.

Parameters:

  • func – The function to decorate (when used without parentheses)

  • spec – Optional specification for the function

  • meta – Optional metadata dictionary for the function

FPy primitive are declared using the @fpy2.fpy_primitive decorator.

fpy2.fpy_primitive(func: Callable[[P], R]) → Primitive[P, R]
fpy2.fpy_primitive(*, ctx: str | None = None, arg_ctxs: list[str | tuple] | None = None, ret_ctx: Context | str | tuple | None = None, spec: Any = None, meta: dict[str, Any] | None = None) → Callable[[Callable[[P], R]], Primitive[P, R]]

Decorator to parse a Python function into an FPy primitive. Constructs an FPy Primitive from a Python function.

Primitives are Python functions that can be called from the FPy runtime.

Parameters:

  • func – The function to decorate (when used without parentheses)

  • spec – Optional specification for the primitive

  • meta – Optional metadata dictionary for the primitive

Primitives are arbitrary Python functions that can be called with FPy programs. They must have type annotations for all arguments and the return value.

Runtime

FPy programs are represented by the fpy2.Function class.

class fpy2.Function(ast: FuncDef, *, runtime: Interpreter | None = None)

Bases: Generic[P, R]

FPy function.

This object is created by the @fpy decorator and represents a function in the FPy runtime.

Example:

@fp.fpy
def my_function(x: fp.Real) -> fp.Real:
    return x * 2
static from_fpcore(core: FPCore, *, env: ForeignEnv | None = None, default_name: str = 'f', ignore_unknown: bool = False)

Converts an FPCore (from titanfp) to an FPy function.

Optionally, specify default_name to set the name of the function. If ignore_unknown is set to True, then the syntax checker will not raise an exception when encountering unknown functions.

class fpy2.ForeignEnv(globals: dict[str, Any], nonlocals: dict[str, CellType], builtins: dict[str, Any])

Bases: object

Python environment of an FPy function.

get(key, default=None) → Any

Like get() for dict instances.

merge(other: ForeignEnv, keys: Iterable[str] | None = None) → ForeignEnv

Merge two environments.

Optionally, specify keys to restrict which keys to merge.

Interpreters

FPy programs are interpreted by any implementation of the fpy2.Interpreter class.

class fpy2.Interpreter(ctx: Context | None = None)

Bases: ABC

Abstract base class for FPy interpreters.

ctx: Context | None = None

optionaly overriding context

abstractmethod eval(func: Function, args, ctx: Context | None = None)

Evaluates a function func on arguments args under a rounding context ctx. If ctx is None, the rounding context is the native Python floating-point context.

abstractmethod eval_expr(expr: Expr, env: dict[NamedId, Any], ctx: Context)

Evaluates an expression expr under an environment env and rounding context ctx. Unlike eval, this method requires and explicit rounding context.

FPy provides a single interpreter:

class fpy2.BytecodeInterpreter(ctx: Context | None = None)

Bases: Interpreter

Interpreter that compiles to Python bytecode and executes it.

eval(func: Function, args, ctx: Context | None = None)

Evaluates a function func on arguments args under a rounding context ctx. If ctx is None, the rounding context is the native Python floating-point context.

eval_expr(expr: Expr, env: dict[NamedId, Any], ctx: Context)

Evaluates an expression expr under an environment env and rounding context ctx. Unlike eval, this method requires and explicit rounding context.

Calling a fpy2.Function object invokes the default interpreter. A user can set or get the default interpreter using the following functions:

fpy2.set_default_interpreter(rt: Interpreter)

Sets the default FPy interpreter

fpy2.get_default_interpreter() → Interpreter

Get the default FPy interpreter.

Compatability

FPy is compatabile with FPCore, a minimal functional language for specifying numerical algorithms.

class fpy2.FPCoreContext(**kwargs)

Bases: object

FPCore rounding context.

FPCore defines a rounding context to be a dictionary of properties. Each property consists of an arbitrary string key and an arbitrary value.

The FPCore standard defines a set of standard properties: - precision: the precision of the floating-point numbers - round: the rounding mode to use - overflow: overflow behavior for fixed-point numbers

This class provides a way to define an FPCore-style rounding context and convert to and from rounding contexts in this library.

static from_context(ctx: Context) → FPCoreContext

Create an FPCore context from a given context.

Parameters:

ctx – The context to convert.

Returns:

An FPCore context with the properties of the given context.

to_context() → Context

Converts the FPCore context to a context in this library.

with_prop(key: str, value: Any) → FPCoreContext

Create a new FPCore context with the given property.

Parameters:

  • key – The property key.

  • value – The property value.

Returns:

A new FPCore context with the given property.