def composition_from_fractions(
    elements: Sequence[str],
    fractions: Sequence[float],
    charge_states: Sequence[float],
    *,
    target_zeff: Optional[float],
    masses: Optional[Sequence[float]] = None,
    main_ion: str = "H",
    status: str = "explicit",
    source: str = "caller",
) -> ImpurityComposition:
    """An impurity composition from parallel lists of elements, relative fractions and charge states.

    The form issue #1565 Sec. 2 names (``species=["C", "O", "N"]``,
    ``fractions=[0.3, 0.4, 0.3]``) with the one addition it requires: the
    charge state of each species is stated, never read off the atomic number.

    Parameters
    ----------
    elements : sequence of str
        Element symbols [-].
    fractions : sequence of float
        Relative particle densities, non-negative; normalised internally, the
        given values kept in ``input_record`` [-].
    charge_states : sequence of float
        Ionic charge of each species, in ``(0, Z_n]`` [-].
    target_zeff : float or None
        Plasma effective charge to close the composition at [-].
    masses : sequence of float, optional
        Species masses; default the standard atomic weights [u].
    main_ion : str, optional
        Main-ion element, default ``"H"`` [-].
    status : str, optional
        One of :data:`COMPOSITION_KINDS`, default ``"explicit"`` [-].
    source : str, optional
        Where the composition came from, for provenance [-].

    Returns
    -------
    ImpurityComposition
        The validated composition [any].

    Raises
    ------
    ValueError
        Lists of unequal length, an unknown element, a charge state outside
        ``(0, Z_n]``, negative fractions or a bad status.

    Applicability
    -------------
    Machine-independent.
    """
    n = len(elements)
    if len(fractions) != n or len(charge_states) != n or (masses is not None and len(masses) != n):
        raise ValueError("elements, fractions, charge_states (and masses) must have equal lengths")
    species = tuple(
        ImpuritySpecies(
            element=str(elements[k]),
            charge_state=float(charge_states[k]),
            relative_density=float(fractions[k]),
            mass=None if masses is None else float(masses[k]),
        )
        for k in range(n)
    )
    record = {"elements": list(elements), "fractions": [float(v) for v in fractions],
              "charge_states": [float(v) for v in charge_states]}
    return ImpurityComposition(species=species, target_zeff=target_zeff, main_ion=main_ion,
                               status=status, source=source, input_record=record)

def composition_from_model(model: Mapping[str, Any], *, source: Optional[str] = None) -> ImpurityComposition:
    """An impurity composition from a parsed machine ``impurity_model`` record.

    Parameters
    ----------
    model : mapping
        A record as :func:`vaft.machine_mapping.core_profiles.vest_impurity_model`
        returns it: ``status``, ``species`` (element, charge_state, mass,
        relative_density), ``target_zeff``, ``reduction``, ``main_ion`` and
        ``provenance`` [any].
    source : str, optional
        Provenance label; default the record's own ``provenance.source`` [-].

    Returns
    -------
    ImpurityComposition
        The composition, with ``status`` ``"assumed"``, ``"measured"`` or
        ``"derived"`` as the preset's own ``status`` (``inferred`` and any
        other value map to ``derived``) [any].

    Raises
    ------
    ValueError
        A malformed record (as :class:`ImpuritySpecies` validates it).

    Applicability
    -------------
    Machine-independent.
    """
    species = tuple(
        ImpuritySpecies(
            element=str(item["element"]),
            charge_state=float(item["charge_state"]),
            relative_density=float(item["relative_density"]),
            mass=float(item["mass"]) if item.get("mass") is not None else None,
        )
        for item in model["species"]
    )
    provenance = dict(model.get("provenance") or {})
    # measured stays measured, inferred is a derived kind (COMPOSITION_KINDS has no
    # "inferred"), assumed stays assumed; anything else is derived
    status = {"assumed": "assumed", "measured": "measured", "inferred": "derived"}.get(model.get("status"), "derived")
    return ImpurityComposition(
        species=species,
        target_zeff=model.get("target_zeff"),
        main_ion=str(model.get("main_ion", "H")),
        reduction=str(model.get("reduction", "preserve_charge_z2_mass")),
        status=status,
        source=source or str(provenance.get("source", "machine preset")),
        input_record={"model_status": model.get("status"), **provenance},
    )

def composition_record_origin(record: Any) -> Optional[str]:
    """The ``origin`` a composition record states, or ``None`` when it states none.

    Parameters
    ----------
    record : str or None
        A ``*_fit.parameters`` record [-].

    Returns
    -------
    str or None
        One of :data:`COMPOSITION_ORIGINS`, ``"unknown"`` for an ``origin``
        outside them, or ``None`` for an absent record or one without an
        ``origin`` field (an unlabelled value) [-].

    Applicability
    -------------
    Machine-independent.
    """
    if record is None:
        return None
    for part in str(record).replace("\n", ";").split(";"):
        match = _RECORD_FIELD.fullmatch(part)
        if match and match.group(1).lower() == "origin":
            origin = match.group(2).strip().lower()
            return origin if origin in COMPOSITION_ORIGINS else "unknown"
    return None

def composition_record_text(origin: str, method: str, **fields: Any) -> str:
    """The record a writer stores beside a composition or Z_eff it put into ``core_profiles``.

    Parameters
    ----------
    origin : str
        One of :data:`COMPOSITION_ORIGINS` [-].
    method : str
        How the value was obtained, e.g. ``impurity_model_preset``; further
        keyword arguments are appended as ``key=value`` fields, in order [-].

    Returns
    -------
    str
        ``origin=<origin>; method=<method>[; key=value...]`` [-].

    Raises
    ------
    ValueError
        An unknown origin, or a ``;`` or ``=`` inside a value.

    Applicability
    -------------
    Machine-independent.
    """
    if origin not in COMPOSITION_ORIGINS:
        raise ValueError(f"origin must be one of {COMPOSITION_ORIGINS}, got {origin!r}")
    parts = [f"origin={origin}", f"method={method}"]
    for key, value in fields.items():
        text = f"{value:g}" if isinstance(value, float) else str(value)
        if ";" in text or "=" in text:
            raise ValueError(f"field {key} carries a separator: {text!r}")
        parts.append(f"{key}={text}")
    return "; ".join(parts)

def populate_zeff_profile(
    ods: Any,
    resolved: ResolvedImpurityComposition,
    *,
    time: Optional[float] = None,
    tolerance: float = 5e-4,
    method: Optional[str] = None,
) -> Any:
    """A copy of ``ods`` whose ``core_profiles`` slice carries the resolved Z_eff(rho).

    Parameters
    ----------
    ods : ODS
        Source; never modified [any].
    resolved : ResolvedImpurityComposition
        From :func:`resolve_impurity_composition`; not of kind ``measured`` [any].
    time : float, optional
        Slice time; default the resolved composition's own [s].
    tolerance : float, optional
        Largest ``|t_slice - time|`` accepted [s].
    method : str, optional
        ``method=`` field of the record; default ``<kind>_composition`` [-].

    Returns
    -------
    ODS
        A deep copy with ``profiles_1d.zeff`` and ``profiles_1d.zeff_fit.parameters``
        (``origin=assumed|derived; method=...``) written [any].

    Raises
    ------
    ValueError
        A measured composition (already in ``core_profiles``), no slice at the
        time, or no electron density.

    Convention
    ----------
    The record's ``origin`` is ``assumed`` for an explicit or preset
    composition (Z_eff is then the assumed target) and ``derived`` for one
    computed from other data; :func:`resolve_impurity_composition` never reads
    either back as a measured target.  A measured ``zeff`` is never
    overwritten: a composition closed at it is left with the slice's own
    measured profile and record.

    Applicability
    -------------
    Machine-independent.

    Provenance
    ----------
    .. [issue] #1565 Sec. 5 (core_profiles.zeff from the resolved composition).
    """
    work = copy.deepcopy(ods)
    index, ne, rho = _write_slice(work, resolved, time, tolerance)
    base = f"core_profiles.profiles_1d.{index}"
    if "measured" in resolved.zeff_source:
        return work  # the slice already carries the measured profile it was closed at
    if composition_record_origin(_get(work, f"{base}.zeff_fit.parameters")) == "measured":
        raise ValueError(f"{base}.zeff is labelled measured; it is never overwritten")
    zeff, filled = _fill_undefined(_on_grid(resolved.zeff, resolved, rho, ne.size), rho)
    work[f"{base}.zeff"] = zeff
    record = _record(resolved, "zeff", method)
    work[f"{base}.zeff_fit.parameters"] = record + (f"; filled_points={filled}" if filled else "")
    return work