geope.gecko

geope.gecko.Gecko

Null-space ("auxiliary cost") optimiser for GEOPE solutions.

Gecko post-processes an already-found GEOPE solution: it moves the parameters within the Jacobian null space so that fidelity is preserved while an auxiliary cost is improved — smoothing, frequency shaping, pulse length, gate speed, robustness, or parameter bounds.

A Gecko is constructed from a Parameters object — the same object a Geope uses. The optimisation functions are read off params (built lazily and cached there), so to post-process a Geope solution, pass that Geope's params::

g = Geope(p); g.optimize()
Gecko(g.params).smooth(...)

Because the functions are cached on params, the Gecko reuses the Geope's already-compiled traces rather than recompiling.

Attributes:

Name	Type	Description
params		The bound Parameters object (live optimisation state).
history		Optional History logger (None unless supplied).
step_size		Transient last optimisation rate.
pulse_constraints		Optional pulse-shape constraint config.
constraint_expander		Linear-equality constraint expander (from params).
drift_parameters		Drift parameter np.ndarray (None in experimental / param_transform mode).

.. note:: The Parameters object is shared with the source Geope. A null-space pass with piecewise_steps_multiplier > 1 subdivides the pulse and advances params.parameters / params.piecewise_steps in place — so the shared Geope's state moves forward too, and a later geope.optimize() continues from the subdivided pulse.

__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

__init__(params, history=None, verbose=False)

Initialise the Gecko optimiser.

Parameters:

Name	Type	Description	Default
params	Parameters	A Parameters instance — the same object a Geope uses. Pass a Geope's geope.params to post-process its solution; the cached optimisation functions are reused.	required
history	History | None	Optional History logger. When supplied, the run trajectory is recorded into it.	None
verbose	bool	Whether to print progress. Defaults to False.	False

Raises:

Type	Description
TypeError	If params is not a Parameters instance.

smooth(piecewise_steps_multiplier=1, smoothing_rate=0.01, max_smoothing_steps=100, diff_tol=0.1)

Smooth the piecewise-constant pulse by null-space optimisation.

Minimises the differences between consecutive gate segments while remaining in the null space of the Jacobian so that fidelity is preserved.

Parameters:

Name	Type	Description	Default
piecewise_steps_multiplier	int	Factor by which to increase the number of gate segments. Defaults to 1.	1
smoothing_rate	float	Learning rate for the null-space update. Defaults to 0.01.	0.01
max_smoothing_steps	int	Maximum smoothing iterations. Defaults to 100.	100
diff_tol	float	Convergence tolerance on the smoothing cost. Defaults to 0.1.	0.1

Returns:

Type	Description
bool	A tuple (success, iters) where success is True if
int	diff_tol was reached.

smooth_frequency(piecewise_steps_multiplier=1, smoothing_rate=0.01, max_smoothing_steps=100, diff_tol=0.1)

Suppress high-frequency spectral power in the pulse.

Parameters:

Name	Type	Description	Default
piecewise_steps_multiplier	int	Factor by which to subdivide gate segments. Defaults to 1.	1
smoothing_rate	float	Learning rate. Defaults to 0.01.	0.01
max_smoothing_steps	int	Maximum iterations. Defaults to 100.	100
diff_tol	float	Convergence tolerance on the spectral cost. Defaults to 0.1.	0.1

Returns:

Type	Description
tuple[bool, int]	A tuple (success, iters).

filter_frequency(filter_fn, piecewise_steps_multiplier=1, smoothing_rate=0.01, max_smoothing_steps=100, diff_tol=0.1)

Drive the pulse toward filter_fn(rfft(pulse)).

Parameters:

Name	Type	Description	Default
filter_fn	Callable[[Array], Array]	Complex-array filter applied to the rfft of phi.	required
piecewise_steps_multiplier	int	Factor by which to subdivide gate segments. Defaults to 1.	1
smoothing_rate	float	Learning rate. Defaults to 0.01.	0.01
max_smoothing_steps	int	Maximum iterations. Defaults to 100.	100
diff_tol	float	Convergence tolerance. Defaults to 0.1.	0.1

Returns:

Type	Description
tuple[bool, int]	A tuple (success, iters).

speed(parameter_labels=None, parameter_indices=None, piecewise_steps_multiplier=1, optimization_rate=0.01, max_optimization_steps=100, diff_tol=0.1)

Minimise the peak amplitude of selected projected parameters.

Cost: \(\max_{g,k\in P}|\phi_k(g)|\). Minimising it raises the gate-speed limit.

Parameters:

Name	Type	Description	Default
parameter_labels	list[str] | None	Projected-basis labels to minimise.	None
parameter_indices	tuple[int, ...] | None	Integer indices (alternative to labels).	None
piecewise_steps_multiplier	int	Subdivision factor. Defaults to 1.	1
optimization_rate	float	Learning rate. Defaults to 0.01.	0.01
max_optimization_steps	int	Maximum iterations. Defaults to 100.	100
diff_tol	float	Convergence tolerance. Defaults to 0.1.	0.1

Returns:

Type	Description
tuple[bool, int]	A tuple (success, iters).

length(parameter_labels=None, parameter_indices=None, piecewise_steps_multiplier=1, optimization_rate=0.01, max_optimization_steps=100, diff_tol=0.1)

Minimise the total pulse length.

Cost: \(\sum_g\sqrt{\sum_{k\in P}\phi_k(g)^2 + \|d_g\|^2}\) where \(d_g\) is the per-segment drift contribution.

Parameters:

Name	Type	Description	Default
parameter_labels	list[str] | None	Projected-basis labels to minimise. If None, all projected parameters are used.	None
parameter_indices	tuple[int, ...] | None	Integer indices (alternative to labels).	None
piecewise_steps_multiplier	int	Subdivision factor. Defaults to 1.	1
optimization_rate	float	Learning rate. Defaults to 0.01.	0.01
max_optimization_steps	int	Maximum iterations. Defaults to 100.	100
diff_tol	float	Convergence tolerance. Defaults to 0.1.	0.1

Returns:

Type	Description
tuple[bool, int]	A tuple (success, iters).

robust(parameter_labels=None, parameter_indices=None, delta=0.01, num_samples=5, piecewise_steps_multiplier=1, optimization_rate=0.01, max_optimization_steps=100, diff_tol=0.1)

Maximise the worst-case fidelity over \(\delta\) perturbations.

Cost: \(1 - \min_{\boldsymbol\delta} F(U(\phi+\sum_k \delta_k e_k))\) over a Cartesian grid of num_samples evenly-spaced values in \([-\delta, +\delta]\) for each \(k\in P\).

Parameters:

Name	Type	Description	Default
parameter_labels	list[str] | None	Projected-basis labels to make robust.	None
parameter_indices	tuple[int, ...] | None	Integer indices (alternative to labels).	None
delta	float	Half-width of the perturbation box. Defaults to 0.01.	0.01
num_samples	int	Samples per parameter. Defaults to 5.	5
piecewise_steps_multiplier	int	Subdivision factor. Defaults to 1.	1
optimization_rate	float	Learning rate. Defaults to 0.01.	0.01
max_optimization_steps	int	Maximum iterations. Defaults to 100.	100
diff_tol	float	Convergence tolerance. Defaults to 0.1.	0.1

Returns:

Type	Description
tuple[bool, int]	A tuple (success, iters).

bound(parameter_bounds, method='projected_gradient', bounding_rate=0.01, max_bounding_steps=100, diff_tol=0.1)

Enforce parameter bounds via null-space optimisation.

Projects the parameters into the feasible box defined by parameter_bounds while staying in the Jacobian null space.

Parameters:

Name	Type	Description	Default
parameter_bounds	dict[str, tuple[float, float]]	Dictionary mapping interaction labels to (min, max) tuples.	required
method	str	Bounding strategy — 'projected_gradient' / 'pg' or 'mid_point' / 'mp'. Defaults to 'projected_gradient'.	'projected_gradient'
bounding_rate	float	Learning rate. Defaults to 0.01.	0.01
max_bounding_steps	int	Maximum iterations. Defaults to 100.	100
diff_tol	float	Convergence tolerance. Defaults to 0.1.	0.1

Returns:

Type	Description
bool	A tuple (success, iters) where success is True if
int	diff_tol was reached.

Raises:

Type	Description
ValueError	If an unsupported method is provided.

get_free_params_update_smoothing()

Build a JIT-compiled function to reconstruct free parameters.

Combines projected and drift parameters into the full free-parameter array during smoothing.

Returns:

Type	Description
Callable[[Array, ndarray], Array]	A JIT-compiled callable
Callable[[Array, ndarray], Array]	update_free_params_smoothing(proj_params, params).