sheap.Assistants.Parameters module

Parameter / Parameters with built-in support for shared (global) free parameters.

Key behavior

• If you do NOT use shared params:

  raw_init() returns:

  • (n_free,) for single spectrum

  • (n_spec, n_free) for batched spectra (same as your original code)

• If you DO use shared params (any Parameter with shared=True and not fixed and not tied):

  raw_init() returns a packed 1D vector:

  raw_packed = [ raw_shared (n_shared,) | raw_local_flat (n_spec * n_local,) ]

  raw_to_phys(raw_packed) returns:

  • (n_spec, n_total) (batched physical vectors, with shared params identical across spectra)

  phys_to_raw(phys) returns the same packed 1D vector.

Notes

• In shared-mode, at least ONE local (shared=False) parameter should carry a vector value of shape (n_spec,) so the class can infer n_spec.

• Shared free parameters should usually be provided as scalars (or 0-d arrays).

class Parameter(name, value, *, min=-inf, max=inf, tie=None, fixed=False, shared=False)

Bases: object

Represents a single fit parameter with optional bounds, ties, fixed status, and optional shared behavior across a batch (shared=True).

Parameters:

• name (str)

• value (float | jax.numpy.ndarray | List[float] | Tuple[float, ...])

• min (float)

• max (float)

• tie (Tuple[str, str, str, float] | None)

• fixed (bool)

• shared (bool)

class Parameters

Bases: object

Container for managing a list of Parameter instances.

Supports: - fixed params (excluded from optimization) - tied params (computed from sources) - bounded transforms (logistic / square / linear) - batched parameters (values as arrays) - shared free parameters (shared=True) as global hyper-parameters for batched fits,

with packing/unpacking handled internally.

Notes

• If any parameter has an array value with shape (n_spec,), we treat the container as batched.

• In shared-mode (at least one free shared parameter), raw space is a packed 1D vector:

  [raw_shared…, raw_local(spec0)… raw_local(spec1)…]

  and raw_to_phys returns a full physical array of shape (n_spec, n_total).

• IMPORTANT: In shared-mode, raw_to_phys broadcasts shared parameters across spectra in the returned phys array, so phys[:, idx_shared] is always shape (n_spec,) and can be fed into vmap(lambda A,m,s: …) directly (shared means identical values across the batch).

add(name, value, *, min=None, max=None, tie=None, fixed=False, shared=False)

Parameters:

• name (str)

• value (float | jax.numpy.ndarray | List[float] | Tuple[float, ...])

• min (float | None)

• max (float | None)

• tie (Tuple[str, str, str, float] | None)

• fixed (bool)

• shared (bool)

property names: List[str]

raw_init()

Initial raw vector from stored physical values.

Return type:

jax.numpy.ndarray

phys_init()

Build the initial physical parameter array from stored Parameter.value.

Returns:

• If n_spec == 1: shape (n_total,)

• If n_spec > 1: shape (n_spec, n_total)

Return type:

jnp.ndarray

Notes

• Scalar values are broadcast across spectra.

• Vector values (shape (n_spec,)) are taken per spectrum.

raw_to_phys(raw_params)

Convert raw parameter vector(s) to physical space.

• No shared free params: classic behavior.

• Shared free params: expects packed 1D raw and returns (n_spec, n_total), with shared params broadcast across spectra in the returned phys.

Parameters:

raw_params (jax.numpy.ndarray)

Return type:

jax.numpy.ndarray

phys_to_raw(phys_params)

Convert physical parameter vector(s) to raw space.

• No shared free params: classic behavior.

• Shared free params: expects (n_spec, n_total) and returns packed 1D raw.

Parameters:

phys_params (jax.numpy.ndarray)

Return type:

jax.numpy.ndarray

linear_phys_indices()

Return the indices in physical parameter space corresponding to linear parameters.

Physical-space indices always follow the full parameter ordering in self._list, so fixed and tied parameters are included if they are marked as linear.

Returns:

Integer array with the indices of linear parameters in the physical vector.

Return type:

jnp.ndarray

nonlinear_raw_indices()

Return the indices in raw optimization space corresponding to non-linear free parameters.

Notes

• Raw space only contains free parameters (tie is None and fixed is False).

• Parameters with linear_param=True are excluded.

• In classic mode (no shared free parameters), raw indices follow self._raw_list.

• In shared-mode, raw packing is:

  [raw_shared…, raw_local(spec0)… raw_local(spec1)…]

  so local non-linear indices are repeated for each spectrum.

• Shared non-linear parameters appear only once at the beginning of the packed raw vector.

Returns:

Integer array with the indices of non-linear free parameters in raw space.

Return type:

jnp.ndarray

property specs: List[Tuple[str, Any, float, float, str, bool, bool]]

(name, value, min, max, transform, fixed, shared)

property summary: List[Dict[str, Any]]

User-facing summary of parameters and definitions.

build_Parameters(tied_map, params_dict, initial_params, constraints)

Construct a Parameters object from initialization arrays, constraints, and tie definitions.

This helper builds a container of Parameter instances ready for fitting, applying bounds, fixed values, and tied relationships.

Parameters:

• tied_map (dict[int, tuple[int, str, float]]) –

  Mapping of parameter indices to tie definitions. Each entry is of the form idx_target -> (idx_source, op, operand), where:

  • idx_target is the index of the tied parameter,

  • idx_source is the index of the source parameter,

  • op is an arithmetic operator string ('*', '/', '+', '-'),

  • operand is a numeric factor or offset.

• params_dict (dict[str, int]) – Dictionary mapping parameter names to their index positions in the parameter vector.

• initial_params (array-like, shape (n_params,)) – Initial physical parameter values.

• constraints (array-like, shape (n_params, 2)) – Lower and upper bounds per parameter.

Returns:

A populated container with names, values, bounds, and tie definitions.

Return type:

Parameters

Notes

• Tied parameters are added with their tie attribute and are not optimized

  directly; their values are reconstructed from the source parameter during raw→physical mapping.

• Untied parameters are added with their initial value and bounds taken from

  constraints.

• Fixed parameters are not assigned here; add them via

  Parameters.add(..., fixed=True) if needed.

• Typically called by higher-level fitting routines (e.g., RegionFitting)

  when preparing parameter sets.