transforms class

class pycif.utils.classes.transforms.Transform(plg_orig=None, orig_name='', **kwargs)

Bases: Setup

Plugin type for data transformations in the inversion pipeline.

Transforms operate on tracers and fluxes, participate in the forward and adjoint mapper chain, and can propagate incompatible metadata (dates, domains, tracers) across the pipeline. Ensemble/MC batch perturbations are handled via mapper2batch().

Concrete implementations live in pycif/plugins/transforms/.

start_pipe = False

end_pipe = False

initiate_template()

Initialise the Transform plugin template.

Loads the registered transform module and attaches all standard methods (ini_mapper, forward, adjoint, mapper2batch, perturb_transform, flushrun, propagate_incompatible_input_dates, propagate_incompatible_domain, propagate_incompatible_tracer, propagate_incompatible_files) as bound methods on this instance.

classmethod register_plugin(name, version, module, subtype='', **kwargs)

Register a module for a plugin and version with possibly options

Parameters:

• name (str) – name of the plugin

• version (str) – version of the plugin

• module (types.ModuleType) – module defining the interface between pyCIF and the plugin

• plugin_type (str) – type of plugin

• **kwargs (dictionary) – default options for module

classmethod get_transform(plg)

Load and return the Transform plugin registered under the given plugin’s name.

Parameters:

plg (Plugin) – Plugin whose orig_name identifies the transform to load.

Returns:

Loaded transform plugin instance.

Return type:

Transform

perturb_transform(*args, **kwargs)

Default empty perturb_transform method.

Do nothing by default.

If specified in the corresponding plugin, the function should perturb its own behaviour beyond the mapper if necessary.

For instance, for models, it is necessary to update the chemical scheme to know which species should be accounted for

ini_mapper(*args, **kwargs)

Default empty ini_mapper method

flushrun(*args, **kwargs)

Default empty flushrun method for transforms

mapper2batch(nsamples, transf_mapper, all_mapper, all_transforms, dir_samples, file_samples, **kwargs)

Expand a transform’s mapper to handle a batch of ensemble/MC samples.

For each output tracer ID that feeds a perturbed successor, nsamples copies are created (suffixed __sample#NNN). The corresponding input tracer IDs are duplicated in the same way so that the full pipeline can process all samples in a single forward/adjoint pass.

Special handling is applied for the toobsvect plugin (observation vector aggregation) and for transforms whose inputs differ from their outputs (controlled via the outputs2inputs mapper sub-dict).

After expanding inputs and outputs, subsimus sub-simulation entries are also duplicated and perturb_transform() is called once to let the plugin adjust its own internal state.

Parameters:

• nsamples (int) – Number of ensemble / Monte Carlo samples.

• transf_mapper (dict) – Mapper dict for this transform, containing "inputs", "outputs", "precursors", "successors", "outputs2inputs", and "subsimus" sub-dicts. Modified in-place.

• all_mapper (dict) – Full pipeline mapper keyed by transform index, used to check whether a tracer ID is directly consumed by a successor without perturbation.

• all_transforms (list) – Ordered list of all transform instances in the pipeline.

• dir_samples (str) – Directory where per-sample working files are stored.

• file_samples (str) – Path template for per-sample file names.

• **kwargs – Forwarded to perturb_transform().

Returns:

The updated transf_mapper with all sample expansions

applied.

Return type:

dict

propagate_incompatible_dates(*args, **kwargs)

Default empty propagate_incompatible_dates method for transforms

propagate_incompatible_input_dates(*args, **kwargs)

Default empty propagate_incompatible_dates method for transforms

propagate_incompatible_domain(*args, **kwargs)

Default empty propagate_incompatible_domain method for transforms

propagate_incompatible_tracer(*args, **kwargs)

Default empty propagate_incompatible_tracer method for transforms

propagate_incompatible_input_files(*args, **kwargs)

Default empty propagate_incompatible_files method for transforms

propagate_incompatible_all_successors_initialized(transf_mapper, trid, mode, **kwargs)

Default empty propagate_incompatible_all_successors_initialized method for transforms

propagate_incompatible(transf_mapper, attributes, trid, anyNone, mode='backward', **kwargs)

Propagate incompatible metadata attributes from outputs to inputs.

For each attribute in attributes, delegates to the corresponding propagate_incompatible_<attribute> method on this instance (e.g. propagate_incompatible_domain, propagate_incompatible_tracer).

Propagation is skipped when anyNone is True and at least one downstream output has not yet been fully initialised (i.e. all_successors_initialized is not set), ensuring that the mapper is only updated once the complete downstream context is known.

Parameters:

• transf_mapper (dict) – Mapper dict for this transform (modified in-place by the per-attribute delegate methods).

• attributes (list[str]) – Names of the metadata attributes to propagate (e.g. ["domain", "tracer", "input_dates"]).

• trid (tuple) – Tracer identifier (component, name) for the input whose metadata is being propagated.

• anyNone (bool) – If True, propagation is deferred until all successor outputs report all_successors_initialized=True.

• mode (str) – Propagation direction — "backward" (default) or "forward".

• **kwargs – Forwarded to each per-attribute delegate method.

classmethod generate_inputs2outputs(transf_mapper)

Build the inverse of the outputs→inputs mapping.

Inverts transf_mapper["outputs2inputs"] so that each input tracer ID is mapped to the list of output tracer IDs that depend on it.

Parameters:

transf_mapper (dict) – Mapper dict containing at least "inputs" and "outputs2inputs" keys.

Returns:

Mapping {input_trid: [output_trid, ...]} for every

input tracer ID currently in transf_mapper["inputs"].

Return type:

dict

clean_input_dates(mapper)

Cleaning input dates to make sure they are of proper format and consistent with output dates

Parameters:

mapper (dict[str]) – dictionary of the mapper.

Returns:

cleaned input_dates

Return type:

dict[str]