LION.utils.spec

Specs: a LION component written as the call that builds it, in JSON.

LION writes them, as metadata, when it saves a component; they are not meant to be written by hand. A spec is plain JSON in which a dict with "_target_" means “call this”:

{“_target_”: “LION.models.CNNs.UNets.Unet.UNet”,

“model_parameters”: {“_target_”: “LION.models.LIONmodel.LIONModelParameter”,

“inChan”: 1, …}}

_target_ is the import path of a class, _args_ its positional arguments and every other key a keyword argument. "_call_": false refers to a class or function without calling it. A dict without _target_ (in older files) is a LIONParameter. The keys follow Hydra’s instantiate convention.

• to_spec(obj) writes the spec of an object. An object’s arguments are its attributes with the names of its constructor’s arguments (LION’s components keep each argument under its own name; torch losses and metrics do too). A class can define spec_kwargs() to give them itself. A torch optimizer is written with its hyperparameters; its parameters are given when building. A learning-rate scheduler is written with its arguments; its optimizer is given when building.

• build(spec) makes the object again. A spec names code to run, so only targets in allowed modules are imported, and only classes are called (plus numpy.array); functions are only referred to. Add your own modules with allow=.

• X.instantiate(source), on LION’s components (LIONmodel, LIONDataset, Experiment), makes the component a saved file describes, through instantiate(spec, cls, base). X.load(source) also restores its state (a model’s weights).

Functions

build(spec[, allow])	Make the object a spec describes.
build_arguments(spec[, allow])	A spec's target path and its built keyword arguments, without calling it (to call another class, e.g. the one Model.load() is called on).
encode(value)	A value as JSON: plain JSON types as they are, everything else as the spec of the call that makes it.
encode_or_name(value[, what])	encode(value), or, for a value a spec can't hold (a lambda, a class that doesn't keep its arguments), {"unsaved": repr, "reason": ...} with a warning.
import_path(x)	The import path of a class or function.
instantiate(spec, cls, base[, allow])	Make the component a spec describes, as cls (see target_class); arguments replace recorded ones.
is_allowed(path[, allow])	Whether build may import path (ALLOWED_MODULES, ALLOWED_TARGETS, and the module prefixes in allow).
is_unsaved(value)	A value a record could only name (encode_or_name).
parameters(spec, name, cls, base[, allow])	What the component's default_parameters() gives, as the spec records it (its argument name, e.g. "model_parameters"), to change and make the component with.
read(source)	Saved metadata, as a dict: the path of a .json (or of a model's files, e.g. "model.pt" or "model": its .json is read), a dict already read from one, or a LIONParameter (e.g. a record).
resolve(path[, allow])	The class or function at an import path, if it is allowed.
target_class(path, cls, base[, allow])	The class to make for a spec naming path, when cls.instantiate (or cls.load) is called: the class the spec names if cls is the base class (LIONmodel, LIONDataset, Experiment), which must derive from it; otherwise cls, with a warning if the spec names another class.
to_spec(obj)	The spec of an object: its class and the arguments that build it.
unknown_names(parameters, defaults[, ignore])	Names in parameters that defaults doesn't have (likely typos).
warn_unknown_names(owner, parameters, defaults)	Warn about names in parameters that defaults doesn't have.

---

LION.utils.spec.build(spec, allow=(), **kwargs)

Make the object a spec describes.

allow: more module prefixes (e.g. ["my_package."]) whose classes may be built. kwargs are added to the top-level call, for arguments that are live objects, e.g. build(optimizer_spec, params=model.parameters()).

LION.utils.spec.build_arguments(spec, allow=())

A spec’s target path and its built keyword arguments, without calling it (to call another class, e.g. the one Model.load() is called on).

LION.utils.spec.encode(value)

A value as JSON: plain JSON types as they are, everything else as the spec of the call that makes it.

LION.utils.spec.encode_or_name(value, what='it')

encode(value), or, for a value a spec can’t hold (a lambda, a class that doesn’t keep its arguments), {"unsaved": repr, "reason": ...} with a warning. For records, which describe what they can and name the rest.

LION.utils.spec.import_path(x)

The import path of a class or function.

LION.utils.spec.instantiate(spec, cls, base, allow=(), **arguments)

Make the component a spec describes, as cls (see target_class); arguments replace recorded ones. Used by the instantiate() class methods of LION’s components.

LION.utils.spec.is_allowed(path, allow=())

Whether build may import path (ALLOWED_MODULES, ALLOWED_TARGETS, and the module prefixes in allow).

LION.utils.spec.is_unsaved(value)

A value a record could only name (encode_or_name).

LION.utils.spec.parameters(spec, name, cls, base, allow=())

What the component’s default_parameters() gives, as the spec records it (its argument name, e.g. "model_parameters"), to change and make the component with. The class’s defaults if the spec has none (it was made with them). Used by the parameters_from_file() class methods.

LION.utils.spec.read(source)

Saved metadata, as a dict: the path of a .json (or of a model’s files, e.g. "model.pt" or "model": its .json is read), a dict already read from one, or a LIONParameter (e.g. a record).

LION.utils.spec.resolve(path, allow=())

The class or function at an import path, if it is allowed.

LION.utils.spec.target_class(path, cls, base, allow=())

The class to make for a spec naming path, when cls.instantiate (or cls.load) is called: the class the spec names if cls is the base class (LIONmodel, LIONDataset, Experiment), which must derive from it; otherwise cls, with a warning if the spec names another class.

LION.utils.spec.to_spec(obj)

The spec of an object: its class and the arguments that build it.

LION.utils.spec.unknown_names(parameters, defaults, ignore=())

Names in parameters that defaults doesn’t have (likely typos).

LION.utils.spec.warn_unknown_names(owner, parameters, defaults, ignore=())

Warn about names in parameters that defaults doesn’t have.