fz-Algorithm

A Funz plugin template repository for creating custom algorithm plugins.

This repository serves as a template and starting point for creating new Funz algorithm plugins. It provides a working example with a random sampling algorithm that you can customize for your own optimization, sampling, or design-of-experiments algorithm.

Features

Algorithm Interface

Every algorithm must implement these methods:

• __init__(**options): Constructor accepting algorithm-specific options
• get_initial_design(input_vars, output_vars): Return initial set of points to evaluate
• get_next_design(X, Y): Return next points based on previous results, or [] when finished
• get_analysis(X, Y): Return final analysis results

Optional method:

• get_analysis_tmp(X, Y): Return intermediate analysis at each iteration (for progress display)

Template Algorithm

The template includes a Random Sampling algorithm (Algorithm) that:

• Generates nvalues random points uniformly in the input variable bounds
• Is a one-shot algorithm (no iterative refinement)
• Reports basic statistics (mean, best, worst)

Installation

This plugin requires the Funz/fz framework.

pip install git+https://github.com/Funz/fz.git

Install the Algorithm Plugin

import fz
fz.install_algorithm("Algorithm")

Or from a URL:

fz.install_algorithm("https://github.com/Funz/fz-Algorithm")

Or using the CLI:

fz install Algorithm

Usage

Without fzd (standalone algorithm testing)

You can test your algorithm without any simulation code:

from fz.algorithms import load_algorithm

# Load the algorithm
algo = load_algorithm("Algorithm", nvalues=20, seed=123)

# Define input variable ranges
input_vars = {"x": (0.0, 10.0), "y": (-5.0, 5.0)}

# Get initial design
design = algo.get_initial_design(input_vars, ["output"])
print(f"Initial design: {len(design)} points")

# Simulate outputs (replace with your function)
import math
outputs = [math.sin(p["x"]) + p["y"]**2 for p in design]

# Get analysis
analysis = algo.get_analysis(design, outputs)
print(analysis["text"])

With fzd (coupled with a model)

Use fz.fzd() to run the algorithm coupled with a model and calculators:

import fz

# Install model and algorithm plugins
fz.install("Model")  # or your model
fz.install_algorithm("Algorithm")

# Run iterative design
analysis = fz.fzd(
    input_path="examples/Model/input.txt",
    input_variables={"x": "[0;10]", "y": "[-5;5]"},
    model="Model",
    output_expression="result",
    algorithm="Algorithm",
    algorithm_options={"nvalues": 20, "seed": 123},
    calculators="localhost_Model",
    analysis_dir="analysis_results"
)

print(analysis)

Directory Structure

fz-Algorithm/
├── .fz/
│   └── algorithms/
│       └── Algorithm.py        # Algorithm implementation
├── .github/
│   └── workflows/
│       └── test.yml            # CI workflow
├── tests/
│   └── test_plugin.py          # Test suite
├── example_standalone.ipynb    # Notebook: algorithm without fzd
├── example_with_fzd.ipynb      # Notebook: algorithm with fzd
├── LICENSE
└── README.md

Creating Your Own Algorithm Plugin

To create a custom algorithm plugin based on this template:

1. Clone this repository as a starting point:

   # On GitHub: Use "Use this template" button, or:
   git clone https://github.com/Funz/fz-Algorithm.git fz-MyAlgorithm
   cd fz-MyAlgorithm

2. Rename the algorithm:

   • Rename .fz/algorithms/Algorithm.py to .fz/algorithms/MyAlgorithm.py
   • Rename the class inside from Algorithm to MyAlgorithm
   • Update the #title, #author, #type, #options, #require headers

3. Implement your algorithm:

   • get_initial_design(): Generate your initial set of points
   • get_next_design(): Implement your iterative logic (return [] when done)
   • get_analysis(): Format your results
   • Optionally implement get_analysis_tmp() for progress reporting

4. Update metadata headers:

   #title: My Optimization Algorithm
   #author: Your Name
   #type: optimization
   #options: max_iter=100;tol=0.001;population_size=20
   #require: numpy;scipy

5. Update tests and examples:

   • Edit tests/test_plugin.py to match your algorithm
   • Update the example notebooks

Algorithm Types

Common algorithm types (set in #type header):

• sampling: Random sampling, Latin Hypercube, etc.
• optimization: Gradient descent, PSO, Brent, etc.
• sensitivity: Sobol, Morris, etc.
• doe: Design of experiments (full factorial, etc.)

Header Format

Algorithm files support these metadata headers:

#title: Algorithm display name
#author: Author name
#type: algorithm category (sampling, optimization, sensitivity, ...)
#options: key1=default1;key2=default2;...
#require: package1;package2;...

• #options: Default values for algorithm options. Users can override these via fzd(..., algorithm_options={...})
• #require: Python packages that will be auto-installed if missing

Running Tests

# Run all tests
python -m pytest tests/ -v

# Or directly
python tests/test_plugin.py

License

BSD 3-Clause License. See LICENSE file.

Related Links

• Funz/fz - Main framework
• Funz/fz-Model - Template for model plugins
• Funz/fz-Scale - Example model plugin for SCALE