Package: ablkit
📘Documentation|📚Examples|💬Reporting IssuesABLkit: A Toolkit for Abductive LearningABLkitis an efficient Python toolkit forAbductive Learning (ABL). ABL is a novel paradigm that integrates machine learning and logical reasoning in a unified framework. It is suitable for tasks where both data and (logical) domain knowledge are available.Key Features of ABLkit:High Flexibility: Compatible with various machine learning modules and logical reasoning components.User-Friendly Interface: Provide data, model, and knowledge, and get started with just a few lines of code.Optimized Performance: Optimization for high performance and accelerated training speed.ABLkit encapsulates advanced ABL techniques, providing users with an efficient and convenient toolkit to develop dual-driven ABL systems, which leverage the power of both data and knowledge.InstallationInstall from PyPIThe easiest way to install ABLkit is usingpip:pipinstallablkitInstall from SourceAlternatively, to install from source code, sequentially run following commands in your terminal/command line.gitclonehttps://github.com/AbductiveLearning/ABLkit.gitcdABLkit
pipinstall-v-e.(Optional) Install SWI-PrologIf the use of aProlog-based knowledge baseis necessary, please also installSWI-Prolog:For Linux users:sudoapt-getinstallswi-prologFor Windows and Mac users, please refer to theSWI-Prolog Install Guide.Quick StartWe use the MNIST Addition task as a quick start example. In this task, pairs of MNIST handwritten images and their sums are given, alongwith a domain knowledge base which contains information on how to perform addition operations. Our objective is to input a pair of handwritten images and accurately determine their sum.Working with DataABLkit requires data in the format of(X, gt_pseudo_label, Y)whereXis a list of input examples containing instances,gt_pseudo_labelis the ground-truth label of each example inXandYis the ground-truth reasoning result of each example inX. Note thatgt_pseudo_labelis only used to evaluate the machine learning model's performance but not to train it.In the MNIST Addition task, the data loading looks like:# The 'datasets' module below is located in 'examples/mnist_add/'fromdatasetsimportget_dataset# train_data and test_data are tuples in the format of (X, gt_pseudo_label, Y)train_data=get_dataset(train=True)test_data=get_dataset(train=False)Building the Learning PartLearning part is constructed by first defining a base model for machine learning. ABLkit offers considerable flexibility, supporting any base model that conforms to the scikit-learn style (which requires the implementation offitandpredictmethods), or a PyTorch-based neural network (which has defined the architecture and implementedforwardmethod). In this example, we build a simple LeNet5 network as the base model.# The 'models' module below is located in 'examples/mnist_add/'frommodels.nnimportLeNet5cls=LeNet5(num_classes=10)To facilitate uniform processing, ABLkit provides theBasicNNclass to convert a PyTorch-based neural network into a format compatible with scikit-learn models. To construct aBasicNNinstance, aside from the network itself, we also need to define a loss function, an optimizer, and the computing device.​importtorch​fromablkit.learningimportBasicNN​​loss_fn=torch.nn.CrossEntropyLoss()​optimizer=torch.optim.RMSprop(cls.parameters(),lr=0.001,alpha=0.9)​device=torch.device("cuda"iftorch.cuda.is_available()else"cpu")​base_model=BasicNN(model=cls,loss_fn=loss_fn,optimizer=optimizer,device=device)The base model built above is trained to make predictions on instance-level data (e.g., a single image), while ABL deals with example-level data. To bridge this gap, we wrap thebase_modelinto an instance ofABLModel. This class serves as a unified wrapper for base models, facilitating the learning part to train, test, and predict on example-level data, (e.g., images that comprise an equation).fromablkit.learningimportABLModel​​model=ABLModel(base_model)Building the Reasoning PartTo build the reasoning part, we first define a knowledge base by creating a subclass ofKBBase. In the subclass, we initialize thepseudo_label_listparameter and override thelogic_forwardmethod, which specifies how to perform (deductive) reasoning that processes pseudo-labels of an example to the corresponding reasoning result. Specifically, for the MNIST Addition task, thislogic_forwardmethod is tailored to execute the sum operation.fromablkit.reasoningimportKBBase​classAddKB(KBBase):def__init__(self,pseudo_label_list=list(range(10))):super().__init__(pseudo_label_list)​deflogic_forward(self,nums):returnsum(nums)​kb=AddKB()Next, we create a reasoner by instantiating the classReasoner, passing the knowledge base as a parameter. Due to the indeterminism of abductive reasoning, there could be multiple candidate pseudo-labels compatible to the knowledge base. In such scenarios, the reasoner can minimize inconsistency and return the pseudo-label with the highest consistency.fromablkit.reasoningimportReasoner​reasoner=Reasoner(kb)Building Evaluation MetricsABLkit provides two basic metrics, namelySymbolAccuracyandReasoningMetric, which are used to evaluate the accuracy of the machine learning model's predictions and the accuracy of thelogic_forwardresults, respectively.fromablkit.data.evaluationimportReasoningMetric,SymbolAccuracy​metric_list=[SymbolAccuracy(),ReasoningMetric(kb=kb)]Bridging Learning and ReasoningNow, we useSimpleBridgeto combine learning and reasoning in a unified ABL framework.fromablkit.bridgeimportSimpleBridge​bridge=SimpleBridge(model,reasoner,metric_list)Finally, we proceed with training and testing.​bridge.train(train_data,loops=1,segment_size=0.01)bridge.test(test_data)To explore detailed tutorials and information, please refer to -document.ExamplesWe provide several examples inexamples/. Each example is stored in a separate folder containing a README file.MNIST AdditionHandwritten Formula (HWF)Handwritten Equation DeciphermentZooReferencesFor more information about ABL, please refer to:Zhou, 2019andZhou and Huang, 2022.@article{zhou2019abductive,
  title     = {Abductive learning: towards bridging machine learning and logical reasoning},
  author    = {Zhou, Zhi-Hua},
  journal   = {Science China Information Sciences},
  volume    = {62},
  number    = {7},
  pages     = {76101},
  year      = {2019}
}

@incollection{zhou2022abductive,
  title     = {Abductive Learning},
  author    = {Zhou, Zhi-Hua and Huang, Yu-Xuan},
  booktitle = {Neuro-Symbolic Artificial Intelligence: The State of the Art},
  editor    = {Pascal Hitzler and Md. Kamruzzaman Sarker},
  publisher = {{IOS} Press},
  pages     = {353--369},
  address   = {Amsterdam},
  year      = {2022}
}