feat: ✨ Add Orca Gaussian distribution model and update documentation (#1886)

* feat: ✨ Add Orca Gaussian distribution model and update documentation

* fix: 🧪 Update reference keys to include 'orcagaussian' and 'lorentzian' models

* refactor: ♻️ Refactor code structure for improved readability and maintainability

* fix: 🧪 Fix Orca Gaussian model and update tests for distribution models

* chore: 📝 Update docstring to use raw string for core Gaussian calculation

* fix: ✅ Add WidthAPI class for ORCA Gaussian model and update related tests

* fix: 🧪 Update Orca Gaussian model to use 'width' parameter and adjust related tests

* fix: 🧪 Update Gaussian model to use 'x_0' parameter and add tests for auto-parameter detection

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix: ✅ Refactor test functions in TestDefineParametersAuto for improved type hints and readability

* fix: ✅ Move Callable import under TYPE_CHECKING for improved clarity and organization

* chore: 🐛 Refactor imports and update linting configurations

- Consolidated multiple import statements into single lines for improved readability across various modules.
- Updated the linting configuration in trunk.yaml to enable isort and disable black.
- Removed unused imports and organized existing ones in several files to adhere to PEP 8 standards.
- Enhanced code clarity and maintainability by restructuring import statements in the spectrafit package.

* fix: ✅ Simplify Callable import logic for better readability

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: Anselmoo

.trunk/trunk.yaml

@@ -19,10 +19,9 @@ runtimes:
 lint:
   disabled:
     - black
-    - isort
     - markdown-table-prettify
   enabled:
-    - markdown-table-prettify@3.6.0
+    - isort@6.0.1
     - pre-commit-hooks@5.0.0:
         commands:
           - end-of-file-fixer

docs/doc/models.md

@@ -43,6 +43,10 @@ tags:
 
   Bell-shaped curve widely used for modeling spectral peaks.
 
+- :material-function-variant: **[Orca Gaussian Distribution](#orca-gaussian-distribution)**
+
+  Variant of Gaussian distribution with specific parameters.
+
 - :material-function-variant: **[Lorentzian Distribution](#lorentzian-distribution)**
 
   Distribution with wider tails than Gaussian, common in resonance phenomena.
@@ -155,6 +159,35 @@ Where:
       }
     ```
 
+### Orca Gaussian Distribution
+
+The [Orca][1] Gaussian distribution is a variant of the Gaussian distribution, defined by its amplitude, center, and width:
+$$f(x) = \frac{A}{\sigma\sqrt{2\pi}} \exp\left(-\frac{(x-\mu)^2}{2\sigma^2}\right)$$
+
+It is similar to the standard Gaussian distribution but uses a different notation for the amplitude with respect to the implementation in the  [`orca_mapspc`][2].
+
+Where:
+
+- $A$ is the amplitude
+- $\mu$ is the center (mean)
+- $\sigma$ is related to the full width at half maximum (FWHM) by $\text{FWHM} = 2\sigma\sqrt{2\ln{2}}$
+
+!!! example "ORCA Gaussian Model Parameters"
+
+    ```json
+         {
+        "peaks": {
+          "1": {
+            "gaussian": {
+              "amplitude": {"max": 2, "min": 0, "vary": true, "value": 1},
+              "center": {"max": 2, "min": -2, "vary": true, "value": 0},
+              "fwhmg": {"max": 0.5, "min": 0.02, "vary": true, "value": 0.1}
+            }
+          }
+        }
+      }
+    ```
+
 ### Lorentzian Distribution
 
 The Lorentzian distribution, also known as the Cauchy distribution, is characterized by wider tails compared to the Gaussian distribution:
@@ -351,3 +384,6 @@ For calculating the models, a few math constants are needed, which are implement
 - [Fitting Documentation](fitting.md)
 - [API Reference](../api/modelling_api.md)
 - [Changelog](../changelog.md)
+
+[1]: https://www.faccts.de/docs/orca/6.0/manual/#
+[2]: https://www.faccts.de/docs/orca/6.0/manual/contents/detailed/utilities.html

includes/abbreviations.md

@@ -77,6 +77,7 @@
 *[Normalization]: Scaling data to a common range or standard, often between 0 and 1 or based on a specific feature
 *[NumPy]: Fundamental package for scientific computing with Python
 *[Objective Function]: The function that an optimization algorithm seeks to minimize or maximize (e.g., sum of squared residuals in Least-Squares)
+*[ORCA]: A computational chemistry software package for quantum chemistry calculations
 *[Optimizer]: The algorithm (e.g., Levenberg-Marquardt, Nelder-Mead) used by the Minimizer to find the best-fit Parameters
 *[Overfitting]: Fitting a model too closely to the noise or random fluctuations in the data, rather than the underlying trend
 *[Pandas DataFrames]: Two-dimensional, size-mutable, and potentially heterogeneous tabular data structures in the Pandas Python library

spectrafit/__init__.py

@@ -13,12 +13,10 @@
 
 import sys
 import warnings
-
 from typing import Tuple
 
 from typing_extensions import Literal
 
-
 PYTHON_END_OF_LIFE: Tuple[Literal[3], Literal[8]] = (3, 8)
 
 if sys.version_info[:2] == PYTHON_END_OF_LIFE:

spectrafit/api/cmd_model.py

@@ -4,21 +4,18 @@
 from getpass import getuser
 from hashlib import sha256
 from socket import gethostname
-from typing import Any
-from typing import Dict
-from typing import List
-from typing import Optional
-from typing import Union
+from typing import Any, Dict, List, Optional, Union
 from uuid import uuid4
 
-from pydantic import BaseModel
-from pydantic import Field
-from pydantic import HttpUrl
+from pydantic import BaseModel, Field, HttpUrl
 from pydantic.functional_validators import field_validator
+
 from spectrafit import __version__
-from spectrafit.api.tools_model import AutopeakAPI
-from spectrafit.api.tools_model import DataPreProcessingAPI
-from spectrafit.api.tools_model import GlobalFittingAPI
+from spectrafit.api.tools_model import (
+    AutopeakAPI,
+    DataPreProcessingAPI,
+    GlobalFittingAPI,
+)
 
 
 class DescriptionAPI(BaseModel):

spectrafit/api/file_model.py

@@ -1,13 +1,9 @@
 """Definition of the data file model."""
 
 from pathlib import Path
-from typing import Callable
-from typing import List
-from typing import Optional
-from typing import Union
+from typing import Callable, List, Optional, Union
 
-from pydantic import BaseModel
-from pydantic import Field
+from pydantic import BaseModel, Field
 from pydantic.functional_validators import field_validator
 
 

spectrafit/api/models_model.py

@@ -1,12 +1,8 @@
 """Reference model for the API of the models distributions."""
 
-from typing import Callable
-from typing import List
-from typing import Optional
-
-from pydantic import BaseModel
-from pydantic import Field
+from typing import Callable, List, Optional
 
+from pydantic import BaseModel, Field
 
 __description__ = "Lmfit expression for explicit dependencies."
 
@@ -99,6 +95,16 @@ class FwhmvAPI(BaseModel):
     expr: Optional[str] = Field(default=None, description=__description__)
 
 
+class WidthAPI(BaseModel):
+    """Definition of the Width of the ORCA Gaussian of the models distributions."""
+
+    max: Optional[float] = Field(default=None, description="Maximum width.")
+    min: Optional[int] = Field(default=None, description="Minimum width.")
+    vary: bool = Field(default=True, description="Vary the width.")
+    value: Optional[float] = Field(default=None, description="Initial width value.")
+    expr: Optional[str] = Field(default=None, description=__description__)
+
+
 class GammaAPI(BaseModel):
     """Definition of the Gamma of the Voigt of the models distributions."""
 
@@ -190,6 +196,14 @@ class GaussianAPI(BaseModel):
     fwhmg: FwhmgAPI = FwhmgAPI()
 
 
+class OrcaGaussianAPI(BaseModel):
+    """Definition of the ORCA Gaussian of the models distributions."""
+
+    amplitude: AmplitudeAPI = AmplitudeAPI()
+    center: CenterAPI = CenterAPI()
+    width: WidthAPI = WidthAPI()
+
+
 class LorentzianAPI(BaseModel):
     """Definition of the Lorentzian of the models distributions."""
 
@@ -371,6 +385,7 @@ class DistributionModelAPI(BaseModel):
     """Definition of the models distributions."""
 
     gaussian: GaussianAPI = GaussianAPI()
+    orcagaussian: OrcaGaussianAPI = OrcaGaussianAPI()
     lorentzian: LorentzianAPI = LorentzianAPI()
     voigt: VoigtAPI = VoigtAPI()
     pseudovoigt: PseudovoigtAPI = PseudovoigtAPI()

spectrafit/api/notebook_model.py

@@ -1,16 +1,10 @@
 """Reference model for the API of the Jupyter Notebook interface."""
 
-from typing import List
-from typing import Optional
-from typing import Tuple
-from typing import Union
-
-from _plotly_utils.colors.carto import Burg
-from _plotly_utils.colors.carto import Purp_r
-from _plotly_utils.colors.carto import Teal_r
+from typing import List, Optional, Tuple, Union
+
+from _plotly_utils.colors.carto import Burg, Purp_r, Teal_r
 from _plotly_utils.colors.qualitative import Plotly as PlotlyColors
-from pydantic import BaseModel
-from pydantic import Field
+from pydantic import BaseModel, Field
 from pydantic.functional_validators import field_validator
 
 

spectrafit/api/pptx_model.py

@@ -2,23 +2,15 @@
 
 import re
 import tempfile
-
 from pathlib import Path
-from typing import Dict
-from typing import List
-from typing import Tuple
-from typing import Type
-from typing import Union
+from typing import Dict, List, Tuple, Type, Union
 
 import pandas as pd
 import pkg_resources
-
 from matplotlib import pyplot as plt
 from pptx.util import Pt
-from pydantic import BaseModel
-from pydantic import ConfigDict
-from pydantic import Field
-from pydantic import field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
 from spectrafit import __version__
 from spectrafit.plotting import PlotSpectra
 

spectrafit/api/report_model.py

@@ -1,10 +1,6 @@
 """Reference model for the API of the Jupyter Notebook report."""
 
-from typing import Any
-from typing import Dict
-from typing import Hashable
-from typing import List
-from typing import Union
+from typing import Any, Dict, Hashable, List, Union
 
 from dtale import __version__ as dtale_version
 from emcee import __version__ as emcee_version
@@ -14,15 +10,14 @@
 from numpy import __version__ as numpy_version
 from pandas import __version__ as pandas_version
 from plotly import __version__ as plotly_version
-from pydantic import BaseModel
-from pydantic import ConfigDict
-from pydantic import Field
+from pydantic import BaseModel, ConfigDict, Field
 from pydantic import __version__ as pydantic_version
 from scipy import __version__ as scipy_version
 from sklearn import __version__ as sklearn_version
+from statsmodels import __version__ as statsmodels_version
+
 from spectrafit.api.cmd_model import DescriptionAPI
 from spectrafit.api.tools_model import DataPreProcessingAPI
-from statsmodels import __version__ as statsmodels_version
 
 
 class CreditsAPI(BaseModel):