Package: torchcross
TorchCrossEasy-to-use PyTorch library for cross-domain learning, few-shot learning and
meta-learning.What is TorchCross?TorchCross is a PyTorch library for cross-domain learning, few-shot learning and
meta-learning. It provides convenient utilities for creating cross-domain learning
or few-shot learning experiments.Package Overviewtorchcross: The main package, containing the library.torchcross.cd: Contains functions to create network heads, losses and metrics
for cross-domain learning experiments.torchcross.data: Contains classes to load data as for cross-domain learning
or few-shot learning experiments.torchcross.data.task: Contains theTaskandTaskDescriptionclasses, which
represent a task in a few-shot learning scenario and a task's metadata,
respectively.torchcross.data.task_source: Contains theTaskSourceclass, which extends thetorch.utils.data.Datasetclass and represents a data source for sampling tasks
in a few-shot learning scenario. Additionally, it contains the utility classes
which facilitate working withTaskSourceobjects.torchcross.data.metadataset: Contains theMetaDatasetclass, which
represents a collection of tasks in a few-shot learning scenario. TheFewShotMetaDatasetandSubTaskRandomFewShotMetaDatasetclasses extend theMetaDatasetclass and provide a convenient interface for sampling few-shot
instances from aTaskSource.torchcross.models: Containstorch.nn.Moduleclasses for cross-domain
and few-shot scenarios.torchcross.models.lightning: Containspytorch_lightning.LightningModuleclasses
which wrap thetorch.nn.Moduleclasses intorchcross.modelsand provide
convenient training and evaluation routines.torchcross.utils: Contains various utility functions.This library is still in alpha. The API is potentially subject to change. Any feedback
is welcome.InstallationThe library can be installed via pip:pipinstalltorchcrossBasic Usage ExamplesWrapping a PyTorch Dataset as a TaskSourceTheWrapTaskSourceclass can be used to wrap a PyTorch dataset as aTaskSource.importtorch.utils.datafromtorchcross.dataimportTaskTarget,WrapTaskSource# Create a PyTorch datasetdataset:torch.utils.data.Dataset=...# Define the appropriate TaskTarget. Let's assume that the task is a multi-class# classification task.task_target=TaskTarget.MULTICLASS_CLASSIFICATION# Classes can be provided as a dictionary. Let's assume that the dataset contains# four classes with names "Class A", "Class B", "Class C" and "Class D".classes={0:"Class A",1:"Class B",2:"Class C",3:"Class D"}# Wrap the dataset as a TaskSourcetask_source=WrapTaskSource(dataset,task_target,classes)Creating a Few-Shot Meta-DatasetTheFewShotMetaDatasetclass can be used to create a few-shot meta-dataset from aTaskSource.fromtorchcross.data.metadatasetimportFewShotMetaDatasetimporttorchcrossastx# Create a TaskSource.task_source=...# Create a few-shot meta-dataset from the task source. Let's assume that we want to# sample 100 tasks, each containing 5 support samples and 10 query samples.# Let's use the stack function from the tx.utils module to stack the support and query# samples into a single tensor.meta_dataset=FewShotMetaDataset(task_source,collate_fn=tx.utils.collate_fn.stack,n_support_samples_per_class=5,n_query_samples_per_class=10,filter_classes_min_samples=30,length=100,)Creating a Few-Shot Meta-Dataset with Random Sub-TasksTheSubTaskRandomFewShotMetaDatasetclass can be used to create a few-shot
meta-dataset from aTaskSourcewhere each task is a random sub-task of the original
task, meaning that each few-shot task contains a random subset of the original task's
classes.fromtorchcross.data.metadatasetimportSubTaskRandomFewShotMetaDatasetimporttorchcrossastx# Create a TaskSource.task_source=...# Create a few-shot meta-dataset from the task source. Let's assume that we want to# sample 100 tasks, each containing a random subset of the original task's classes and# 1 to 10 support samples per class and 10 query samples per class.# Let's use the stack function from the tx.utils module to stack the support and query# samples into a single tensor.few_shot=SubTaskRandomFewShotMetaDataset(task_source,collate_fn=tx.utils.collate_fn.stack,n_support_samples_per_class_min=1,n_support_samples_per_class_max=10,n_query_samples_per_class=10,filter_classes_min_samples=30,length=100,)Use the MAML Algorithm to Train a Model on a Few-Shot Meta-DatasetThelightning.LightningModulesubclasses intorchcross.models.lightningcan be used
to train a model on a meta-dataset. Let's assume that we want to train a model on a
few-shot meta-dataset using the MAML algorithm. We can use theMAMLclass from thetorchcross.models.lightningmodule to do so.fromfunctoolsimportpartialimportlightning.pytorchasplimporttorchimporttorchoptfromtorch.utils.dataimportDataLoaderfromtorchcross.dataimportTaskDescription,TaskTargetfromtorchcross.models.lightningimportMAMLfromtorchcross.utils.collate_fnimportidentity# Create few-shot meta-datasets for training and validation.train_meta_dataset=...val_meta_dataset=...# Create dataloaders for training and validation.train_dataloader=DataLoader(train_meta_dataset,batch_size=4,collate_fn=identity)val_dataloader=DataLoader(val_meta_dataset,batch_size=4,collate_fn=identity)# Create a `TaskDescription` object which describes the task type of task that we want# to solve. Let's assume that the task is a multi-class classification task with four# classes.task_description=TaskDescription(TaskTarget.MULTICLASS_CLASSIFICATION,classes={0:"Class A",1:"Class B",2:"Class C",3:"Class D"},)# Create a backbone network. We could for example use a pre-trained resnet18 backbone.backbone=...num_backbone_output_features=512# Create inner and outer optimizers and hyperparameters for MAML.outer_optimizer=partial(torch.optim.Adam,lr=0.001)inner_optimizer=partial(torchopt.MetaSGD,lr=0.1)eval_inner_optimizer=partial(torch.optim.SGD,lr=0.1)num_inner_steps=4eval_num_inner_steps=32# Create the lighting model with pre-trained resnet18 backbonemodel=MAML((backbone,num_backbone_output_features),task_description,outer_optimizer,inner_optimizer,eval_inner_optimizer,num_inner_steps,eval_num_inner_steps,)# Create the lightning trainertrainer=pl.Trainer(inference_mode=False,max_epochs=10,check_val_every_n_epoch=1,val_check_interval=1000,limit_val_batches=100,)# Train the modeltrainer.fit(model,train_dataloader,val_dataloader)Real-World ExampleSee theMIMetalibrary for a
real-world example of how to use TorchCross to perform cross-domain learning, few-shot
learning or meta-learning experiments.