xadap

Python implementation of Learning-based Controller for Extreme Adaptation.

Based on: Dingqi Zhang, Antonio Loquercio, Jerry Tang, Ting-Hao Wang, Jitendra Malik, Mark W. Mueller. "A Learning-based Quadcopter Controller with Extreme Adaptation" IEEE Transactions on Robotics, 41(2):3948-3964, 2025. https://doi.org/10.1109/TRO.2025.3577037

Classes:

Name	Description
ModelType	Enumeration for model normalization variants.
ButterworthFilter	Low-pass filter for smoothing sensor measurements.
NeuralNetworkModel	Neural network model for adaptation.
Xadap_NN_control	Controller combining high-level controller with neural adaptation.

ModelType

Bases: Enum

Enumeration for model normalization variants.

ButterworthFilter

ButterworthFilter(cutoff_freq=30, sample_rate=100)

Low-pass filter for smoothing sensor measurements.

Initialize filter coefficients and buffers.

Parameters:

Name	Type	Description	Default
cutoff_freq	float	Cutoff frequency in Hz.	30
sample_rate	float	Sampling rate in Hz.	100

Methods:

Name	Description
run	Filter a new sample and return the smoothed value.

run

run(x_new: ndarray) -> np.ndarray

Filter a new sample and return the smoothed value.

Parameters:

Name	Type	Description	Default
x_new	ndarray	New sample vector.	required

Returns:

Type	Description
ndarray	np.ndarray: Filtered sample.

NeuralNetworkModel

NeuralNetworkModel()

Neural network model for adaptation.

Initialize ONNX model paths, load normalization parameters, and activate sessions.

Methods:

Name	Description
activate	Initialize ONNX runtime sessions.
normalize_obs	Normalize observations based on model type.
predict	Run inference through both networks.

activate

activate()

Initialize ONNX runtime sessions.

normalize_obs

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

Normalize observations based on model type.

Parameters:

Name	Type	Description	Default
obs	ndarray	Raw observation array.	required
model_type	ModelType	Which normalization scheme to apply.	required

Returns:

Type	Description
ndarray	np.ndarray: Normalized observations.

predict

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

Run inference through both networks.

Parameters:

Name	Type	Description	Default
cur_obs	ndarray	Current observation vector.	required
last_act	ndarray	Previous action vector.	required
obs_history	ndarray	Flattened observation history.	required
act_history	ndarray	Flattened action history.	required

Returns:

Type	Description
tuple[ndarray, ndarray]	tuple[np.ndarray, np.ndarray]: Normalized and raw actions.

Xadap_NN_control

Xadap_NN_control(params: VehicleParams = VehicleParams(), control_mask: list[int] = [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1], gains: dict | None = None)

Bases: FlightController

Controller combining high-level controller with neural adaptation.

Initialize the hybrid controller and buffers.

Parameters:

Name	Type	Description	Default
params	VehicleParams	Vehicle parameters.	VehicleParams()
control_mask	list[int]	Control mask for target/state channels.	[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
gains	dict | None	Optional PID gains passed to FlightController.	None

Methods:

Name	Description
update	Compute thrust and moments from target and state.
reset	Reset controller state and buffers.

Attributes:

Name	Type	Description
params	VehicleParams	Vehicle parameters for the controller.
control_mask	ndarray | Tensor	unified control mask for target/state channels, used in update(). e.g. using 9~11 for attitude yaw control.

params instance-attribute

params: VehicleParams = params

Vehicle parameters for the controller.

control_mask instance-attribute

control_mask: ndarray | Tensor = control_mask

unified control mask for target/state channels, used in update(). e.g. using 9~11 for attitude yaw control.

update

update(target: ndarray, state: ndarray) -> np.ndarray

Compute thrust and moments from target and state.

Parameters:

Name	Type	Description	Default
target	ndarray	Desired state vector.	required
state	ndarray	Current state vector.	required

Returns:

Type	Description
ndarray	np.ndarray: Control output ordered as [thrust, Mx, My, Mz].

reset

reset(*args, **kwargs)

Reset controller state and buffers.