functioneer 0.3.0__tar.gz → 0.4.0__tar.gz

functioneer-0.4.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: functioneer
+Version: 0.4.0
+Summary: Effortlessly explore function behavior with automated batch analysis.
+Author-email: Quinn Marsh <quinnmarsh@hotmail.com>
+Maintainer-email: Quinn Marsh <quinnmarsh@hotmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/qthedoc/functioneer
+Project-URL: Issues, https://github.com/qthedoc/functioneer/issues
+Project-URL: Funding, https://donate.pypi.org
+Project-URL: Say Thanks!, http://quinnmarsh.com
+Keywords: functioneer,analysis,batch run,batch runner,automation,autorun,trade space,digital twin
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.18.5
+Requires-Dist: scipy>=1.5.2
+Requires-Dist: pandas>=1.0.5
+Dynamic: license-file
+
+# Functioneer
+
+**Author**: Quinn Marsh\
+**PyPI**: https://pypi.org/project/functioneer/
+
+Functioneer lets you effortlessly explore function behavior with automated batch analysis. With just a few lines of code, you can queue up thousands or even millions of function evaluations, with various parameter combinations and/or optimizations. Retrieve structured results in formats like pandas for seamless integration into your workflows. Perfect for parameter sweeps, engineering simulations, and digital twin optimization.
+
+## Quick Start
+
+### Installation
+```
+pip install functioneer
+```
+
+Full set of examples: [Examples.ipynb](https://github.com/qthedoc/functioneer/blob/main/examples/Examples.ipynb)*\
+*This is currently the main form of documentation, lots of good stuff in there!
+
+### Choose a Function to Analyze
+Choose any function(s) you like. We use the [Rosenbrock Function](https://en.wikipedia.org/wiki/Rosenbrock_function) in these examples for its simplicity, many inputs and its historical significance as an optimization benchmark.
+
+```
+import functioneer as fn
+
+# Rosenbrock function (known minimum of 0 at: x=1, y=1, a=1, b=100)
+def rosenbrock(x, y, a, b):
+    return (a-x)**2 + b*(y-x**2)**2
+```
+
+### Example 1: Forks and Function Evaluation (The Basics)
+
+**Goal**: Test `rosenbrock` function with multiple values for parameters `x` and `y`.
+
+Note: forks for `x` and `y` create a 'grid' of values\
+Note: Parameter IDs MUST match your function's args, function evals inside functioneer are fully keyword arg based.
+```
+anal = fn.AnalysisModule() # Create new analysis
+anal.add.define({'a': 1, 'b': 100}) # define a and b
+anal.add.fork('x', (0, 1, 2)) # Fork analysis, create branches for x=0, x=1, x=2
+anal.add.fork('y', (1, 10))
+anal.add.execute(func=rosenbrock) #
+results = anal.run()
+print('Example 1 Output:')
+print(results['df'][['a', 'b', 'x', 'y', 'rosenbrock']])
+```
+```
+Example 1 Output:
+   a    b  x   y  rosenbrock
+0  1  100  0   1         101
+1  1  100  0  10       10001
+2  1  100  1   1           0
+3  1  100  1  10        8100
+4  1  100  2   1         901
+5  1  100  2  10        3601
+```
+
+### Example 2: Optimization
+
+**Goal**: Optimize `x` and `y` to find the minimum `rosenbrock` value for various `a` and `b` values.
+
+Note: values for `x` and `y` before optimization are used as initial guesses
+```
+anal = fn.AnalysisModule({'x': 0, 'y': 0})
+anal.add.fork('a', (1, 2))
+anal.add.fork('b', (0, 100, 200))
+anal.add.optimize(func=rosenbrock, opt_param_ids=('x', 'y'))
+results = anal.run()
+print('\nExample 2 Output:')
+print(results['df'][['a', 'b', 'x', 'y', 'rosenbrock']])
+```
+```
+Example 2 Output:
+   a    b         x         y    rosenbrock
+0  1    0  1.000000  0.000000  4.930381e-32
+1  1  100  0.999763  0.999523  5.772481e-08
+2  1  200  0.999939  0.999873  8.146869e-09
+3  2    0  2.000000  0.000000  0.000000e+00
+4  2  100  1.999731  3.998866  4.067518e-07
+5  2  200  1.999554  3.998225  2.136755e-07
+```
+## Key Features
+
+- **Test variations of a parameter with a single line of code:** Avoid writing deeply nested loops. Typically varying *n* parameters requires *n* nested loops... not anymore!
+
+- **Quickly swap out optimization variables:** Most optimization libraries require your function to take in a list or array of values, BUT this makes it very annoying to remap your parameters to and from the array each time you simple want to change an optimization parameter!
+
+- **Get results in a consistent easy to use format:** No more questions, the results are presented in a nice clean pandas data frame every time.
+
+## Use cases
+
+- **Analysis and Optimization of Digital Twins**: Explore the design trade-space and understand performance of your simulated system.
+- **Machine Learning and AI**: Autonomously test thousands of architectures or other parameters for ML models (like neural networks) to see which perform best.
+- **Your Imagination is the Limit**: What function will you engineer?
+
+## How Functioneer Works
+
+At its core, functioneer organizes analyses as a tree where a *set of parameters* starts at the trunk and moves out towards the *leaves*. Along the way, the *set of parameters* 'flows' through a series of *analysis steps* (each of which can be defined in a single line of code). Each *analysis step* can modify or use the parameters in various ways, such as defining new parameters, modifying/overwriting parameters, or using the parameters to evaluate or even optimize any function of your choice. One key feature of functioneer is the ability to introduce *forks*: a type of *analysis step* that splits the analysis into multiple parallel *branches*, each exploring different values for a given parameter. Using many *Forks* in series allows you to queue up thousands or even millions of parameter combinations with only a few lines of code. This structured approach enables highly flexible and dynamic analyses, suitable for a wide range of applications.
+
+Summary of most useful types of *analysis steps*:
+- Define: Adds a new parameter to the analysis
+- Fork: Splits the analysis into multiple parallel *branches*, each exploring different values for a specific parameter
+- Execute: Calls a provided function using the parameters
+- Optimize: Quickly set up an optimization by providing a function and defining which parameters are going to be optimized
+
+<details>
+<summary>
+<span style="font-size:1.5em;">Important Terms</span>
+</summary>
+
+* AnalysisModule
+    * Definition: The central container for an analysis pipeline.
+    * Function: Holds a sequence of analysis steps and manages a set of parameters that flow through the pipeline.
+
+* Parameters
+    * Definition: Named entities that represent inputs, intermediate values, or outputs of the analysis.
+    * Function: Can be created, modified, or used in computations during analysis steps.
+
+* Analysis Steps
+    * Definition: Individual operations performed during the analysis.
+    * Function: Modify parameters by defining new ones, updating existing values, forking the analysis, or executing/optimizing functions.
+
+* Fork
+    * Definition: A special type of *analysis step* that splits the pipeline into multiple branches.
+    * Function: Creates independent branches where each branch explores a different value or configuration for a given parameter.
+
+* Branch
+    * Definition: One of the independent paths created by a Fork.
+    * Function: Represents a distinct variation of the analysis, each processing a specific set of parameter values.
+
+* Leaf
+    * Definition: The endpoint of a branch after all analysis steps have been executed.
+    * Function: Represents the final state of parameters for that branch. Each leaf corresponds to a specific combination of parameter values and results. When results are tabulated, each row corresponds to a leaf.
+</details>
+
+## Inspiration
+I wanted to be an Analysis Ninja... effortlessly swapping parameters and optimization variables and most importantly getting results quickly! But manually rearranging code for what seemed like simple asks was really baking my noodle. Simple things like adding a variable to the analysis, or swapping out an optimization variable, required a shocking amount of code rework. Thus Functioneer was born.
+
+## Acknowledgments
+Thanks to the amazing open source communities: Python, numpy, pandas, etc that make this possible.
+
+Thanks to LightManufacturing, where I had the opportunity to develop advanced digital twins for solar thermal facilities... and then analyze them. It was here, where the seed for Functioneer was planted. 
+
+Thanks to God for incepting my mind with what seemed like the craziest idea at the time: to structure an analysis as a pipeline of *analysis steps* with the *parameters* flowing thru like water.
+
+## License
+
+This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
+
+You are free to use, modify, and distribute this software. Please include proper attribution by retaining the copyright notice in your copies or substantial portions of the software.
+

functioneer-0.4.0/README.md

@@ -0,0 +1,149 @@
+# Functioneer
+
+**Author**: Quinn Marsh\
+**PyPI**: https://pypi.org/project/functioneer/
+
+Functioneer lets you effortlessly explore function behavior with automated batch analysis. With just a few lines of code, you can queue up thousands or even millions of function evaluations, with various parameter combinations and/or optimizations. Retrieve structured results in formats like pandas for seamless integration into your workflows. Perfect for parameter sweeps, engineering simulations, and digital twin optimization.
+
+## Quick Start
+
+### Installation
+```
+pip install functioneer
+```
+
+Full set of examples: [Examples.ipynb](https://github.com/qthedoc/functioneer/blob/main/examples/Examples.ipynb)*\
+*This is currently the main form of documentation, lots of good stuff in there!
+
+### Choose a Function to Analyze
+Choose any function(s) you like. We use the [Rosenbrock Function](https://en.wikipedia.org/wiki/Rosenbrock_function) in these examples for its simplicity, many inputs and its historical significance as an optimization benchmark.
+
+```
+import functioneer as fn
+
+# Rosenbrock function (known minimum of 0 at: x=1, y=1, a=1, b=100)
+def rosenbrock(x, y, a, b):
+    return (a-x)**2 + b*(y-x**2)**2
+```
+
+### Example 1: Forks and Function Evaluation (The Basics)
+
+**Goal**: Test `rosenbrock` function with multiple values for parameters `x` and `y`.
+
+Note: forks for `x` and `y` create a 'grid' of values\
+Note: Parameter IDs MUST match your function's args, function evals inside functioneer are fully keyword arg based.
+```
+anal = fn.AnalysisModule() # Create new analysis
+anal.add.define({'a': 1, 'b': 100}) # define a and b
+anal.add.fork('x', (0, 1, 2)) # Fork analysis, create branches for x=0, x=1, x=2
+anal.add.fork('y', (1, 10))
+anal.add.execute(func=rosenbrock) #
+results = anal.run()
+print('Example 1 Output:')
+print(results['df'][['a', 'b', 'x', 'y', 'rosenbrock']])
+```
+```
+Example 1 Output:
+   a    b  x   y  rosenbrock
+0  1  100  0   1         101
+1  1  100  0  10       10001
+2  1  100  1   1           0
+3  1  100  1  10        8100
+4  1  100  2   1         901
+5  1  100  2  10        3601
+```
+
+### Example 2: Optimization
+
+**Goal**: Optimize `x` and `y` to find the minimum `rosenbrock` value for various `a` and `b` values.
+
+Note: values for `x` and `y` before optimization are used as initial guesses
+```
+anal = fn.AnalysisModule({'x': 0, 'y': 0})
+anal.add.fork('a', (1, 2))
+anal.add.fork('b', (0, 100, 200))
+anal.add.optimize(func=rosenbrock, opt_param_ids=('x', 'y'))
+results = anal.run()
+print('\nExample 2 Output:')
+print(results['df'][['a', 'b', 'x', 'y', 'rosenbrock']])
+```
+```
+Example 2 Output:
+   a    b         x         y    rosenbrock
+0  1    0  1.000000  0.000000  4.930381e-32
+1  1  100  0.999763  0.999523  5.772481e-08
+2  1  200  0.999939  0.999873  8.146869e-09
+3  2    0  2.000000  0.000000  0.000000e+00
+4  2  100  1.999731  3.998866  4.067518e-07
+5  2  200  1.999554  3.998225  2.136755e-07
+```
+## Key Features
+
+- **Test variations of a parameter with a single line of code:** Avoid writing deeply nested loops. Typically varying *n* parameters requires *n* nested loops... not anymore!
+
+- **Quickly swap out optimization variables:** Most optimization libraries require your function to take in a list or array of values, BUT this makes it very annoying to remap your parameters to and from the array each time you simple want to change an optimization parameter!
+
+- **Get results in a consistent easy to use format:** No more questions, the results are presented in a nice clean pandas data frame every time.
+
+## Use cases
+
+- **Analysis and Optimization of Digital Twins**: Explore the design trade-space and understand performance of your simulated system.
+- **Machine Learning and AI**: Autonomously test thousands of architectures or other parameters for ML models (like neural networks) to see which perform best.
+- **Your Imagination is the Limit**: What function will you engineer?
+
+## How Functioneer Works
+
+At its core, functioneer organizes analyses as a tree where a *set of parameters* starts at the trunk and moves out towards the *leaves*. Along the way, the *set of parameters* 'flows' through a series of *analysis steps* (each of which can be defined in a single line of code). Each *analysis step* can modify or use the parameters in various ways, such as defining new parameters, modifying/overwriting parameters, or using the parameters to evaluate or even optimize any function of your choice. One key feature of functioneer is the ability to introduce *forks*: a type of *analysis step* that splits the analysis into multiple parallel *branches*, each exploring different values for a given parameter. Using many *Forks* in series allows you to queue up thousands or even millions of parameter combinations with only a few lines of code. This structured approach enables highly flexible and dynamic analyses, suitable for a wide range of applications.
+
+Summary of most useful types of *analysis steps*:
+- Define: Adds a new parameter to the analysis
+- Fork: Splits the analysis into multiple parallel *branches*, each exploring different values for a specific parameter
+- Execute: Calls a provided function using the parameters
+- Optimize: Quickly set up an optimization by providing a function and defining which parameters are going to be optimized
+
+<details>
+<summary>
+<span style="font-size:1.5em;">Important Terms</span>
+</summary>
+
+* AnalysisModule
+    * Definition: The central container for an analysis pipeline.
+    * Function: Holds a sequence of analysis steps and manages a set of parameters that flow through the pipeline.
+
+* Parameters
+    * Definition: Named entities that represent inputs, intermediate values, or outputs of the analysis.
+    * Function: Can be created, modified, or used in computations during analysis steps.
+
+* Analysis Steps
+    * Definition: Individual operations performed during the analysis.
+    * Function: Modify parameters by defining new ones, updating existing values, forking the analysis, or executing/optimizing functions.
+
+* Fork
+    * Definition: A special type of *analysis step* that splits the pipeline into multiple branches.
+    * Function: Creates independent branches where each branch explores a different value or configuration for a given parameter.
+
+* Branch
+    * Definition: One of the independent paths created by a Fork.
+    * Function: Represents a distinct variation of the analysis, each processing a specific set of parameter values.
+
+* Leaf
+    * Definition: The endpoint of a branch after all analysis steps have been executed.
+    * Function: Represents the final state of parameters for that branch. Each leaf corresponds to a specific combination of parameter values and results. When results are tabulated, each row corresponds to a leaf.
+</details>
+
+## Inspiration
+I wanted to be an Analysis Ninja... effortlessly swapping parameters and optimization variables and most importantly getting results quickly! But manually rearranging code for what seemed like simple asks was really baking my noodle. Simple things like adding a variable to the analysis, or swapping out an optimization variable, required a shocking amount of code rework. Thus Functioneer was born.
+
+## Acknowledgments
+Thanks to the amazing open source communities: Python, numpy, pandas, etc that make this possible.
+
+Thanks to LightManufacturing, where I had the opportunity to develop advanced digital twins for solar thermal facilities... and then analyze them. It was here, where the seed for Functioneer was planted. 
+
+Thanks to God for incepting my mind with what seemed like the craziest idea at the time: to structure an analysis as a pipeline of *analysis steps* with the *parameters* flowing thru like water.
+
+## License
+
+This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
+
+You are free to use, modify, and distribute this software. Please include proper attribution by retaining the copyright notice in your copies or substantial portions of the software.
+

{functioneer-0.3.0 → functioneer-0.4.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "functioneer"
-version = "0.3.0"
+version = "0.4.0"
 authors = [{ name = "Quinn Marsh", email = "quinnmarsh@hotmail.com" }]
 maintainers = [{ name = "Quinn Marsh", email = "quinnmarsh@hotmail.com" }]
 description = "Effortlessly explore function behavior with automated batch analysis."
 readme = "README.md"
 license = { text = "MIT" }
-keywords = ["functioneer", "analysis", "batch run", "automation", "autorun", "trade space", "digital twin"]
+keywords = ["functioneer", "analysis", "batch run", "batch runner", "automation", "autorun", "trade space", "digital twin"]
 requires-python = ">=3.7"
 dependencies = [
   "numpy>=1.18.5",

{functioneer-0.3.0 → functioneer-0.4.0}/src/functioneer/__init__.py

@@ -1,4 +1,4 @@
 # functioneer/__init__.py
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 from functioneer.analysis import AnalysisModule, AnalysisStep, Define, Fork, Execute, Optimize
 from functioneer.parameter import Parameter

functioneer-0.4.0/src/functioneer/analysis.py

@@ -0,0 +1,293 @@
+# MIT License
+# Copyright (c) 2025 Quinn Marsh
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+import copy
+import pandas as pd
+from datetime import datetime
+import time
+
+from functioneer.steps import AnalysisStep, Define, Fork, Execute, Optimize
+from functioneer.parameter import ParameterSet, Parameter
+from functioneer.util import call_with_matched_kwargs
+
+## TODO: work towards staged analysis (eg. needed for pick best 10) 
+# allow for a tuple of dicts for starting with multiple parameter sets, 
+# also might allow sending in of the pandas datafram to add to it (if not just append new rows when done with sub analysis)
+# pandas_to_paramsets: a function that takes in a pd and returns a tuple of paramsets ready to be fed into the next stage of analysis
+class AnalysisModule():
+    """
+    The central container for an analysis pipeline in functioneer.
+
+    Parameters
+    ----------
+    init_param_values : dict, optional
+        Initial parameter values as a dictionary with parameter IDs (str) as keys and their values.
+        Parameter IDs must be valid (non-empty strings, not reserved names like 'runtime' or 'datetime').
+        Defaults to an empty dictionary.
+    name : str, optional
+        Name of the analysis module. Defaults to an empty string.
+
+    Raises
+    ------
+    ValueError
+        If init_param_values is not a dictionary, contains invalid parameter IDs, or includes reserved names.
+    TypeError
+        If name is not a string.
+    """
+    def __init__(self, init_param_values={}, name='') -> None:
+        """ Initialize Functioneer Analysis
+
+        Args:
+            init_param_values : dict, optional
+                Initial parameter values as a dictionary with parameter IDs (str) as keys and their values.
+                Parameter IDs must be valid (non-empty strings, not reserved names like 'runtime' or 'datetime').
+                Defaults to an empty dictionary.
+            name : str, optional
+                Name of the analysis module. Defaults to an empty string.
+
+        Raises:
+            ValueError: If init_param_values is not a dictionary, contains invalid parameter IDs, or includes reserved names.
+            TypeError: If name is not a string.
+        """
+        if not isinstance(name, str):
+            raise TypeError(f"Invalid AnalysisModule: 'name' must be a string, got {type(name)}")
+        if not isinstance(init_param_values, dict):
+            raise ValueError(f"Invalid AnalysisModule: 'init_param_values' must be a dictionary, got {type(init_param_values)}")
+        for param_id in init_param_values:
+            Parameter.validate_id(param_id)
+
+        self.name = name
+        self.sequence: list[AnalysisStep] = []
+        self.init_paramset: ParameterSet = ParameterSet()
+        self.init_paramset.update_param_values(init_param_values)
+        self.init_paramset.add_param(Parameter('runtime', 0))
+        self.finished_leaves:int = 0
+
+        # Namespaces
+        self.add = self.AddNamespace(self)  # Instantiate the namespace
+
+        # Results and Metadata
+        self.df: pd.DataFrame = pd.DataFrame()
+        self.t0 = None
+        self.leaf_data: List[Dict[str, Any]] = []
+        self.runtime: Optional[float] = None
+
+
+        pass
+
+    class AddNamespace:
+        """Namespace for adding different types of analysis steps."""
+        def __init__(self, parent):
+            self.parent: AnalysisModule = parent
+
+        def __call__(self,
+            analysis_object: AnalysisStep
+        ) -> None:
+            """Manually append an AnalysisStep object to the Analysis
+            """
+            # TODO Validate AnalysisStep
+
+            # TODO analysis_object.initialize(self.sequence)
+
+            self.parent.sequence.append(analysis_object)
+
+        def define(self, param_or_dict: Union[str, Dict[str, Any]], value: Any = None, condition: Optional[Callable[..., bool]] = None) -> None:
+            """Define a parameter with a single ID and value or a dictionary of parameters.
+
+            Args:
+                param_or_dict: Parameter ID (str) or dictionary of parameter IDs to values.
+                value: Value for the parameter (if param_or_dict is a string).
+                condition: Optional condition function to determine if the step should run.
+
+            Examples:
+                >>> anal.add.define('a', 1)  # Define single parameter
+                >>> anal.add.define({'a': 1, 'b': 100})  # Define multiple parameters
+
+            Raises:
+                ValueError: If inputs are invalid (e.g., wrong types, missing value, or value provided with dict).
+            """
+            if isinstance(param_or_dict, dict):
+                if value is not None:
+                    raise ValueError(
+                        "When defining multiple parameters with a dictionary, the 'value' argument is ignored. "
+                        "Use either define(param_id: str, value: Any) or define(params: Dict[str, Any])."
+                    )
+                for param_id, val in param_or_dict.items():
+                    self.parent.sequence.append(Define(param_id, val, condition))
+            elif isinstance(param_or_dict, str) and value is not None:
+                self.parent.sequence.append(Define(param_or_dict, value, condition))
+            else:
+                raise ValueError("Expected (param_id, value) or {param_id: value, ...}")
+            
+        def fork(self, param_or_dict: Union[str, Dict[str, Tuple[Any, ...]]], value_set: Optional[Tuple[Any, ...]] = None, condition: Optional[Callable[..., bool]] = None) -> None:
+            """Fork analysis with a single parameter or dictionary of parameter value sets.
+
+            Args:
+                param_or_dict: Parameter ID (str) or dictionary of parameter IDs to value sets.
+                value_set: Tuple of values for the parameter (if param_or_dict is a string).
+                condition: Optional condition function to determine if the step should run.
+
+            Examples:
+                >>> anal.add.fork('x', (0, 1, 2))  # Fork single parameter
+                >>> anal.add.fork({'x': (0, 1, 2), 'y': (0, 10, 20)})  # Fork multiple parameters
+
+            Raises:
+                ValueError: If inputs are invalid (e.g., wrong types, missing value_set, or value_set provided with dict).
+            """
+            if isinstance(param_or_dict, dict):
+                if value_set is not None:
+                    raise ValueError(
+                        "When forking multiple parameters with a dictionary, the 'value_set' argument is ignored. "
+                        "Use either fork(param_id: str, value_set: Tuple[Any, ...]) or fork(params: Dict[str, Tuple[Any, ...]])."
+                    )
+                self.parent.sequence.append(Fork(param_or_dict, condition))
+            elif isinstance(param_or_dict, str) and value_set is not None:
+                self.parent.sequence.append(Fork({param_or_dict: value_set}, condition))
+            else:
+                raise ValueError("Expected (param_id, value_set) or {param_id: value_set, ...}")
+            
+        def execute(self, func: Callable[..., Any], assign_to: Optional[Union[str, List[str], Tuple[str, ...]]] = None, unpack_result: bool = False, condition: Optional[Callable[..., bool]] = None) -> None:
+            """Execute a function and store its result in the ParameterSet.
+
+            Args:
+                func: Function to execute, taking parameter values as input.
+                assign_to: Custom Parameter ID(s) to store the result (str or list/tuple of strings).
+                unpack_result: If True, unpacks a dictionary result into multiple parameters.
+                condition: Optional condition function to determine if the step should run.
+
+            Examples:
+                >>> anal.add.execute(my_function)  # Execute function, store result
+                >>> anal.add.execute(my_function, assign_to='new_param')  # Execute function, store result to param: 'new_param'
+                >>> anal.add.execute(my_function_returns_dict, unpack_result=True)  # Unpack dict result
+                >>> anal.add.execute(my_function_returns_dict, assign_to=['out_1', 'out_2'], unpack_result=True)  # Unpack only dict keys: out_1, out_2
+
+            Raises:
+                ValueError: If func is not callable or assign_to is invalid.
+            """
+            self.parent.sequence.append(Execute(func, assign_to, unpack_result, condition))
+                
+        def optimize(self, func: Callable[..., float], opt_param_ids: Tuple[str, ...], assign_to: Optional[str] = None, direction: str = 'min', optimizer: Union[str, Callable] = 'SLSQP', tol: Optional[float] = None, bounds: Optional[Dict[str, Tuple[float, float]]] = None, options: Optional[Dict[str, Any]] = None, condition: Optional[Callable[..., bool]] = None, **kwargs) -> None:
+            """Optimize a function over specified parameters.
+
+            Args:
+                func: Objective function to optimize, returning a scalar.
+                opt_param_ids: Parameter IDs to optimize.
+                assign_to: Parameter ID to store the optimized value.
+                direction: Optimization direction ('min' or 'max').
+                optimizer: Optimization method (SciPy method name or callable).
+                tol: Tolerance for convergence.
+                bounds: Dictionary of parameter IDs to (min, max) tuples.
+                options: Additional optimizer options (e.g., maxiter, ftol).
+                condition: Optional condition function to determine if the step should run.
+                **kwargs: Additional arguments for the optimizer.
+
+            Examples:
+                >>> anal.add.optimize(rosenbrock, ('x', 'y'))  # Minimize with SLSQP
+                >>> anal.add.optimize(rosenbrock_neg, ('x', 'y'), direction='max', optimizer='Nelder-Mead')  # Maximize with Nelder-Mead
+
+            Raises:
+                ValueError: If inputs are invalid (e.g., invalid direction, optimizer).
+            """
+            self.parent.sequence.append(Optimize(func, opt_param_ids, assign_to, direction, optimizer, tol, bounds, options, condition, **kwargs))
+
+    def run(self,
+            # create_pandas = True,
+            # verbose = True
+        )  -> Dict[str, Any]:
+        """Execute the analysis sequence and return results including a DataFrame of leaf data.
+
+        Returns:
+            Dict[str, Any]: Dictionary containing the results DataFrame, runtime, and number of finished leaves.
+        """
+        self.t0 = time.time()
+        self.finished_leaves = 0
+        self.leaf_data = []  # Reset leaf data
+        try:
+            self._process(self.init_paramset, step_idx=0) # start on step 0
+        except Exception as e:
+            raise RuntimeError(f"Analysis failed: {str(e)}") from e
+        finally:
+            self.runtime = time.time() - self.t0
+
+        # Create DataFrame from collected leaf data
+        df = pd.DataFrame(self.leaf_data) if self.leaf_data else pd.DataFrame()
+
+        return dict(
+            df = df,
+            runtime = self.runtime,
+            finished_leaves = self.finished_leaves,
+        )
+
+    def _process(self, paramset: ParameterSet, step_idx:int):
+        """
+        Run a step of the analysis sequence and recursively process the next step.
+        """
+        try:
+            # Terminate branch if no more steps
+            if step_idx >= len(self.sequence):
+                self._end_sequence(paramset)
+                return
+
+            # Get current step
+            step: AnalysisStep = self.sequence[step_idx]
+
+            # Check step condition
+            try:
+                run_step = paramset.call_with_matched_kwargs(step.condition) if step.condition else True
+            except Exception as e:
+                raise RuntimeError(f"Error evaluating step condition: {str(e)}") from e
+
+            # Run the analysis step
+            t0 = time.time()
+            try:
+                new_paramsets = step.run(paramset) if run_step else (copy.deepcopy(paramset),)
+            except Exception as e:
+                raise RuntimeError(f"Error executing step: {str(e)}") from e
+            step_runtime = time.time() - t0
+        
+            # Handle branch termination
+            if new_paramsets is None:
+                self._end_sequence(paramset)
+                return
+
+            # Validate new paramsets
+            if not isinstance(new_paramsets, tuple) or not all(isinstance(ps, ParameterSet) for ps in new_paramsets):
+                raise ValueError(f"Invalid step result, Expected tuple of ParameterSet, got {type(new_paramsets)}")
+        
+        except Exception as e:
+            step_type = type(step).__name__
+            details = step.get_details()
+            raise RuntimeError(f"Error in {step_type} step at index {step_idx} with details {details}: {str(e)}") from e
+
+        # Process next step for each new parameter set (recursively)
+        for ps in new_paramsets:
+            ps.update_param('runtime', value=ps.get_value('runtime', 0.0) + step_runtime) # Update cumulative runtime
+            self._process(ps, step_idx + 1)
+
+    def _end_sequence(self, paramset: ParameterSet) -> None:
+        """Record data for a completed analysis leaf (the end of a branch)."""
+        self.finished_leaves += 1
+        leaf_dict = paramset.values_dict.copy()
+        leaf_dict['datetime'] = datetime.now()
+        self.leaf_data.append(leaf_dict)
+

{functioneer-0.3.0 → functioneer-0.4.0}/src/functioneer/parameter.py

@@ -175,7 +175,7 @@ class ParameterSet(dict[str, Parameter]):
         if missing_args:
             missing_args = [f"'{arg}'" for arg in missing_args]
             # TODO: catch this error higher up so we can provide info about WHAT param or function was being evaluated
-            raise ValueError(f"Missing the following required params while evaluating function: {', '.join(missing_args)}")
+            raise KeyError(f"Missing the following required params while evaluating function: {', '.join(missing_args)}")
 
         # Call the function with matched kwargs
         return func(**matched_kwargs)