geope.parameters

geope.parameters.Parameters

Central state object for the Basis -> Parameters -> Optimizer pipeline.

Holds the system description (basis, control/drift Hamiltonians, target), optimisation config (constraints, bounds, param_transform), and the live optimisation state (parameters, fidelity) that an optimiser such as Geope updates in place.

Attributes:

Name	Type	Description
basis		Full Basis for the system.
projected_basis		The controllable sub-Basis.
drift_basis		The drift sub-Basis, or None.
target		Target unitary as np.ndarray.
piecewise_steps		Number of piecewise-constant gate segments.
fixed_drift		Whether the drift contribution is held fixed.
control		The control dict used to build projected_basis.
drift_config		The dict used to build drift_basis.
pulse_constraints		Optional pulse-shape constraint config.
param_transform		Optional callable mapping experimental params to basis coefficients.
projective		Whether to optimise with the projective (SU) fidelity (True) or the phase-sensitive (U) fidelity.
n_experimental_params		Length of the experimental-parameter vector when param_transform is set.
constraint_arrays		List of linear-equality constraint vectors, after merging.
constraint_expander		Expansion matrix that maps free parameters into the projected basis under the constraints.
bounds		Pre-built bounds, or None.
drift_parameters		Drift parameter np.ndarray, or None.
seed		Optional random seed.
init_spread		Half-width of the uniform initial-parameter sampling.
parameters		Current parameter np.ndarray (full-basis), seeded to the initial guess and updated in place by an optimiser.
fidelity		Current fidelity value, or None before a run.
infidelity		1 - fidelity (None before a run).

projected_indices cached property

Boolean mask for the projected basis within the full basis.

drift_indices cached property

Boolean mask for the drift basis within the full basis.

All-False when there is no drift basis.

proj_drift_indices cached property

Combined boolean mask for projected and drift elements.

proj_drift_basis cached property

Combined projected-and-drift Basis object.

proj_indices_projdrift_basis cached property

Projected indices expressed within the combined proj+drift basis.

drift_indices_projdrift_basis cached property

Drift indices expressed within the combined proj+drift basis.

compute_U_fn cached property

Unitary-from-parameters function (wrapped when param_transform set).

fid_U_fn cached property

Fidelity-of-unitary function bound to target.

infid_U_fn cached property

Infidelity-of-unitary function bound to target.

infid_fn cached property

Infidelity as a function of the free parameters.

grad_fn cached property

Value-and-gradient of the infidelity (used by GRAPE).

hess_fn_autodiff cached property

Hessian of the infidelity (used by GRAPE).

hess_fn cached property

Manual (Goodwin–Kuprov) Hessian of the infidelity.

Analytic drop-in for hess_fn, built from the manual propagator derivatives instead of autodiff. Only available without a param_transform (the manual derivatives operate directly on the proj+drift basis coefficients).

jac_fn cached property

Jacobian of the unitary w.r.t. the free parameters.

Holomorphic autodiff in projected-basis mode; a real/imag-split Jacobian when param_transform is set (so the imaginary part is not discarded through the real-valued user transform).

geo_fn cached property

Geodesic-Hamiltonian function bound to target (used by GEOPE).

project_omegas_fn cached property

Projection of matrices onto the Lie-algebra basis (used by GEOPE).

gammas_and_omegas cached property

Combined gammas-and-omegas function for the GEOPE update step.

In param_transform (experimental) mode the omega projection has one free column per experimental parameter, so the projected-index restriction selects all of them.

__dict__ class-attribute

__doc__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__module__ class-attribute

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__weakref__ property

list of weak references to the object

basis_coefficients property

Current parameters mapped through param_transform if set.

Returns the induced basis coefficients corresponding to the current self.parameters. If param_transform is None this is just the current parameters.

infidelity property

1 - fidelity, or None before a run has computed it.

__init__(basis=None, control=None, drift=None, projected_basis=None, drift_basis=None, init_values=None, drift_values=None, target=None, piecewise_steps=1, fixed_drift=True, constraints=None, pulse_constraints=None, bounds=None, init_spread=0.1, seed=None, param_transform=None, n_experimental_params=None, projective=True)

Initialise a Parameters bundle.

Parameters:

Name	Type	Description	Default
basis	Basis | None	Full Basis. Required when constructing without an explicit external basis. If None, a default two-qubit Pauli basis is built.	None
control	dict | None	Dict of allowed controllable interactions, e.g. {1: ['x', 'y'], (1, 2): ['xx']}. Mutually exclusive with projected_basis.	None
drift	dict | None	Dict of fixed drift interactions, same format. Mutually exclusive with drift_basis.	None
projected_basis	Basis | None	Pre-built projected Basis. Used as an escape hatch when the projected subset can't be expressed as a control dict. Mutually exclusive with control.	None
drift_basis	Basis | None	Pre-built drift Basis. Mutually exclusive with drift.	None
init_values	dict | ndarray | None	Initial parameter values. May be a dict in the same format as control, or an np.ndarray.	None
drift_values	dict | ndarray | None	Drift parameter values. May be a dict or array.	None
target	ndarray | None	Target unitary.	None
piecewise_steps	int	Number of piecewise-constant gate segments. Defaults to 1.	1
fixed_drift	bool	Whether the drift contribution is held fixed. Defaults to True.	True
constraints	list | None	Optional list of linear-equality constraints, each either an np.ndarray of size projected_basis.lie_algebra_dim or a dict in the control format.	None
pulse_constraints	dict | list | None	Optional pulse-shape constraints whose temporal profile is frozen during optimisation. In projected space, a control-format dict {qubit_index_or_tuple: [lowercase op labels]} (the same format as control), e.g. {1: ['x'], (1, 2): ['zz']}. In experimental space (param_transform set), a list of integer parameter indices. Forwarded to Geope. A dict that names an interaction absent from the projected basis raises ValueError.	None
bounds	dict | None	Optional dict mapping interaction label to (min, max) bound tuples.	None
init_spread	float	Half-width of uniform initialisation. Defaults to 0.1.	0.1
seed	int | Array | None	Optional random seed. Defaults to jax.random.key(0).	None
param_transform	Callable | None	Optional callable mapping experimental params to basis coefficients. May take (phi,) or (phi, step_index).	None
n_experimental_params	int | None	Number of experimental parameters when param_transform is set. Defaults to projected_basis.lie_algebra_dim.	None
projective	bool	If True (default), use the projective (SU) fidelity. If False, use phase-sensitive (U) fidelity.	True

to_dict()

Export the current basis coefficients as a control-style dict.

Returns a dict keyed by qubit index (or qubit-index tuple) whose values are dicts mapping lower-case interaction labels to real coefficient values.

geope.utils.make_per_element_transform(transforms)

Build a param_transform from per-element callables.

Each entry of transforms maps a single experimental parameter to a single basis coefficient. Use None to mean identity.

Parameters:

Name	Type	Description	Default
transforms	list[Callable | None]	List of callables (or None), one per basis element.	required

Returns:

Type	Description
Callable	A callable mapping a phi vector to a coefficients vector,
Callable	suitable for Parameters(param_transform=...).

Example

transforms = [lambda x: jnp.exp(1j*x), jnp.cos, None].

geope.utils.filter_basis_by_control(basis, control)

Filter a Basis keeping only operators that match a control dict.

For each basis element, inspect its label, build the qubit-index key (a single integer for 1-body terms, a tuple for multi-body) and the lower-case interaction label, then keep the element only if control[key] lists the interaction.

Parameters:

Name	Type	Description	Default
basis	Basis	The full Basis to filter.	required
control	dict	Dict mapping qubit index (or tuple of indices) to a list of interaction labels, e.g. {1: ['x', 'y'], (1, 2): ['xx']}.	required

Returns:

Type	Description
Basis	A new Basis containing only the matching operators. The
Basis	returned basis preserves basis._n_qubits_override if set.