lingvo.core.hyperparams module

Defines Params base class, used for defining class/function parameters.

lingvo.core.hyperparams._QuoteString(s)

Quotes a string with appropriate quotes and escaping.

This performs lite escaping by choosing enclosing quotation marks that would escape the least (either single or double quotes) and escaping those quotes and the backslash. Note that this does not escape newlines. If the string contains embedded newlines, they will be output verbatim.

Parameters

s – String to quote.

Returns

Quotes string (possibly multiline).

lingvo.core.hyperparams._UnquoteString(quoted)

lingvo.core.hyperparams._EndsWithTerminalQuote(s, quote_char)

Returns whether a string ends with a valid terminal quote.

lingvo.core.hyperparams._IsNamedTuple(x)

Returns whether an object is an instance of a collections.namedtuple.

Examples:

_IsNamedTuple((42, 'hi')) ==> False
Foo = collections.namedtuple('Foo', ['a', 'b'])
_IsNamedTuple(Foo(a=42, b='hi')) ==> True

Parameters

x – The object to check.

class lingvo.core.hyperparams._SortedDict

Bases: dict

A dict with a __repr__ that is always sorted by key.

class lingvo.core.hyperparams._Param(name, default_value, description)

Bases: object

Stores data for a single parameter.

ToString(nested_depth)

Prints the parameter as a string.

Set(value)

Get()

GetDefault()

lingvo.core.hyperparams.CopyFieldsTo(from_p, to_p, skip=None, ignore_unknown_keys=False)

Copy fields from one Params to another, with optional skipped params.

Preserves type(to_p.Instantiate()). Use from_p.Copy() instead if requiring a deep copy of from_p, without updating to_p.

Parameters

• from_p – Source params to copy from.

• to_p – Destination params to copy to.

• skip – A string, a list of strings or None. Param names to skip. Automatically skips InstantiableParams’ ‘cls’ parameter.

• ignore_unknown_keys – if False: it will copy all keys and it will fail if from_p has a key that does not exist in to_p. If True: it will copy only keys which are common; it will not fail if there is no common keys at all; it will ignore keys which are different.

Returns

The updated to_p.

class lingvo.core.hyperparams.Params

Bases: object

Stores data for a set of parameters.

Provides attribute-based API, e.g. “params.foo = 5”. Uses internal {‘name’: _Param} dict for storing parameter data.

_ToString(nested_depth: int) → str

_SimilarKeys(name: str) → List[str]

Return a list of params keys that are similar to name.

_KeyErrorString(name: str) → str

Copy() → ParamsT

Creates a deep copy of self.

_CopyTo(res: ParamsT) → ParamsT

MergeCommonKeysFrom(other: ParamsT) → ParamsT

Merges common keys content from other with itself.

Define(name: str, default_value: Any, description: str) → None

Defines a parameter.

Parameters

• name – The parameter name. Must only contain lowercase letters, numbers, and underscores. Must start with lowercase letter.

• default_value – Default value for this parameter. May be None.

• description – String description of this parameter.

Raises

AttributeError – If parameter ‘name’ is already defined.

Freeze() → None

Marks this Params as immutable.

IsImmutable() → bool

Return whether this Params is immutable.

_GetNested(name: str) → Tuple[ParamsT, str]

Returns nested param by its name.

Set(**kwargs: Any) → ParamsT

Sets multiple parameters.

Dots in names indicate navigation into nested Params objects. We do not allow navigation into lists or dicts, and may ban these types altogether in favor of string representations.

Parameters

**kwargs – Name-value pairs to set.

Returns

self

Get(name: str) → Any

Get parameter.

Dots in names indicate navigation into nested Params objects. We do not allow navigation into lists or dicts, and may ban these types altogether in favor of string representations.

Parameters

name – (str) Name.

Returns

value.

Raises

AttributeError – if parameter is not found

Delete(*args) → ParamsT

Deletes multiple parameters.

Dots in names indicate navigation into nested Params objects. We do not allow navigation into lists or dicts, and may ban these types altogether in favor of string representations.

Parameters

*args – List of names.

Returns

self

IterParams() → Generator[Tuple[str, Any], None, None]

Pythonic dict-like iteration.

GetKeys() → List[str]

ToProto() → Hyperparam

Writes to a Hyperparams proto.

Serializes the Hyperparams into a proto that can be then written to disk or sent over the network. Note that serialization is not guaranteed to be unique or stable (this is a feature of protos themselves, not this code), so using it for fingerprinting for example may not be appropriate. Refer to the ToText() method for a serialization approach that Lingvo controls.

Returns

The serialized params as a Hyperparams proto.

classmethod FromProto(param_pb: Hyperparam) → ParamsT

Reads from a Hyperparams proto.

Visit(visit_fn: Callable[[str, Any], None], enter_fn: Optional[Callable[[str, Any], bool]] = None, exit_fn: Optional[Callable[[str, Any], None]] = None)

Recursively visits objects within this Params instance.

Visit can traverse Params, lists, tuples, dataclasses, and namedtuples.

By default, visit_fn is called on any object we don’t know how to traverse into, like an integer or a string. enter_fn and exit_fn are called on objects we can traverse into, like Params, lists, tuples, dataclasses, and namedtuples. We call enter_fn before traversing the object, and exit_fn when we are finished.

If enter_fn returns false, that means we shouldn’t traverse into the object; we call visit_fn on it instead and never call exit_fn.

Keys are of the form:

key.subkey when traversing Params objects
key[1] when traversing lists/tuples
key[subkey] when traversing dataclasses or namedtuples

Lists of (key, value) tuples are treated like namedtuples.

Parameters

• visit_fn – Called on every object that can’t be entered, or when enter_fn returns false.

• enter_fn – Called on every enter-able function. If this function returns false, we call visit_fn and do not enter the object.

• exit_fn – Called after an enter-able object has been traversed.

ToText(include_types: Literal[False] = False, separator: str = ':') → str

ToText(include_types: Literal[True], separator: str = ':') → Tuple[str, Dict[str, str]]

Encodes params into a simple text format.

Each param is represented as a single line in the output. The param name and value is separated by a “:”. The nest param name is separated by “.”. For values of non-trivial types (types other than int, float, bool, str, and a few, etc.), we just print out the name of its type.

Note that strings are enclosed in appropriate single or double quotes (whichever would involve the least escaping) and will have some characters backslash escaped. String properties can span multiple lines.

Parameters

• include_types – Should we return types of the values. If True, the types dict will be returned as a second val in a return tuple

• separator – Punctuation symbol used to separate param name and value.

Returns

The encoded text or (encoded text, types dict) if include_types is True.

FromText(text: str, type_overrides: Optional[Mapping[str, str]] = None) → ParamsT

Merges params specified in ‘text’ into ‘params’.

‘text’ follows the simple text format as produced by ToText. For a param specified in both ‘params’ and ‘text’, overwrites the value in ‘params’ according to ‘text’. Params specified in ‘text’ but not in ‘params’ are ignored.

Parameters

• text – A text representation of params.

• type_overrides – Overrides for the types of the params.

Returns

self

Raises

• AttributeError – text contains invalid parameter key

• ValueError – text contains invalid parameter value, or the format is wrong.

ToTextWithTypes() → str

Same as ToText but encodes both params and their types.

FromTextWithTypes(text: str) → ParamsT

Same as FromText but expects to have types encoded in the text.

TextDiff(other: ParamsT) → str

Return the differences between this object and another as a string.

Parameters

other – The other Params object.

Returns

A string of differences.

class lingvo.core.hyperparams.InstantiableParams(cls: Type[InstantiableParamsClsT])

Bases: Params, Generic[InstantiableParamsClsT]

Params which can be instantiated.

When using InstantiableParams, callers must provide a class which supports initialization using a Params instance.

This covers a common use case of Params to hold a configuration for a given class.

Instantiate(**kwargs) → InstantiableParamsClsT

Instantiate an instance that this Params is configured for.

Example

params = InstantiableParams(cls=MyObject) params.Define(‘weight’, 0.2, ‘Training weight.’) params.weight = 0.9 obj = params.Instantiate()

It’s common for classes to have a classmethod called Params that returns a pre-made InstantiableParams, like this:

params = MyObject.Params() params.weight = 0.9 obj = params.Instantiate()

By convention, anything that parameterizes the behavior of your class should be stored in this Params object. However, your class may also use shared state objects which aren’t really parameters, like a shared lock. These can be passed as extra arguments to Instantiate.

Example

lock = threading.Lock() params = MyObject.Params() obj_a = params.Instantiate(lock=lock) obj_b = params.Instantiate(lock=lock)

Parameters

**kwargs – Additional keyword arguments to pass to the constructor in addition to this Params object.

Returns

A constructed object where type(object) == cls.

Copy() → ParamsT

See base class.