### Install refmod Python Library

Source: https://github.com/arunoruto/reflectance-models/blob/main/README.md

This command installs the refmod Python library using pip. Ensure you have Python and pip installed on your system. This is the primary method for obtaining the library for use in your projects.

```sh
pip install refmod
```

--------------------------------

### Hapke Class - Main Interface for Reflectance Calculations (Python)

Source: https://context7.com/arunoruto/reflectance-models/llms.txt

Demonstrates how to use the main Hapke class to create a model instance and calculate reflectance. This class provides a high-level interface for managing parameters and invoking reflectance calculations using either AMSA or IMSA models.

```python
import numpy as np
from refmod import Hapke

# Create a Hapke model instance with default parameters
hapke = Hapke(
    single_scattering_albedo=np.array([0.5, 0.6, 0.7]),  # Multi-wavelength albedo
    legendre_coefficients=np.array([1.0, 0.0, 0.5]),     # Phase function coefficients
    incidence_direction=np.array([0.5, 0.0, 0.866]),     # 30 degree incidence
    emission_direction=np.array([0.0, 0.0, 1.0]),        # Nadir viewing
    surface_orientation=np.array([0.0, 0.0, 1.0]),       # Flat surface
    roughness=0.2,                                        # Surface roughness (radians)
    shadow_hiding_h=0.06,                                 # Opposition effect parameter
    shadow_hiding_b0=1.0,                                 # Opposition effect amplitude
    model="amsa",                                         # Use AMSA model
    h_level=2                                             # H-function approximation level
)

# Calculate reflectance
reflectance = hapke.refl()
print(f"Reflectance values: {reflectance}")
# Output: Reflectance values: [0.0234... 0.0312... 0.0401...]
```

--------------------------------

### Calculate Legendre Coefficients 'b_n'

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/functions/legendre/index.rst

Calculates the coefficients 'b_n' for Legendre polynomial expansion, used in Hapke's photometric model for phase function representation.

```APIDOC
## GET /refmod/hapke/functions/legendre/coef_b

### Description
Calculates coefficients 'b_n' for Legendre polynomial expansion, used in Hapke's photometric model, specifically for the phase function representation.

### Method
GET

### Endpoint
/refmod/hapke/functions/legendre/coef_b

### Parameters
#### Query Parameters
- **b** (float) - Optional - Asymmetry parameter for the Henyey-Greenstein phase function component, by default 0.21.
- **c** (float) - Optional - Parameter determining the mixture of Henyey-Greenstein functions or a single function if NaN, by default 0.7. If `c` is `np.nan`, a single Henyey-Greenstein function is assumed.
- **n** (int) - Optional - The number of coefficients to calculate (degree of Legendre polynomial), by default 15. The resulting array will have `n + 1` elements.

### Response
#### Success Response (200)
- **coefficients** (array) - Array of 'b_n' coefficients, shape (n + 1,).

#### Response Example
```json
{
  "coefficients": [
    1.0, 0.21, 0.0441, 0.009261, 0.00194481, 0.0004084101, 0.000085766121, 0.00001799088541, 0.0000037780859365, 0.000000793398046465, 0.00000016661358975765, 0.0000000349888538490965, 0.000000007347659308309265, 0.00000000154290845474494565, 0.0000000003240107754964385865, 0.000000000068042262854252103165
  ]
}
```
```

--------------------------------

### Calculate Reflectance using refmod

Source: https://github.com/arunoruto/reflectance-models/blob/main/README.md

This Python code snippet demonstrates how to import the refmod library and use its functions to calculate surface reflectance based on Hapke model parameters. It requires NumPy for numerical operations and assumes basic knowledge of the Hapke model parameters.

```python
import refmod
import numpy as np

# Define Hapke parameters
incidence_angle = 30  # degrees
emission_angle = 0    # degrees
phase_angle = 30      # degrees
ssa = 0.8             # single scattering albedo
# ... other parameters like Henyey-Greenstein asymmetry parameter, porosity, etc.

# Calculate reflectance
# reflectance = refmod.hapke_isotropic(incidence_angle, emission_angle, phase_angle, ssa) # Example function
# print(f"Reflectance: {reflectance}")
```

--------------------------------

### Calculate Legendre Coefficients 'a_n'

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/functions/legendre/index.rst

Calculates the coefficients 'a_n' for Legendre polynomial series used in Hapke's photometric model.

```APIDOC
## GET /refmod/hapke/functions/legendre/coef_a

### Description
Calculates coefficients 'a_n' for Legendre polynomial series, which are used in Hapke's photometric model.

### Method
GET

### Endpoint
/refmod/hapke/functions/legendre/coef_a

### Parameters
#### Query Parameters
- **n** (int) - Optional - The number of coefficients to calculate (degree of Legendre polynomial), by default 15. The resulting array will have `n + 1` elements.

### Response
#### Success Response (200)
- **coefficients** (array) - Array of 'a_n' coefficients, shape (n + 1,).

#### Response Example
```json
{
  "coefficients": [
    1.0, 0.21, 0.0441, 0.009261, 0.00194481, 0.0004084101, 0.000085766121, 0.00001799088541, 0.0000037780859365, 0.000000793398046465, 0.00000016661358975765, 0.0000000349888538490965, 0.000000007347659308309265, 0.00000000154290845474494565, 0.0000000003240107754964385865, 0.000000000068042262854252103165
  ]
}
```
```

--------------------------------

### Perform Albedo Inversion using Hapke Model in Python

Source: https://context7.com/arunoruto/reflectance-models/llms.txt

The `Hapke.albedo()` method performs inverse modeling to derive single scattering albedo from measured reflectance values using least-squares optimization. It requires observation geometry, Hapke model parameters, and measured reflectance data.

```python
import numpy as np
from refmod import Hapke

# Setup observation geometry
incidence_direction = np.array([0.5, 0.0, 0.866]).reshape(1, 1, 3)
emission_direction = np.array([0.0, 0.0, 1.0]).reshape(1, 1, 3)
surface_orientation = np.array([0.0, 0.0, 1.0]).reshape(1, 1, 3)

# Create Hapke model for inversion (without albedo initially)
hapke = Hapke(
    legendre_coefficients=np.array([1.0, 0.21, 0.5]),
    incidence_direction=incidence_direction,
    emission_direction=emission_direction,
    surface_orientation=surface_orientation,
    roughness=0.1,
    shadow_hiding_h=0.05,
    shadow_hiding_b0=1.0,
    model="amsa",
    h_level=2
)

# Measured reflectance data (e.g., from spectroscopic observation)
measured_reflectance = np.array([0.025, 0.035, 0.045, 0.055])

# Invert to find single scattering albedo
recovered_albedo = hapke.albedo(
    reflectance=measured_reflectance,
    least_squares_param={"method": "lm"}  # Levenberg-Marquardt
)

print(f"Recovered albedo: {recovered_albedo.flatten()}")
```

--------------------------------

### Linear Mixing of Spectral End-Members (Python)

Source: https://context7.com/arunoruto/reflectance-models/llms.txt

Combines multiple spectral end-members to model intimate mixtures using the 'linear_mixing' function from 'refmod.mixing'. Requires numpy and inputs such as bulk density, end-member albedo, and phase functions.

```python
import numpy as np
from refmod.mixing import linear_mixing

# Define end-member properties (2 minerals, 50 wavelengths)
n_wavelengths = 50
n_endmembers = 2
n_angles = 181

# Single scattering albedo for each end-member (wavelengths x endmembers)
albedo_olivine = np.random.uniform(0.4, 0.6, n_wavelengths)
albedo_pyroxene = np.random.uniform(0.3, 0.5, n_wavelengths)
albedo = np.column_stack([albedo_olivine, albedo_pyroxene])

# Phase functions (angles x wavelengths) for each end-member
phase_olivine = np.ones((n_angles, n_wavelengths)) * 1.5  # Simplified
phase_pyroxene = np.ones((n_angles, n_wavelengths)) * 1.2
phase_functions = [phase_olivine, phase_pyroxene]

# Mixing proportions (bulk density ratios)
bulk_density = np.array([0.7, 0.3])  # 70% olivine, 30% pyroxene

# Calculate mixed albedo and phase function
mixed_albedo, mixed_phase = linear_mixing(
    bulk_density=bulk_density,
    albedo=albedo,
    phase_function=phase_functions,
    extinction_efficiency=None,  # Assume unity
    solid_density=None,          # Assume equal densities
    radius=None,                 # Assume equal particle sizes
    legendre_expansion=15,       # Number of Legendre terms
    theta_elements=181           # Output phase function angles
)

print(f"Mixed albedo shape: {mixed_albedo.shape}")
print(f"Mixed phase function shape: {mixed_phase.shape}")
print(f"Mixed albedo at wavelength 25: {mixed_albedo[25, 0]:.4f}")
```

--------------------------------

### Compute Legendre Polynomial Coefficients in Python

Source: https://context7.com/arunoruto/reflectance-models/llms.txt

Functions for computing Legendre polynomial coefficients, essential for phase function expansions and the Hapke model's anisotropic scattering formulation. Includes functions to calculate Hapke's `a_n` coefficients and convert Double Henyey-Greenstein parameters to Legendre expansions.

```python
import numpy as np
from refmod.hapke.functions.legendre import (
    coef_a,
    dhg_legendre_coefficients,
    legendre_eval,
    function_p,
    value_p
)

# Calculate Hapke's a_n coefficients (Eq. 27 from Hapke 2002)
n_terms = 15
a_n = coef_a(n=n_terms)
print(f"First 5 a_n coefficients: {a_n[:5]}")

# Convert Double Henyey-Greenstein to Legendre expansion
b, c = 0.21, 0.7
b_n = dhg_legendre_coefficients(b=b, c=c, n=n_terms)
print(f"First 5 b_n coefficients: {b_n[:5]}")

# Evaluate Legendre polynomial expansion at specific angles
cos_alpha = np.array([1.0, 0.5, 0.0, -0.5, -1.0])  # Phase angle cosines
phase_function_values = legendre_eval(cos_alpha, b_n)
print(f"Phase function values: {phase_function_values}")
```

--------------------------------

### Microscopic Roughness Calculation

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/functions/roughness/index.rst

Calculates the microscopic roughness factor and modified cosine terms for Hapke's reflectance model. This accounts for sub-resolution roughness effects on observed reflectance.

```APIDOC
## POST /arunoruto/reflectance-models/refmod.hapke.functions.roughness/microscopic_roughness

### Description
Calculates the microscopic roughness factor and modified cosine terms for Hapke's reflectance model. This accounts for sub-resolution roughness effects on observed reflectance.

### Method
POST

### Endpoint
/arunoruto/reflectance-models/refmod.hapke.functions.roughness/microscopic_roughness

### Parameters
#### Request Body
- **roughness** (float) - Required - The mean slope angle of surface facets, in radians. A value of 0 means a smooth surface.
- **incidence_direction** (npt.NDArray) - Required - Incidence direction vector(s), shape (..., 3). Assumed to be normalized.
- **emission_direction** (npt.NDArray) - Required - Emission direction vector(s), shape (..., 3). Assumed to be normalized.
- **surface_orientation** (npt.NDArray) - Required - Surface normal vector(s), shape (..., 3). Assumed to be normalized.

### Request Example
```json
{
  "roughness": 0.5,
  "incidence_direction": [0.1, 0.2, 0.9797958971132712],
  "emission_direction": [0.3, 0.4, 0.8717797887081348],
  "surface_orientation": [0.0, 0.0, 1.0]
}
```

### Response
#### Success Response (200)
- **s** (npt.NDArray) - The microscopic roughness factor, shape (...).
- **mu_0_prime** (npt.NDArray) - The modified cosine of the incidence angle ($mu_0^{prime}$), accounting for roughness, shape (...).
- **mu_prime** (npt.NDArray) - The modified cosine of the emission angle ($mu^{prime}$), accounting for roughness, shape (...).

#### Response Example
```json
{
  "s": 0.85,
  "mu_0_prime": 0.95,
  "mu_prime": 0.80
}
```

### Notes
- The calculations are based on Hapke (1984).
- Input vectors are normalized internally.
- If `roughness` is 0, `s` is 1, `mu_0_prime` is `cos(i)`, and `mu_prime` is `cos(e)`.
```

--------------------------------

### Hapke Base Class

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/index.rst

Provides a base class for creating Pydantic models used within the reflectance models framework. It includes standard Pydantic model attributes for introspection.

```APIDOC
## GET /refmod/hapke/base

### Description
Information about the base Hapke class, used for creating Pydantic models within the reflectance models library.

### Method
GET

### Endpoint
/refmod/hapke/base

### Parameters
None

### Response
#### Success Response (200)
- **class_name** (string) - The name of the class.
- **description** (string) - A brief description of the class's purpose.
- **attributes** (object) - Metadata about the model's attributes and variables.

#### Response Example
```json
{
  "class_name": "Hapke",
  "description": "A base class for creating Pydantic models.",
  "attributes": {
    "__class_vars__": "The names of the class variables defined on the model.",
    "__private_attributes__": "Metadata about the private attributes of the model.",
    "__signature__": "The synthesized __init__ Signature of the model.",
    "__pydantic_complete__": "Whether model building is completed, or if there are still undefined fields.",
    "__pydantic_core_schema__": "The core schema of the model."
  }
}
```
```

--------------------------------

### Generic Phase Function Selection and Evaluation

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/functions/phase/index.rst

Selects and evaluates a specified phase function based on the provided type and arguments. This endpoint acts as a dispatcher for different phase function models.

```APIDOC
## POST /arunoruto/reflectance-models/refmod.hapke.functions.phase/phase_function

### Description
Selects and evaluates a phase function based on the provided type and arguments.

### Method
POST

### Endpoint
/arunoruto/reflectance-models/refmod.hapke.functions.phase/phase_function

### Parameters
#### Request Body
- **cos_g** (ndarray) - Required - Cosine of the scattering angle (g).
- **type** (string) - Required - Type of phase function to use. Valid options are: "dhg" or "double_henyey_greenstein", "cs" or "cornette" or "cornette_shanks".
- **args** (tuple) - Required - Arguments for the selected phase function. For "dhg": (b, c) where b is asymmetry and c is backscatter fraction. For "cs": (xi,) where xi is the Cornette-Shanks asymmetry parameter.

### Request Example
```json
{
  "cos_g": [0.1, -0.9],
  "type": "dhg",
  "args": [0.2, 0.8]
}
```

### Response
#### Success Response (200)
- **phase_function_values** (ndarray) - Calculated phase function values.

#### Response Example
```json
{
  "phase_function_values": [0.555, 0.111]
}
```

#### Error Response (400)
- **error** (string) - Description of the error, e.g., "Unsupported phase function type."

#### Error Example
```json
{
  "error": "Unsupported phase function type."
}
```
```

--------------------------------

### Opposition Effect Functions (SHOE & CBOE) (Python)

Source: https://context7.com/arunoruto/reflectance-models/llms.txt

Models the shadow hiding (SHOE) and coherent backscattering (CBOE) opposition effects using functions from 'refmod.hapke.functions.opposition_effect'. Takes phase angles (converted to tan(alpha/2)) and parameters like angular width (h) and amplitude (b0) as input.

```python
import numpy as np
from refmod.hapke.functions.opposition_effect import shadow_hiding, coherant_backscattering

# Phase angle converted to tan(alpha/2)
phase_angles = np.linspace(0, 30, 31)  # degrees
alpha_rad = np.deg2rad(phase_angles)
tan_alpha_2 = np.tan(alpha_rad / 2)

# Shadow hiding opposition effect (SHOE)
h_sh = 0.06   # Typical for lunar regolith
b0_sh = 1.0   # Maximum amplitude

shoe = shadow_hiding(tan_alpha_2, h=h_sh, b0=b0_sh)
print(f"Shadow hiding at phase=0: {shoe[0]:.4f}")
print(f"Shadow hiding at phase=5: {shoe[5]:.4f}")
print(f"Shadow hiding at phase=30: {shoe[30]:.4f}")

# Coherent backscatter opposition effect (CBOE)
h_cb = 0.005  # Narrower than SHOE
b0_cb = 0.3   # Typically smaller than SHOE

cboe = coherant_backscattering(tan_alpha_2, h=h_cb, b0=b0_cb)
print(f"\nCoherent backscatter at phase=0: {cboe[0]:.4f}")
print(f"Coherent backscatter at phase=1: {cboe[1]:.4f}")
print(f"Coherent backscatter at phase=5: {cboe[5]:.4f}")
```

--------------------------------

### Microscopic Roughness Calculation

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/roughness/index.rst

Calculates the microscopic roughness factor and modified cosine values for Hapke's photometric model. This accounts for the effects of sub-resolution roughness on observed reflectance.

```APIDOC
## microscopic_roughness

### Description
Calculates the microscopic roughness factor for Hapke's model. This correction accounts for the effects of sub-resolution roughness on the observed reflectance.

### Method
POST

### Endpoint
/arunoruto/reflectance-models/refmod.hapke.roughness/microscopic_roughness

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **roughness** (float) - Required - The mean slope angle of surface facets, in radians. A value of 0 means a smooth surface.
- **incidence_direction** (npt.NDArray) - Required - Incidence direction vector(s), shape (..., 3). Assumed to be normalized.
- **emission_direction** (npt.NDArray) - Required - Emission direction vector(s), shape (..., 3). Assumed to be normalized.
- **surface_orientation** (npt.NDArray) - Required - Surface normal vector(s), shape (..., 3). Assumed to be normalized.

### Request Example
```json
{
  "roughness": 0.5,
  "incidence_direction": [0.1, 0.2, 0.9797958971132712],
  "emission_direction": [0.3, 0.4, 0.8660254037844386],
  "surface_orientation": [0.0, 0.0, 1.0]
}
```

### Response
#### Success Response (200)
- **s** (npt.NDArray) - The microscopic roughness factor, shape (...).
- **mu_0_prime** (npt.NDArray) - The modified cosine of the incidence angle (μ₀′), accounting for roughness, shape (...).
- **mu_prime** (npt.NDArray) - The modified cosine of the emission angle (μ′), accounting for roughness, shape (...).

#### Response Example
```json
{
  "s": 0.85,
  "mu_0_prime": 0.95,
  "mu_prime": 0.80
}
```

### Notes
The calculations are based on Hapke (1984).

- The terms μ₀′ (mu_0_s0, mu_0_s) and μ′ (mu_s0, mu_s) are calculated based on different conditions for incidence angle `i` and emission angle `e`:
  - For prime-zero terms (μ₀′(0), μ′(0) used in `mu_0_s0`, `mu_s0`): See Hapke (1984, Eqs. 48, 49).
  - For μ₀′ and μ′ when i < e: See Hapke (1984, Eqs. 46, 47).
  - For μ₀′ and μ′ when i ≥ e: See Hapke (1984, Eqs. 50, 51).

- Input vectors (`incidence_direction`, `emission_direction`, `surface_orientation`) are normalized internally.
- If `roughness` is 0, `s` is 1, `mu_0_prime` is `cos(i)`, and `mu_prime` is `cos(e)`.

### References
Hapke (1984)
```

--------------------------------

### AMSA Model Function for Reflectance Calculation (Python)

Source: https://context7.com/arunoruto/reflectance-models/llms.txt

Shows how to use the `amsa` function to calculate reflectance using the Anisotropic Multiple Scattering Approximation. This function requires detailed inputs for observation geometry, Hapke parameters, and optional effects like shadow hiding and coherent backscattering.

```python
import numpy as np
from refmod.hapke.models import amsa
from refmod.hapke.functions.legendre import coef_a, dhg_legendre_coefficients

# Define observation geometry (direction vectors with shape (3, height, width))
height, width = 100, 100
incidence_angle = np.deg2rad(30)
emission_angle = np.deg2rad(0)

# Create direction vectors
incidence_direction = np.array([np.sin(incidence_angle), 0, np.cos(incidence_angle)])
incidence_direction = incidence_direction.reshape(3, 1, 1)
incidence_direction = np.tile(incidence_direction, (1, height, width))

emission_direction = np.array([np.sin(emission_angle), 0, np.cos(emission_angle)])
emission_direction = emission_direction.reshape(3, 1, 1)
emission_direction = np.tile(emission_direction, (1, height, width))

surface_normal = np.array([0.0, 0.0, 1.0]).reshape(3, 1, 1)
surface_normal = np.tile(surface_normal, (1, height, width))

# Define Hapke parameters
single_scattering_albedo = np.random.uniform(0.3, 0.7, (height, width))
b, c = 0.21, 0.7  # Double Henyey-Greenstein parameters
b_n = dhg_legendre_coefficients(b, c, n=15)  # Legendre coefficients
a_n = coef_a(n=15)  # Hapke's a_n coefficients

# Calculate reflectance with AMSA model
reflectance = amsa(
    single_scattering_albedo=single_scattering_albedo,
    phase_function_legendre=b_n,
    incidence_direction=incidence_direction,
    emission_direction=emission_direction,
    surface_orientation=surface_normal,
    a_n=a_n,
    roughness=0.15,           # Surface roughness in radians
    shadow_hiding_h=0.06,     # Shadow hiding angular width
    shadow_hiding_b0=1.0,     # Shadow hiding amplitude
    coherant_backscattering_h=0.005,  # Coherent backscatter width
    coherant_backscattering_b0=0.3,   # Coherent backscatter amplitude
    h_level=2                 # H-function approximation level (1 or 2)
)

print(f"Reflectance shape: {reflectance.shape}")
print(f"Mean reflectance: {np.nanmean(reflectance):.6f}")
# Output: Reflectance shape: (100, 100)
# Output: Mean reflectance: 0.035421
```

--------------------------------

### Calculate P Function for Multiple Scattering (Python)

Source: https://context7.com/arunoruto/reflectance-models/llms.txt

Calculates the P function for multiple scattering using Hapke's model (2002, Eqs. 23-24) and a scalar P value (Hapke 2002, Eq. 25). Requires numpy and a function 'function_p' and 'value_p'.

```python
import numpy as np

# Assuming function_p and value_p are defined elsewhere
# For demonstration, let's define dummy functions:
def function_p(mu, b_n, a_n):
    return mu * (1 + b_n * mu**2 + a_n * mu**4)
def value_p(b_n, a_n):
    return 1 + b_n + a_n

mu = np.array([0.9, 0.7, 0.5])  # Cosines of angles
b_n = 0.5 # Example value
a_n = 0.2 # Example value
p_values = function_p(mu, b_n, a_n)
print(f"P function values: {p_values}")

p_scalar = value_p(b_n, a_n)
print(f"P scalar value: {p_scalar:.6f}")
```

--------------------------------

### Calculate Reflectance Derivative

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/amsa/index.rst

Calculates the derivative of the reflectance with respect to the single scattering albedo using various parameters.

```APIDOC
## POST /reflectance/derivative

### Description
Calculates the derivative of the reflectance with respect to the single scattering albedo. This endpoint utilizes provided directional, surface, and phase function parameters to compute the derivative.

### Method
POST

### Endpoint
/reflectance/derivative

### Parameters
#### Request Body
- **single_scattering_albedo** (npt.NDArray) - Required - Single scattering albedo.
- **incidence_direction** (npt.NDArray) - Required - Incidence direction vector(s) of shape (..., 3).
- **emission_direction** (npt.NDArray) - Required - Emission direction vector(s) of shape (..., 3).
- **surface_orientation** (npt.NDArray) - Required - Surface orientation vector(s) of shape (..., 3).
- **phase_function_type** (PhaseFunctionType) - Required - Type of phase function to use.
- **b_n** (npt.NDArray) - Required - Coefficients of the Legendre expansion.
- **a_n** (npt.NDArray) - Required - Coefficients of the Legendre expansion.
- **roughness** (float) - Optional - Surface roughness, by default 0.
- **hs** (float) - Optional - Shadowing parameter, by default 0.
- **bs0** (float) - Optional - Shadowing parameter, by default 0.
- **hc** (float) - Optional - Coherent backscattering parameter, by default 0.
- **bc0** (float) - Optional - Coherent backscattering parameter, by default 0.
- **phase_function_args** (tuple) - Optional - Additional arguments for the phase function, by default ().
- **refl_optimization** (npt.NDArray | None) - Optional - Reflectance optimization array. This parameter is not used in the derivative calculation, by default None.

### Response
#### Success Response (200)
- **derivative** (npt.NDArray) - The derivative of the reflectance with respect to single scattering albedo.

#### Response Example
```json
{
  "derivative": "[npt.NDArray representation]"
}
```

### References
- [AMSAModelPlaceholder]
```

--------------------------------

### Implement IMSA Model Function in Python

Source: https://context7.com/arunoruto/reflectance-models/llms.txt

The `imsa` function implements the Isotropic Multiple Scattering Approximation. It assumes isotropic multiple scattering while allowing anisotropic single scattering. This function requires geometry, single scattering albedo, phase function parameters, and surface properties as input.

```python
import numpy as np
from refmod.hapke.models import imsa
from refmod.hapke.functions.legendre import coef_a, dhg_legendre_coefficients

# Setup geometry for a planetary surface observation
incidence_angle = np.deg2rad(45)
emission_angle = np.deg2rad(30)

# Direction vectors (normalized 3D vectors)
i = np.array([np.sin(incidence_angle), 0, np.cos(incidence_angle)]).reshape(3, 1, 1)
e = np.array([np.sin(emission_angle), 0, np.cos(emission_angle)]).reshape(3, 1, 1)
n = np.array([0.0, 0.0, 1.0]).reshape(3, 1, 1)  # Surface normal

# Single scattering albedo (can be multi-wavelength)
albedo = np.array([0.4, 0.5, 0.6]).reshape(3, 1, 1)

# Phase function parameters
b_n = dhg_legendre_coefficients(b=0.21, c=0.7, n=15)
a_n = coef_a(n=15)

# Calculate IMSA reflectance
reflectance = imsa(
    single_scattering_albedo=albedo,
    b_n=b_n,
    incidence_direction=i,
    emission_direction=e,
    surface_orientation=n,
    a_n=a_n,
    roughness=0.1,                # Surface roughness (radians)
    opposition_effect_h=0.05,     # Opposition effect angular width
    opposition_effect_b0=0.8,     # Opposition effect amplitude
    h_level=1                     # H-function level (IMSA typically uses level 1)
)

print(f"IMSA Reflectance: {reflectance.flatten()}")
```

--------------------------------

### Calculate Hapke's P Function

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/functions/legendre/index.rst

Calculates the P function from Hapke's model, which relates to the integrated phase function and accounts for anisotropic scattering.

```APIDOC
## GET /refmod/hapke/functions/legendre/function_p

### Description
Calculates the P function from Hapke's model. This function relates to the integrated phase function and accounts for anisotropic scattering.

### Method
GET

### Endpoint
/refmod/hapke/functions/legendre/function_p

### Parameters
#### Query Parameters
- **x** (array) - Required - Input array, typically cosine of angles (e.g., mu, mu0).
- **b_n** (array) - Required - Array of 'b_n' coefficients.
- **a_n** (array) - Optional - Array of 'a_n' coefficients. If not provided or `None`, they are calculated using `coef_a(b_n.size)`.

### Response
#### Success Response (200)
- **p_function_values** (array) - Calculated P function values. The shape will match `x` after broadcasting.

#### Response Example
```json
{
  "p_function_values": [
    1.5, 1.6, 1.7
  ]
}
```
```

--------------------------------

### H-Function Calculations for Multiple Scattering (Python)

Source: https://context7.com/arunoruto/reflectance-models/llms.txt

Calculates the H-function, a key component of the Hapke model, using two approximation levels for multiple scattering. Requires numpy and functions from 'refmod.hapke.functions.h'. Handles single scattering albedo and cosine of angles as inputs.

```python
import numpy as np
from refmod.hapke.functions.h import h_function, h_function_1, h_function_2

# Cosine of angle (mu = cos(theta))
mu = np.linspace(0.1, 1.0, 10)

# Single scattering albedo values
w = np.array([0.3, 0.5, 0.7, 0.9])

# Create 2D grid for evaluation
mu_grid, w_grid = np.meshgrid(mu, w, indexing='ij')

# Level 1: Simple approximation (Hapke 1993, Eq. 8.31a)
h_level1 = h_function(mu_grid, w_grid, level=1)
print(f"H-function (level 1) for mu=0.5, w=0.7: {h_function_1(0.5, 0.7):.4f}")

# Level 2: More accurate approximation (Cornette & Shanks 1992)
h_level2 = h_function(mu_grid, w_grid, level=2)
print(f"H-function (level 2) for mu=0.5, w=0.7: {h_function_2(0.5, 0.7):.4f}")

# Compare levels for bright surface (high albedo)
print(f"\nH-function comparison at w=0.9:")
for m in [0.2, 0.5, 0.8, 1.0]:
    h1 = h_function_1(m, 0.9)
    h2 = h_function_2(m, 0.9)
    print(f"  mu={m:.1f}: Level 1={h1:.4f}, Level 2={h2:.4f}")
```

--------------------------------

### AMSA Model Calculation

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/index.rst

Calculates reflectance using the Arbitrary Multiple Scattering Approximation (AMSA) model. This model requires detailed inputs about the light's interaction with the surface.

```APIDOC
## POST /refmod/hapke/amsa

### Description
Calculates the reflectance using the AMSA model. This model is suitable for surfaces where multiple scattering and absorption effects are significant.

### Method
POST

### Endpoint
/refmod/hapke/amsa

### Parameters
#### Request Body
- **single_scattering_albedo** (NDArray) - Required - Single scattering albedo.
- **incidence_direction** (NDArray) - Required - Incidence direction vector(s) of shape (..., 3).
- **emission_direction** (NDArray) - Required - Emission direction vector(s) of shape (..., 3).
- **surface_orientation** (NDArray) - Required - Surface orientation vector(s) of shape (..., 3).
- **phase_function_type** (PhaseFunctionType) - Required - Type of phase function to use.
- **b_n** (NDArray) - Optional - Coefficients of the Legendre expansion.
- **a_n** (NDArray) - Optional - Coefficients of the Legendre expansion.
- **hs** (float) - Optional - Shadowing parameter, by default 0.
- **bs0** (float) - Optional - Shadowing parameter, by default 0.
- **roughness** (float) - Optional - Surface roughness, by default 0.
- **hc** (float) - Optional - Coherent backscattering parameter, by default 0.
- **bc0** (float) - Optional - Coherent backscattering parameter, by default 0.
- **phase_function_args** (tuple) - Optional - Additional arguments for the phase function, by default ().
- **refl_optimization** (NDArray | None) - Optional - Reflectance optimization array, by default None.

### Request Example
```json
{
  "single_scattering_albedo": "[numpy array]",
  "incidence_direction": "[numpy array]",
  "emission_direction": "[numpy array]",
  "surface_orientation": "[numpy array]",
  "phase_function_type": "HenyeyGreenstein",
  "hs": 0.1,
  "roughness": 0.5
}
```

### Response
#### Success Response (200)
- **reflectance** (NDArray) - Reflectance values.

#### Response Example
```json
{
  "reflectance": "[numpy array]"
}
```

#### Error Response (e.g., 400)
- **error** (string) - Description of the error, e.g., "Input validation failed."
- **details** (object) - Specific details about the error.

```json
{
  "error": "At least one reflectance value is not real."
}
```
```

--------------------------------

### H-Function Level 1 Calculation

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/functions/h/index.rst

Calculates the H-function (level 1) using the provided input parameter and single scattering albedo.

```APIDOC
## h_function_1

### Description
Calculates the H-function (level 1).

### Method
N/A (Function within a module)

### Endpoint
N/A (Function within a module)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
*   **x** (npt.NDArray) - Input parameter.
*   **w** (npt.NDArray) - Single scattering albedo.

### Returns
*   **h_function_values** (npt.NDArray) - H-function values.

### References
Hapke (1993, p. 121, Eq. 8.31a).
```

--------------------------------

### Vector Normalization Functions

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/functions/vectors/index.rst

Provides functions to normalize vectors by calculating their L2 norm. Includes options to keep dimensions for broadcasting.

```APIDOC
## normalize(x, axis = -1)

### Description
Normalizes a vector or a batch of vectors by calculating the L2 norm (Euclidean norm) along a specified axis.

### Method
N/A (This is a function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

## normalize_keepdims(x, axis = -1)

### Description
Normalizes a vector or batch of vectors, keeping the dimensions of the output for easier broadcasting during operations like division.

### Method
N/A (This is a function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### General H-Function Calculation

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/functions/h/index.rst

Calculates the Hapke H-function, supporting different levels (1 or 2).

```APIDOC
## h_function

### Description
Calculates the Hapke H-function. This function can compute two different versions (levels) of the H-function.

### Method
N/A (Function within a module)

### Endpoint
N/A (Function within a module)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
*   **x** (npt.NDArray) - Input parameter, often mu or mu_0 (cosine of angles).
*   **w** (npt.NDArray) - Single scattering albedo.
*   **level** (int, optional) - Level of the H-function to calculate (1 or 2), by default 1. Level 1 refers to `h_function_1`. Level 2 refers to `h_function_2`.

### Returns
*   **h_function_values** (npt.NDArray) - Calculated H-function values.

### Raises
*   **Exception**: If an invalid level (not 1 or 2) is provided.
```

--------------------------------

### H-Function Level 2 Calculation

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/functions/h/index.rst

Calculates the H-function (level 2) using the provided input parameter and single scattering albedo.

```APIDOC
## h_function_2

### Description
Calculates the H-function (level 2).

### Method
N/A (Function within a module)

### Endpoint
N/A (Function within a module)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
*   **x** (npt.NDArray) - Input parameter, often mu or mu_0 (cosine of angles).
*   **w** (npt.NDArray) - Single scattering albedo.

### Returns
*   **h_function_values** (npt.NDArray) - H-function values.

### References
Cornette and Shanks (1992).
```

--------------------------------

### General H-Function Derivative Calculation

Source: https://github.com/arunoruto/reflectance-models/blob/main/docs/source/autoapi/refmod/hapke/functions/h/index.rst

Calculates the derivative of the Hapke H-function with respect to w, supporting different levels (1 or 2).

```APIDOC
## h_function_derivative

### Description
Calculates the derivative of the Hapke H-function with respect to w. This function can compute the derivative for two different versions (levels) of the H-function.

### Method
N/A (Function within a module)

### Endpoint
N/A (Function within a module)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
*   **x** (npt.NDArray) - Input parameter, often mu or mu_0 (cosine of angles).
*   **w** (npt.NDArray) - Single scattering albedo.
*   **level** (int, optional) - Level of the H-function derivative to calculate (1 or 2), by default 1. Level 1 derivative is not implemented. Level 2 refers to `h_function_2_derivative`.

### Returns
*   **derivative_values** (npt.NDArray) - Calculated H-function derivative values.

### Raises
*   **NotImplementedError**: If level 1 is selected, as its derivative is not implemented.
*   **Exception**: If an invalid level (not 1 or 2) is provided.
```