[MetaSchedule] Introduce Union and OrderedUnion in Database (#12628)

Following up #12520 and #12626, this PR introduces two database classes:
`UnionDatabase` and `OrderedUnionDatabase`, both of which allow users to
organically compose multiple databases together, so that the high-level
IR (Relay, Relax) could select the best tuning records according to
running time or a preferred order given by users.

To each query, `UnionDatabase` returns the best record among all the
databases given; Instead, `OrderedUnionDatabase` returns he record from
the first database that responds to the query.

Used together, users may specify complicated dispatching patterns like
below:

Examples below demonstrate the usecases of and difference between
UnionDatabase and OrderDatabase.

Assumption:
* db1, db2 do not have tuning records for the target workload.
* Each of db3, db4, db5 has tuning records r3, r4, r5 for target
workload respectively.

```python
#### Case 1. `UnionDatabase`:
merged_db = ms.database.UnionDatabase(
    db1, # no record
    db2, # no record
    db3, # has r3
    db4  # has r4
)
# returns the better one between r3 and r4
merged_db.query_tuning_record(..., target_workload)

### Case 2. `OrderedUnionDatabase`
merged_db = ms.database.OrderedUnionDatabase(
    db1, # no record
    db2, # no record
    db3, # has r3
    db4  # has r4
)
# returns r3
merged_db.query_tuning_record(..., target_workload)

### Case 3. Mix-use scenario
merged_db = ms.database.UnionDatabase(
    db1, # no record
    db2, # no record
    db3, # has r3
    ms.database.OrderedUnionDatabase( # returns r4
        db4,  # has r4
        db5,  # has r5
    )
)
# returns the better one between r3 and r4
merged_db.query_tuning_record(..., target_workload)

### Case 4. Another mix-use scenario
merged_db = ms.database.UnionDatabase(
    db1, # no record
    db2, # no record
    db3, # has r3
    ms.database.UnionDatabase( # returns the better one between r4 and r5
        db4,  # has r4
        db5,  # has r5
    )
)
# returns the best one among r3, r4 and r5
merged_db.query_tuning_record(..., target_workload)

### Case 5. Yet another mix-use scenario
merged_db = ms.database.OrderedUnionDatabase(
    db1, # no record
    db2, # no record
    ms.database.UnionDatabase( # returns the better one between r3 and r4
        db3, # has r3
        db4, # has r4
    )
    db5,  # has r5
)
# returns the better one between r3 and r4
merged_db.query_tuning_record(..., target_workload)
```

Co-authored-by: sunggg <49998730+sunggg@users.noreply.github.com>

include/tvm/meta_schedule/database.h

@@ -357,6 +357,22 @@ class Database : public runtime::ObjectRef {
    */
   TVM_DLL static Database JSONDatabase(String path_workload, String path_tuning_record,
                                        bool allow_missing);
+  /*!
+   * \brief A database composed of multiple databases, allowing users to guide IR rewriting using
+   * combined knowledge of those databases. To each query, it returns the best record among all the
+   * databases given.
+   * \param databases The list of databases to be combined.
+   * \return The combined database.
+   */
+  TVM_DLL static Database UnionDatabase(Array<Database, void> databases);
+  /*!
+   * \brief A database composed of multiple databases, allowing users to guide IR rewriting using
+   * combined knowledge of those databases. To each query, it returns the record from the first
+   * database that responds to the query.
+   * \param databases The database to be subsetted.
+   * \return The subsetted database.
+   */
+  TVM_DLL static Database OrderedUnionDatabase(Array<Database, void> databases);
   /*!
    * \brief Create a database with customized methods on the python-side.
    * \param f_has_workload The packed function of `HasWorkload`.

python/tvm/meta_schedule/database/__init__.py

@@ -21,4 +21,6 @@
 from .database import Database, PyDatabase, TuningRecord, Workload
 from .json_database import JSONDatabase
 from .memory_database import MemoryDatabase
+from .ordered_union_database import OrderedUnionDatabase
 from .schedule_fn_database import ScheduleFnDatabase
+from .union_database import UnionDatabase

python/tvm/meta_schedule/database/ordered_union_database.py

@@ -0,0 +1,112 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""A database consists of multiple databases."""
+from tvm._ffi import register_object
+
+from .. import _ffi_api
+from .database import Database
+
+
+@register_object("meta_schedule.OrderedUnionDatabase")
+class OrderedUnionDatabase(Database):
+    """A database composed of multiple databases, allowing users to guide IR rewriting using
+    combined knowledge of those databases. To each query, it returns the record from the first
+    database that responds to the query.
+
+    Examples
+    --------
+    Examples below demonstrate the usecases of and difference between UnionDatabase and
+    OrderDatabase.
+
+    Assumption:
+    * db1, db2 do not have tuning records for the target workload.
+    * Each of db3, db4, db5 has tuning records r3, r4, r5 for target workload respectively.
+
+    .. code-block:: python
+
+    #### Case 1. `UnionDatabase`:
+    merged_db = ms.database.UnionDatabase(
+        db1, # no record
+        db2, # no record
+        db3, # has r3
+        db4  # has r4
+    )
+    # returns the better one between r3 and r4
+    merged_db.query_tuning_record(..., target_workload)
+
+    ### Case 2. `OrderedUnionDatabase`
+    merged_db = ms.database.OrderedUnionDatabase(
+        db1, # no record
+        db2, # no record
+        db3, # has r3
+        db4  # has r4
+    )
+    # returns r3
+    merged_db.query_tuning_record(..., target_workload)
+
+    ### Case 3. Mix-use scenario
+    merged_db = ms.database.UnionDatabase(
+        db1, # no record
+        db2, # no record
+        db3, # has r3
+        ms.database.OrderedUnionDatabase( # returns r4
+            db4,  # has r4
+            db5,  # has r5
+        )
+    )
+    # returns the better one between r3 and r4
+    merged_db.query_tuning_record(..., target_workload)
+
+    ### Case 4. Another mix-use scenario
+    merged_db = ms.database.UnionDatabase(
+        db1, # no record
+        db2, # no record
+        db3, # has r3
+        ms.database.UnionDatabase( # returns best one between r4 and r5
+            db4,  # has r4
+            db5,  # has r5
+        )
+    )
+    # returns the best one among r3, r4 and r5
+    merged_db.query_tuning_record(..., target_workload)
+
+    ### Case 5. Yet another mix-use scenario
+    merged_db = ms.database.OrderedUnionDatabase(
+        db1, # no record
+        db2, # no record
+        ms.database.UnionDatabase( # returns best one between r3 and r4
+            db3, # has r3
+            db4,  # has r4
+        )
+        db5,  # has r5
+    )
+    # returns the better one between r3 and r4
+    merged_db.query_tuning_record(..., target_workload)
+    """
+
+    def __init__(self, *databases: Database) -> None:
+        """Construct a merged database from multiple databases.
+
+        Parameters
+        ----------
+        *databases : Database
+            The list of databases to combine.
+        """
+        self.__init_handle_by_constructor__(
+            _ffi_api.DatabaseOrderedUnionDatabase,  # type: ignore # pylint: disable=no-member
+            databases,
+        )

python/tvm/meta_schedule/database/union_database.py

@@ -0,0 +1,112 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""A database consists of multiple databases."""
+from tvm._ffi import register_object
+
+from .. import _ffi_api
+from .database import Database
+
+
+@register_object("meta_schedule.UnionDatabase")
+class UnionDatabase(Database):
+    """A database composed of multiple databases, allowing users to guide IR rewriting using
+    combined knowledge of those databases. To each query, it returns the best record among all the
+    databases given.
+
+    Examples
+    --------
+    Examples below demonstrate the usecases of and difference between UnionDatabase and
+    OrderDatabase.
+
+    Assumption:
+    * db1, db2 do not have tuning records for the target workload.
+    * Each of db3, db4, db5 has tuning records r3, r4, r5 for target workload respectively.
+
+    .. code-block:: python
+
+    #### Case 1. `UnionDatabase`:
+    merged_db = ms.database.UnionDatabase(
+        db1, # no record
+        db2, # no record
+        db3, # has r3
+        db4  # has r4
+    )
+    # returns the better one between r3 and r4
+    merged_db.query_tuning_record(..., target_workload)
+
+    ### Case 2. `OrderedUnionDatabase`
+    merged_db = ms.database.OrderedUnionDatabase(
+        db1, # no record
+        db2, # no record
+        db3, # has r3
+        db4  # has r4
+    )
+    # returns r3
+    merged_db.query_tuning_record(..., target_workload)
+
+    ### Case 3. Mix-use scenario
+    merged_db = ms.database.UnionDatabase(
+        db1, # no record
+        db2, # no record
+        db3, # has r3
+        ms.database.OrderedUnionDatabase( # returns r4
+            db4,  # has r4
+            db5,  # has r5
+        )
+    )
+    # returns the better one between r3 and r4
+    merged_db.query_tuning_record(..., target_workload)
+
+    ### Case 4. Another mix-use scenario
+    merged_db = ms.database.UnionDatabase(
+        db1, # no record
+        db2, # no record
+        db3, # has r3
+        ms.database.UnionDatabase( # returns best one between r4 and r5
+            db4,  # has r4
+            db5,  # has r5
+        )
+    )
+    # returns the best one among r3, r4 and r5
+    merged_db.query_tuning_record(..., target_workload)
+
+    ### Case 5. Yet another mix-use scenario
+    merged_db = ms.database.OrderedUnionDatabase(
+        db1, # no record
+        db2, # no record
+        ms.database.UnionDatabase( # returns best one between r3 and r4
+            db3, # has r3
+            db4,  # has r4
+        )
+        db5,  # has r5
+    )
+    # returns the better one between r3 and r4
+    merged_db.query_tuning_record(..., target_workload)
+    """
+
+    def __init__(self, *databases: Database) -> None:
+        """Construct a merged database from multiple databases.
+
+        Parameters
+        ----------
+        *databases : Database
+            The list of databases to combine.
+        """
+        self.__init_handle_by_constructor__(
+            _ffi_api.DatabaseUnionDatabase,  # type: ignore # pylint: disable=no-member
+            databases,
+        )

src/meta_schedule/database/json_database.cc

@@ -25,28 +25,6 @@
 namespace tvm {
 namespace meta_schedule {
 
-/*! \brief The struct defining comparison function of sorting by mean run seconds. */
-struct SortTuningRecordByMeanRunSecs {
-  static const constexpr double kMaxMeanTime = 1e10;
-
-  static double Mean(const Array<FloatImm>& a) {
-    if (a.empty()) {
-      return kMaxMeanTime;
-    }
-    double sum = 0.0;
-    for (const FloatImm& i : a) {
-      sum += i->value;
-    }
-    return sum / a.size();
-  }
-
-  bool operator()(const TuningRecord& a, const TuningRecord& b) const {
-    double a_time = Mean(a->run_secs.value_or({}));
-    double b_time = Mean(b->run_secs.value_or({}));
-    return a_time < b_time;
-  }
-};
-
 /*!
  * \brief Read lines from a json file.
  * \param path The path to the json file.

src/meta_schedule/database/ordered_union_database.cc

@@ -0,0 +1,86 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+#include "../utils.h"
+
+namespace tvm {
+namespace meta_schedule {
+
+class OrderedUnionDatabaseNode : public DatabaseNode {
+ public:
+  Array<Database> databases;
+
+  void VisitAttrs(AttrVisitor* v) { v->Visit("databases", &databases); }
+
+  static constexpr const char* _type_key = "meta_schedule.OrderedUnionDatabase";
+  TVM_DECLARE_FINAL_OBJECT_INFO(OrderedUnionDatabaseNode, DatabaseNode);
+
+ public:
+  Optional<TuningRecord> QueryTuningRecord(const IRModule& mod, const Target& target,
+                                           const String& task_name) final {
+    for (const Database& db : databases) {
+      if (Optional<TuningRecord> record = db->QueryTuningRecord(mod, target, task_name)) {
+        return record;
+      }
+    }
+    return NullOpt;
+  }
+
+  bool HasWorkload(const IRModule& mod) final {
+    LOG(FATAL) << "NotImplementedError: OrderedUnionDatabase.HasWorkload";
+    throw;
+  }
+
+  Workload CommitWorkload(const IRModule& mod) final {
+    LOG(FATAL) << "NotImplementedError: OrderedUnionDatabase.CommitWorkload";
+    throw;
+  }
+
+  void CommitTuningRecord(const TuningRecord& record) final {
+    LOG(FATAL) << "NotImplementedError: OrderedUnionDatabase.CommitTuningRecord";
+    throw;
+  }
+
+  Array<TuningRecord> GetTopK(const Workload& workload, int top_k) final {
+    LOG(FATAL) << "NotImplementedError: OrderedUnionDatabase.GetTopK";
+    throw;
+  }
+
+  Array<TuningRecord> GetAllTuningRecords() final {
+    LOG(FATAL) << "NotImplementedError: OrderedUnionDatabase.GetAllTuningRecords";
+    throw;
+  }
+
+  int64_t Size() final {
+    LOG(FATAL) << "NotImplementedError: OrderedUnionDatabase.size";
+    throw;
+  }
+};
+
+Database Database::OrderedUnionDatabase(Array<Database> databases) {
+  ObjectPtr<OrderedUnionDatabaseNode> n = make_object<OrderedUnionDatabaseNode>();
+  n->databases = std::move(databases);
+  return Database(n);
+}
+
+TVM_REGISTER_NODE_TYPE(OrderedUnionDatabaseNode);
+TVM_REGISTER_GLOBAL("meta_schedule.DatabaseOrderedUnionDatabase")
+    .set_body_typed(Database::OrderedUnionDatabase);
+
+}  // namespace meta_schedule
+}  // namespace tvm