epcsaft.parameters#

Read named, unit-bearing physical parameter declarations.

parameter_document selects and combines retained packet records; Parameters.from_mapping maps declared names and units into the native parameter owner (ALG-PARAMETERS). Source values, model choices and units remain explicit. Selecting components does not fit or validate parameters.

epcsaft.parameters.parameter_document(root: str | pathlib.Path, packets: collections.abc.Sequence[tuple[str, collections.abc.Sequence[str]]], *, k_ij: collections.abc.Mapping[tuple[str, str], float] | None = None, l_ij: collections.abc.Mapping[tuple[str, str], float] | None = None) → dict[str, object]#

Combine selected packet components into one parameter document.

Parameters:
  • root (str or pathlib.Path) – Packet root containing <packet>/parameters/parameters.json.

  • packets (sequence of tuple) – (Packet identifier/version, component identifiers) in output order.

  • k_ij (mapping of tuple of str to float, optional) – Dimensionless unlike dispersion-energy corrections. Each supplied value replaces that pair’s constant and temperature-law declarations.

  • l_ij (mapping of tuple of str to float, optional) – Dimensionless unlike diameter corrections, replacing existing values.

Returns:

document – Version-1 epcsaft.parameters declaration with retained source/domain materialization records. Unit-bearing scalar values keep their units.

Return type:

dict

Raises:
  • ParameterError – A packet form is unsupported, a selected component is absent, model choices/coefficients conflict, cation mixing is incompletely selected, or an override does not name two distinct selected components.

  • OSError – A packet file cannot be read.

  • json.JSONDecodeError – A packet contains invalid JSON; missing required keys raise KeyError.

Notes

Only records wholly within each packet’s component selection are retained. A component with no association sites can join the general-site model; other conflicting model choices are refused. Duplicate components are refused later by Parameters.from_mapping, not by this merge function.

class epcsaft.parameters.Parameters(native: epcsaft._core.Parameters, component_ids: tuple[str, ...], site_ids: tuple[tuple[str, str], ...])#

Keep ordered component names beside their native physical parameter record.

Variables:
  • component_ids (tuple of str) – Component order for all native input and output arrays.

  • site_ids (tuple of tuple of str) – Association sites in native order, each (component identifier, site name).

  • molar_masses (tuple of float) – Component molar masses in kg/mol, in component_ids order, read from the native parameter record.

Notes

Prefer from_json, from_packets or from_mapping for unit-bearing source records. The direct constructor only associates names with an existing native record; it does not read a source document.

__init__(native: epcsaft._core.Parameters, component_ids: tuple[str, ...], site_ids: tuple[tuple[str, str], ...]) → None#

Associate an existing native record with ordered component and site names.

Parameters:
  • native (_core.Parameters) – Native physical parameters, already expressed in their native units.

  • component_ids (tuple of str) – Component order matching native.

  • site_ids (tuple of tuple of str) – (Component, site) order matching native association coordinates.

Notes

This constructor assigns the inputs without validating their agreement. It retains no source document for later property/ASL serialization.

component_ids: tuple[str, ...]#
classmethod from_json(path: str | pathlib.Path, *, components: collections.abc.Sequence[str] | None = None) → Parameters#

Read a parameter JSON file and apply native parameter admission.

Parameters:
  • path (str or pathlib.Path) – Version-1 parameter document; each physical scalar declares its unit.

  • components (sequence of str, optional) – Selected component identifiers in desired order; default is file order.

Returns:

parameters – Ordered names, native physical values and retained parameter document.

Return type:

epcsaft.parameters.Parameters

Raises:
classmethod from_mapping(mapping: collections.abc.Mapping[str, object], *, components: collections.abc.Sequence[str] | None = None) → Parameters#

Map a unit-bearing parameter document into native physical parameters.

Parameters:
  • mapping (mapping of str to object) – epcsaft.parameters version 1: components, model choices, correlations, pair coefficients and association topology. Scalars carry magnitude and unit; temperature intervals use K, molar masses kg/mol, and native segment/Born diameters Å. Unit conversion is owned by native admission.

  • components (sequence of str, optional) – Unique selected identifiers in output order; default is document order.

Returns:

parameters – Admitted native record, ordered component/site names and source document.

Return type:

epcsaft.parameters.Parameters

Raises:
  • ParameterError – Unsupported document form, unread fields, duplicate/unknown identifiers, invalid units or physical values, unsupported correlations, conflicting parameter identities, model choices, pairs or association topology.

  • KeyError – A required nested record field is missing.

Notes

Only the declared selection is materialized; complete participants are required for retained cation-mixing terms. Correlations and general-site edges retain named identities. Native build_parameters owns the physical domain, units and admitted model families (ALG-PARAMETERS).

classmethod from_packets(root: str | pathlib.Path, packets: collections.abc.Sequence[tuple[str, collections.abc.Sequence[str]]], *, k_ij: collections.abc.Mapping[tuple[str, str], float] | None = None, l_ij: collections.abc.Mapping[tuple[str, str], float] | None = None) → Parameters#

Load a native parameter set from selected source packets.

Parameters:
  • root (str or pathlib.Path) – Root used by parameter_document.

  • packets (sequence of tuple) – (Packet identifier/version, ordered component identifiers).

  • k_ij (mapping of tuple of str to float, optional) – Dimensionless unlike dispersion corrections replacing source pair laws.

  • l_ij (mapping of tuple of str to float, optional) – Dimensionless unlike diameter corrections replacing source pair laws.

Returns:

parameters – Admitted native values with names in packet/component selection order.

Return type:

epcsaft.parameters.Parameters

Raises:

Notes

Packet combination follows parameter_document; no fitting or adoption of undeclared unlike interactions is performed here.

property molar_masses: tuple[float, ...]#

Read the native component molar masses.

Returns:

masses – Field documented with its unit and order in Parameters Attributes.

Return type:

tuple of float

site_ids: tuple[tuple[str, str], ...]#

Re-exported names#