fz-Model

A Funz plugin template repository for creating custom model plugins.

This repository serves as a template and starting point for creating new Funz model plugins. It provides a working example with a mock calculator that you can customize for your specific simulation code.

Features

Input Syntax

• Variable syntax: ${variable_name}
• Formula syntax: @{formula}
• Comment character: #

Supported Output Variables

The template model (Model) extracts these output variables:

• result: The main result value from the calculation

Installation

This plugin requires the Funz/fz framework.

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

Usage

With fz Python API

import fz

# Example: Run calculation with varying parameters
results = fz.fzr(
    input_path="examples/Model/input.txt",
    input_variables={
        "x": [1.0, 2.0, 3.0, 4.0, 5.0],
        "y": [1.0, 2.0],
        "z": [0.5]
    },
    model="Model",
    calculators="localhost_Model",
    results_dir="my_results"
)

print(results[['x', 'y', 'z', 'result']])

Directory Structure

your_project/
├── examples/
│   └── Model/
│       └── input.txt           # Example input file
├── .fz/
│   ├── models/
│   │   └── Model.json          # Model configuration
│   └── calculators/
│       ├── Model.sh            # Calculator script (mock)
│       └── localhost_Model.json
├── tests/
│   └── test_plugin.py          # Test suite
└── results/                    # Generated by fz

Example Input File

# Example input file for Model plugin
# Variables are defined using ${variable_name} syntax

# Input parameters
x = ${x}
y = ${y}
z = ${z}

In this example:

• ${x}, ${y}, and ${z} are variable parameters that will be substituted by fz
• Lines starting with # are comments

Creating Your Own Plugin

To create a custom plugin based on this template:

1. Clone this repository as a starting point
2. Rename the model:
   • Rename .fz/models/Model.json to .fz/models/YourModel.json
   • Update the id field in the JSON file
3. Customize the calculator script:
   • Rename .fz/calculators/Model.sh to .fz/calculators/YourModel.sh
   • Implement actual calls to your simulation code
4. Update output parsing:
   • Edit the output section in your model JSON
   • Add shell commands that extract values from your output files
5. Update calculator configuration:
   • Edit .fz/calculators/localhost_Model.json
   • Update model mappings to match your script names
6. Add examples:
   • Create example input files for your simulation code

Model Configuration

The model JSON file defines variable syntax and output parsing:

{
    "id": "Model",
    "varprefix": "$",
    "formulaprefix": "@",
    "delim": "{}",
    "commentline": "#",
    "output": {
        "result": "cat output.txt 2>/dev/null || echo ''"
    }
}

Fields:

• id: Unique identifier for the model
• varprefix: Character prefix for variables (e.g., $ for ${x})
• formulaprefix: Character prefix for formulas
• delim: Delimiter characters around variable names
• commentline: Character(s) that start a comment line
• output: Mapping of output variable names to shell commands that extract their values

Calculator Configuration

The calculator JSON files define how to execute your code:

{
    "uri": "sh://",
    "models": {
        "Model": "bash .fz/calculators/Model.sh"
    }
}

• uri: Execution method (sh:// for local shell, ssh:// for remote)
• models: Mapping of model names to execution commands

Remote Execution

To run calculations on a remote server:

results = fz.fzr(
    input_path="input.txt",
    input_variables={"x": [1.0, 2.0, 3.0]},
    model="Model",
    calculators="ssh://user@server.com/bash /path/to/calculators/Model.sh",
    results_dir="remote_results"
)

Troubleshooting

Calculator script not found

Ensure the calculator script is executable:

chmod +x .fz/calculators/Model.sh

Output variable not found

Check the output section in your model JSON file. The shell commands must correctly parse your output files.

Running Tests

python tests/test_plugin.py

License

BSD 3-Clause License. See LICENSE file.

Related Links

• Funz/fz - Main framework
• Funz/fz-Scale - Example plugin for SCALE code