xadap

Array API controller for learning-based extreme adaptation.

Based on Dingqi Zhang et al., "A Learning-based Quadcopter Controller with Extreme Adaptation", IEEE Transactions on Robotics, 41(2):3948-3964, 2025.

Classes:

Name	Description
ModelType	Model normalization variants.
ButterworthFilter	Batched low-pass filter matching the original X-adaptation recurrence.
NeuralNetworkModel	ONNX inference wrapper for the base policy and adaptation encoder.
XadapNNControl	PID high-level controller with an ONNX extreme-adaptation inner loop.

ModelType

Bases: Enum

Model normalization variants.

ButterworthFilter

ButterworthFilter(xp: ModuleType, *, num_envs: int = 1, device=None, cutoff_freq: float = 30.0, sample_rate: float = 100.0)

Batched low-pass filter matching the original X-adaptation recurrence.

Initialize filter coefficients and per-environment buffers.

Methods:

Name	Description
run	Filter one batched sample.
reset	Reset filter buffers for selected environments.

run

run(x_new: ArrayLike) -> ArrayLike

Filter one batched sample.

Returns:

Type	Description
ArrayLike	Filtered values with shape (num_envs, 3).

reset

reset(env_ids=None) -> None

Reset filter buffers for selected environments.

NeuralNetworkModel

NeuralNetworkModel(model_dir: str | Path | None = None, *, session_options: Any = None, providers: list[str] | None = None)

ONNX inference wrapper for the base policy and adaptation encoder.

Load normalization data and initialize ONNX Runtime sessions.

Parameters:

Name	Type	Description	Default
model_dir	str | Path | None	Directory containing mlp.onnx, encoder.onnx, mean.csv, and var.csv. Defaults to controllers/models/Xadap.	None
session_options	Any	Optional ONNX Runtime session options.	None
providers	list[str] | None	Optional ONNX Runtime execution-provider list.	None

Raises:

Type	Description
FileNotFoundError	If one or more required model assets are absent.

Methods:

Name	Description
activate	Initialize ONNX Runtime sessions.
normalize_obs	Normalize a batch of observations.
predict	Run batched inference through the adaptation and base networks.

activate

activate(*, session_options: Any = None, providers: list[str] | None = None) -> None

Initialize ONNX Runtime sessions.

Raises:

Type	Description
ImportError	If the optional ONNX Runtime dependency is unavailable.

normalize_obs

normalize_obs(obs: ndarray, model_type: ModelType) -> np.ndarray

Normalize a batch of observations.

Returns:

Type	Description
ndarray	Normalized observations with the same batch dimension.

predict

predict(cur_obs: ndarray, last_act: ndarray, obs_history: ndarray, act_history: ndarray) -> tuple[np.ndarray, np.ndarray]

Run batched inference through the adaptation and base networks.

Returns:

Type	Description
ndarray	Denormalized motor actions and raw normalized actions, both shaped
ndarray	(num_envs, 4).

XadapNNControl

XadapNNControl(params: VehicleParams = VehicleParams(), control_mask: dict | None = None, gains: dict | None = None, limits: dict | None = None, num_envs: int = 1, device=None, *, backend: BackendName | None = None, xp: ModuleType | None = None, model_dir: str | Path | None = None, neural_network: NeuralNetworkModel | None = None)

Bases: FlightController

PID high-level controller with an ONNX extreme-adaptation inner loop.

Initialize the controller, inference model, and batched histories.

Methods:

Name	Description
update	Compute batched thrust and moments from target and state.
reset	Reset controller, filter, and adaptation state.
randomize	Randomize gains, limits, and selected physical parameters.
gains_to_randomization_ranges	Gains to randomization ranges.

Attributes:

Name	Type	Description
params	VehicleParams	Vehicle parameters for the controller.

params instance-attribute

params: VehicleParams = params

Vehicle parameters for the controller.

update

update(target: ControllerTarget, state: ControllerState) -> ArrayLike

Compute batched thrust and moments from target and state.

Returns:

Type	Description
ArrayLike	Control output ordered as [thrust, Mx, My, Mz] with shape
ArrayLike	(num_envs, 4).

reset

reset(env_ids=None) -> None

Reset controller, filter, and adaptation state.

randomize

randomize(env_ids=None, gains: dict[str, Any] | None = None, limits: dict[str, Any] | None = None, params: dict[str, Any] | None = None)

Randomize gains, limits, and selected physical parameters.

gains_to_randomization_ranges classmethod

gains_to_randomization_ranges(gains: dict | None = None, scale: float = 0.2) -> dict

Gains to randomization ranges.

Returns:

Type	Description
dict	Dictionary mapping gain keys to min/max range tuples.