[DOC] learnware doc(Feature Align + Hetero Map Learnware)

docs/components/learnware.rst

@@ -3,56 +3,52 @@
 Learnware & Reuser
 ==========================================
 
-Learnware and Reuser are related...
+``Learnware`` is the most basic concept in the ``learnware paradigm``. In this section, we will introduce the concept and design of ``learnware`` and its extension for ``Hetero Reuse``. Then we will introduce the ``Reuse Methods``, which applies one or several ``learnware``s to solve the user's task.
 
 Concepts
 ===================
-The learnware paradiam, first introduced by Zhi-Hua Zhou, is defined as a proficiently trained machine learning model accompanied by a specification that allows future users with no prior knowledge of the learnware to identify and reuse it according to their needs.
+In the learnware paradigm, a learnware is a well-performed trained machine learning model with a specification which enables it to be adequately identified to reuse according to the requirement of future users who know nothing about the learnware in advance. The introduction of specifications are shown in `COMPONENTS: Specification <./spec.html>`_.
 
-Developers or owners of trained machine learning models can voluntarily submit their models to a learnware marketplace. If the marketplace accepts the model, it assigns a specification to the model and makes it available in the marketplace.
+In our implementation, the class ``Learnware`` has 3 important member variables:
 
-Utilizing Learnware in Practice
--------------------------------
+- ``id``: The learnware id is generated by ``market``.
+- ``model``: The model in the learnware, can be a ``BaseModel`` or a dict including model name and path. When it is a dict, the function ``Learnware.instantiate_model`` is used to transform it to a ``BaseModel``. The function ``Learnware.predict`` use the model to predict for an input ``X``. See more in `COMPONENTS: Model <./model.html>`_.
+- ``specification``: The specification including the semantic specification and the statistic specification.
 
-With a learnware marketplace in place, users can tackle machine learning tasks without having to create models from scratch. 
 
-Addressing Concerns with Learnware
-----------------------------------
+Learnware for Hetero Reuse (Feature Align + Hetero Map Learnware)
+=======================================================================
 
-The learnware approach aims to address several challenges:
+In the Hetero Market(see `COMPONENTS:Market  <./market>`_ for details), ``HeteroSearcher`` identifies and recommends helpful learnwares among all learnwares in the market, 
+including learnwares with feature/label space different from the user's task requirements(heterogeneous learnwares). ``FeatureAlignLearnware`` and ``HeteroMapLearnware``
+extends ``Learnware`` with the ability to align the feature space and label space of the learnware to the user's task requirements, providing methods for heterogeneous learnwares to be reused in tasks beyond their original purposes.
 
+``FeatureAlignLearnware``
+_________________________
 
-+------------------------+----------------------------------------------------------------------------------------+
-| Concern                | Solution                                                                               |
-+========================+========================================================================================+
-| Limited training data  | Use existing high-quality learnware and require only a small amount of data for        |
-|                        | adaptation or refinement.                                                              |
-+------------------------+----------------------------------------------------------------------------------------+
-| Lack of training skills| Leverage existing learnware instead of building a model from scratch.                  |
-+------------------------+----------------------------------------------------------------------------------------+
-| Catastrophic forgetting| Retain old knowledge in the marketplace as accepted learnware remain available.        |
-+------------------------+----------------------------------------------------------------------------------------+
-| Continual learning     | Facilitate continuous and lifelong learning with the constant influx of high-quality   |
-|                        | learnware, enriching the knowledge base.                                               |
-+------------------------+----------------------------------------------------------------------------------------+
-| Data privacy and       | Ensure data privacy and proprietary protection by having developers only submit        |
-| proprietary concerns   | models, not their data.                                                                |
-+------------------------+----------------------------------------------------------------------------------------+
-| Unplanned tasks        | Ensure the availability of helpful learnware for various tasks, unless entirely new    |
-|                        | to all legal developers.                                                               |
-+------------------------+----------------------------------------------------------------------------------------+
-| Carbon emissions       | Reduce the need to train numerous large models by assembling smaller models that       |
-|                        | provide satisfactory performance.                                                      |
-+------------------------+----------------------------------------------------------------------------------------+
+``FeatureAlignLearnware`` employs a neural network to align the feature space of the learnware to the user's task. 
+It is initialized with a ``Learnware``, and has the following methods to expand the applicable scope of this ``Learnware``:
 
-Future Work and Progress
-------------------------
+- **align**: Key interface that trains a neural network to align ``user_rkme``, which is the ``RKMETableSpecification`` of the user's data, with the learnware's statistical specification.
+- **predict**: Predict the output for user data using the trained neural network and the original learnware's model.
 
-Despite the promising potential of the learnware proposal, much work remains to bring it to fruition. The following sections will discuss some of the progress made thus far.
+
+``HeteroMapAlignLearnware``
+____________________________
+
+If user data is not only heterogeneous in feature space but also in label space, ``HeteroMapAlignLearnware`` uses the help of 
+a small amount of labeled data ``(x_train, y_train)`` required from the user task to align heterogeneous learnwares with the user task.
+
+- ``HeteroMapAlignLearnware.align(self, user_rkme: RKMETableSpecification, x_train: np.ndarray, y_train: np.ndarray)``
+
+  - **input space alignment**: Align the feature space of the learnware to the user task's statistical specification ``user_rkme`` using ``FeatureAlignLearnware``.
+  - **output space alignment**: Further align the label space of the aligned learnware to the user task through supervised learning of ``FeatureAugmentReuser`` using ``(x_train, y_train)``.
+
+- ``HeteroMapAlignLearnware.predict(self, user_data)``
+
+  - If input space and output space alignment are both performed, use the ``FeatureAugmentReuser`` to predict the output for user data.
 
 
-Learnware for Hetero Reuse (Feature Aligh + Hetero Map Learnware)
-=======================================================================
 
 All Reuse Methods
 ===========================
@@ -74,6 +70,7 @@ If ``use_herding`` is set to false, the ``JobSelectorReuser`` uses data points i
 If ``use_herding`` is true, the algorithm estimates the mixture weight based on RKME specifications and raw user data, uses the weight to generate ``herding_num`` auxiliary data points mimicking the user distribution through the kernel herding method, and learns a job selector on these data.
 
 
+
 AveragingReuser
 ------------------