.. _pfs-solution:

=====================================
Parametric Frequency Sweep (PFS)
=====================================

NeurEco's Parametric Frequency Sweep (PFS) solution builds models that predict complex-valued frequency responses based on input parameters. PFS is designed for frequency domain modeling, parametric model order reduction, and transfer function interpolation.

.. contents:: On this page
   :local:
   :depth: 2

What PFS Solves
===============

PFS models learn the relationship between:

- **Input parameters** (frequency + design variables) -> **Complex frequency response**

This is particularly useful for:

- **Electromagnetic simulations**: Predicting S-parameters, antenna responses, filter characteristics
- **Structural dynamics**: Frequency response functions (FRFs), transfer functions
- **Acoustic modeling**: Sound transmission, vibration analysis
- **Model order reduction**: Creating fast-running surrogate models from expensive frequency sweeps

Key Characteristics
===================

**Complex-Valued Outputs**

Unlike other NeurEco templates, PFS models output complex numbers (magnitude and phase), making them suitable for frequency domain analysis.

**Rational Function Approximation**

PFS uses rational functions internally, which naturally capture poles and zeros in frequency response data. The denominator size indicates model complexity.

**First Column = Frequency**

**The first column of input data must always be the frequency** — this is a strict requirement, not optional. Even when evaluating at a single constant frequency, the frequency column must be present. Additional columns contain design parameters.

When to Use PFS
===============

.. list-table::
   :header-rows: 1
   :widths: 50 50

   * - Use PFS When
     - Consider Alternatives When
   * - Outputs are complex-valued (magnitude + phase)
     - Outputs are real-valued only
   * - Frequency is a key input variable
     - No frequency dependence
   * - Data exhibits resonant behavior (poles/zeros)
     - Response is smooth and simple
   * - You need to interpolate frequency responses
     - You need time-domain predictions

File Extension
==============

PFS models use the ``.efnn`` extension (e.g., ``my_model.efnn``).

Getting Started
===============

.. toctree::
   :maxdepth: 1

   workflow
   examples/index

Quick Example
=============

.. code-block:: python

   from NeurEco import NeurEcoFrequential as Frequential
   import numpy as np

   # Load data (frequency + parameters -> complex response)
   x_train = np.load('inputs_train.npy')   # Shape: (n_samples, n_inputs), first col = frequency
   y_train = np.load('targets_train.npy')  # Shape: (n_samples, n_outputs), dtype: complex128

   # Build model
   model = Frequential.PFS()
   config = Frequential.PFSBuildConfig(
       input_data=x_train,
       output_data=y_train,
       write_model_to="./my_pfs_model.efnn",
   )
   model.build(config)

   # Evaluate
   predictions = model.evaluate(x_test)
   print(f"Output dtype: {predictions.dtype}")  # complex128