API reference#

Every name designspace exports, grouped by purpose. The pages are generated from the docstrings, so they carry the same text help() returns.

Building a space#

The entry points, and the builder view a parameter takes on once its type is chosen.

`designspace.BoolParamExpr`(path, domain, ...)	A boolean parameter, declared by .bool().
`designspace.CategoricalParamExpr`(path, ...)	An unordered choice among values, declared by .categorical().
`designspace.ChoiceParamExpr`(path, domain, ...)	A branch among alternatives, declared by .choice().
`designspace.CodeParamExpr`(path, domain, ...)	.code()'s return type, a thin leaf view, always non-generative.
`designspace.CustomParamExpr`(path, domain, ...)	.custom()'s return type, a thin leaf view.
`designspace.FreshParamExpr`(path, domain, ...)	What ds.param(name) returns: a parameter with no type chosen yet.
`designspace.IntegerParamExpr`(path, domain, ...)	An integer parameter, declared by .integer().
`designspace.ListParamExpr`(path, domain, ...)	.repeat()'s return type; re-offers .repeat() (inherited from TypedParamExpr) for nested/variadic lifts.
`designspace.OrdinalParamExpr`(path, domain, ...)	An ordered choice among values, declared by .ordinal().
`designspace.ParamExpr`(path, domain, ...)	A parameter, either being declared or being referred to.
`designspace.PermutationParamExpr`(path, ...)	An ordering of items, declared by .permutation().
`designspace.RealParamExpr`(path, domain, ...)	A continuous parameter, declared by .real().
`designspace.Space`(params, conditions, ...], ...)	A resolved design space: the set of configurations you can draw from.
`designspace.StructParamExpr`(path, domain, ...)	A named group of parameters, declared by .space().
`designspace.SubsetParamExpr`(path, domain, ...)	A selection of items, declared by .subset().
`designspace.SymbolicParamExpr`(path, domain, ...)	.symbolic()'s return type, a thin leaf view, mirroring CustomParamExpr.
`designspace.TypedParamExpr`(path, domain, ...)	A parameter whose type has been chosen.
`designspace.param`(name)	Begin declaring a parameter called name.
`designspace.space`(*exprs)	Resolve parameter builders into a Space.

Expressions#

Conditions, constraints, and derived quantities. Expressions are values: they can be built, passed around, and walked through .kind and .children.

`designspace.ArithExpr`()	An expression node that evaluates to a scalar (numeric or otherwise) value.
`designspace.BoolExpr`()	An expression node that evaluates to a (Kleene) truth value.
`designspace.Expr`()	An expression: the shared base of conditions and arithmetic.
`designspace.Prop`(operand, name)	ds.param("c").prop(name): a custom type's declared scalar property (int/float/bool/str only).
`designspace.Value`(fn, operands, returns)	ds.value(fn, operands, returns=type): an opaque derived quantity: .prop() generalized from one custom param, named property* to any operands, arbitrary function.
`designspace.all_`(*exprs)	Combine conditions with and.
`designspace.any_`(*exprs)	Combine conditions with or.
`designspace.count`(*exprs)	How many of exprs are true, as a number.
`designspace.value`(fn, *operands, returns)	Compute a derived quantity with your own function.

Working with configs#

Reshaping a config without going through a space.

`designspace.config_diff`(a, b, space)	What changed between two configurations.
`designspace.destructure`(config, param_path)	Both the variant name and its payload, in one call.
`designspace.flatten`(config, space)	Turn a nested configuration into one keyed by path.
`designspace.is_flat`(config, space)	Whether a configuration is already keyed by path.
`designspace.payload`(config, param_path)	The parameters carried by a choice parameter's selected variant.
`designspace.unflatten`(flat, space)	Rebuild a nested configuration from one keyed by path.
`designspace.variant`(config, param_path)	Which variant a choice parameter selected.

Rendering#

Every public object renders itself for a person through str(). pretty prints a configuration read against its space.

designspace.pretty(obj[, space, width, ...])

Render obj for a person to read.

Sampling and validation results#

What the sampling and checking surfaces hand back.

`designspace.ConstraintEval`(constraint, ...)	One constraint evaluated against one configuration.
`designspace.ConstraintReport`(constraint, ...)	One SamplingReport.constraints row.
`designspace.ParamDiff`(param, old, new)	One difference between two configurations, from ds.config_diff().
`designspace.ParamError`(param, reason, value)	One parameter's value rejected during validation.
`designspace.PartialEval`(param_status, ...)	What Space.evaluate_partial() found: the state of a partial configuration.
`designspace.SamplingReport`(n, ...)	What Space.sampling_report(n, seed, tighten_bounds) returns.
`designspace.SubspaceInfo`(prefix, kind, ...)	One nested region of a space, from Space.subspaces.
`designspace.ValidationResult`(valid, ...)	What Space.validate() found.

Identity and serialization#

Fingerprints identify spaces; config hashes identify points in one.

designspace.config_hash(config, space)

A stable digest identifying one configuration.

The representation layer#

A Representation is the Space to Space morphism between a genotype and its phenotype.

`designspace.Encoding`(args, *kwargs)	The genotype for one param.
`designspace.EncodingRule`
`designspace.Representation`(source, target, ...)	A Space → Space morphism carrying a value-level decode/encode pair.
`designspace.RepresentationCheck`(n, ok, failures)	What Representation.check() found: a report, never an exception.
`designspace.RepresentationCheckFailure`(law, ...)	One law Representation.check() found violated.

The IR#

The resolved form. Every introspection surface hands back these types, and they are what a solver walks.

`designspace.BoolDomain`()	The two truth values, declared by .bool().
`designspace.CategoricalDomain`(values)	An unordered set of values, declared by .categorical().
`designspace.Chart`(args, *kwargs)	A monotone map from [0, 1] onto a parameter's domain.
`designspace.ChoiceDomain`(variants, has_payload)	A branch among named variants, declared by .choice().
`designspace.CodeDomain`(signature[, ...])	Freeform source code, declared by .code().
`designspace.Condition`(target, expr, params)	When one parameter is active, as resolved IR.
`designspace.Constraint`(expr, hard, origin, ...)	A restriction on which configurations are valid, as resolved IR.
`designspace.CustomDomain`([param_type, ...])	A consumer-supplied type, declared by .custom().
`designspace.Domain`	Represent a PEP 604 union type
`designspace.IntegerDomain`(lo, hi)	A range of integers, declared by .integer().
`designspace.IntegerRemaining`(lo, hi, grid)	What an integer parameter may still take, given a partial configuration.
`designspace.ListDomain`(element_kind, ...[, ...])	A list of independent copies, declared by .repeat().
`designspace.OrdinalDomain`(values)	An ordered set of values, declared by .ordinal().
`designspace.ParamDef`(path, type_kind, ...[, ...])	One resolved parameter: the introspection surface.
`designspace.PermutationDomain`(items)	An ordering of all items, declared by .permutation().
`designspace.PermutationRemaining`(items)	What a permutation parameter may still order.
`designspace.QuantizedSpec`(step, factor[, ...])	A grid restricting a numeric domain, set by .quantized().
`designspace.RealDomain`(lo, hi)	A continuous interval, declared by .real().
`designspace.RealRemaining`(lo, hi, ...)	What a real parameter may still take, given a partial configuration.
`designspace.RemainingDomain`	Represent a PEP 604 union type
`designspace.StructDomain`()	A named group of parameters, declared by .space().
`designspace.SubsetDomain`(items, min_size, ...)	A selection of items, declared by .subset().
`designspace.SubsetRemaining`(forced_in, ...)	What a subset parameter may still select, given a partial configuration.
`designspace.SymbolicDomain`(signature, ...[, ...])	A symbolic expression tree, declared by .symbolic().
`designspace.TypeKind`
`designspace.ValueRemaining`(values)	What a bool, categorical, ordinal, or choice parameter may still take.
`designspace.param_from_def`(pd)	Turn a resolved parameter back into a builder.
`designspace.space_from_ir`(params, ...[, ...])	Build a Space directly from IR, bypassing the builders.

Support types#

Priors, program-parameter vocabulary, and the custom-type protocols.

`designspace.FloatLiteral`(lo, hi)	A range of real constants admissible in a .symbolic() tree.
`designspace.IntLiteral`(lo, hi)	A range of integer constants admissible in a .symbolic() tree.
`designspace.Log`()	A logarithmic prior: equal weight per order of magnitude.
`designspace.Logit`()	A logit prior: weight concentrated toward both ends of (0, 1).
`designspace.ParamType`(args, *kwargs)	The full .custom(param_type) protocol.
`designspace.Power`(p)	A power prior: u ** p weighting toward one end of the domain.
`designspace.Primitive`(name, arity[, fn])	An operator declared for a .symbolic() parameter, with its arity.
`designspace.Prior`(args, *kwargs)	A distribution you supply yourself, for .prior().
`designspace.PriorSpec`	Represent a PEP 604 union type
`designspace.Signature`(args, returns)	The interface a .symbolic() or .code() parameter must satisfy.
`designspace.Weights`(values)	Relative weights over a discrete parameter's values.

Errors#

Every error designspace raises names the offending definition path.

`designspace.DesignSpaceError`	Base of the designspace exception taxonomy.
`designspace.ResolutionError`	Raised when a declaration cannot be resolved into a space.
`designspace.SamplingError`	Raised when a draw cannot be produced.
`designspace.SerializationError`	Raised when a space cannot be written out or read back.

Type aliases#

The names the public signatures are written in. Each is exactly the spelling shown. They carry no behaviour, and exist so that a signature can be followed to a definition instead of guessed at.

designspace.Config = dict[str, Any]#: A configuration: one point of a space, keyed by instance path. Values are in phenotype form; inactive parameters are absent rather than null.

designspace.Seed = int | numpy.random.Generator | None#: What every sampling surface accepts as its source of randomness. An int seeds reproducibly, a Generator is used as given, None draws fresh entropy.

designspace.OnUnserializable = Literal["raise", "mark", "drop"]#: What to_json does with something it cannot serialize.

designspace.FingerprintScope = Literal["full", "sampling"]#: Which facts a fingerprint covers: document identity, or what fixes the feasible set and the sampling measure.

designspace.FingerprintUnserializable = Literal["raise", "mark"]#: As OnUnserializable, minus drop, because dropping a site would change what is being identified.