How to Register Your Algorithm with OptunaHub

After implementing your own algorithm, you can register the algorithm as a package with OptunaHub. To add your package to the optunahub-registry repository, you need to create a pull request from your fork. Your pull request must be aligned with the contribution guidelines.

The following is an example of the directory structure of a package. See the template directory for an example of the directory structure.

package

└── category (e.g. samplers, pruners, and visualization)

└── YOUR_PACKAGE_NAME (you need to create this directory and its contents)

├── YOUR_ALGORITHM_NAME.py

├── __init__.py

├── README.md

├── LICENSE

├── (example.py, example.ipynb)

├── (requirements.txt)

└── (images)

├── (figure1.png)

└── (numerical_results.png)

An implemented algorithm should be put in the corresponding directory, e.g., a sampler should be put in the samplers directory. In the samplers directory, you should create a directory with a unique identifier. This unique identifier is the name of your algorithm package, is used to load the package, and is unable to change once it is registered. The package name must be a valid Python module name, preferably one that is easily searchable. Abbreviations are not prohibited in package names, but their abuse should be avoided.

The created directory should include the following files:

• YOUR_ALGORITHM_NAME.py: The implementation of your algorithm.

• __init__.py: An initialization file. This file must implement your algorithm or import its implementation from another file, e.g., YOUR_ALGORITHM_NAME.py.

• README.md: A description of your algorithm. This file is used to create an web page of OptunaHub. Let me explain the format of the README.md file later.

• LICENSE: A license file. This file must contain the license of your algorithm. It should be the MIT license in the alpha version of OptunaHub.

• example.py, example.ipynb: This is optional. This file should contain a simple example of how to use your algorithm (Example: example.py for Simulated Annealing Sampler). You can provide examples in both formats.

• requirements.txt: This is optional. A file that contains the additional dependencies of your algorithm. If there are no additional dependencies other than Optuna and OptunaHub, you do not need to create this file.

• images: This is optional. A directory that contains images. Only relative references to images in this directory are allowed in README.md, e.g., ![Numrical Results](images/numerical_results.png), and absolute paths to images are not allowed. The first image that appears in README.md will be used as the thumbnail.

All files must pass linter and formetter checks to be merged to the optunahub-registry repository. You can check them by running the pre-commit tool as follows.

pip install pre-commit
pre-commit install
pre-commit run  # This will run all checks against currently staged files.

Although we recommend you write proper type hints, if you find it difficult to comply with mypy, you can omit the check by writing the following directive as the first line of your code.

# mypy: ignore-errors

README.md must contain the following sections:

• A header section written in the following format:

  ---
  author: Optuna team
  title: Demo Sampler
  description: Demo Sampler of OptunaHub
  tags: [sampler]
  optuna_versions: [4.0.0]
  license: MIT License
  ---
  

  • author (string): The author of the package. It can be your name or your organization name.

  • title (string): The package title. It should not be a class/function name but a human-readable name. For example, Demo Sampler is a good title, but DemoSampler is not.

  • description (string): A brief description of the package. It should be a one-sentence summary of the package.

  • tags (list[string]): The package tags. It should be a list of strings. The tags must include sampler, visualization, or pruner depending on the type of the package. You can add other tags as needed. For example, “[‘sampler’, ‘LLM’]”.

  • optuna_versions (list[string]): A list of Optuna versions that the package supports. It should be a list of strings. You can find your Optuna version with python -c 'import optuna; print(optuna.__version__)'.

  • license (string): The license of the package. It should be a string. For example, MIT License. The license must be MIT License in the current version of OptunaHub.

• Abstract section that describes the summary of your package. It should be a markdown paragraph. This section will help attract potential users to your package.

• Class or Function Names section that describes the classes or functions provided by the package. If you provide multiple classes or functions, you should list them in this section. Note that the section must be a markdown list. If you provide only one class or function, you can simply write the class or function name. Note that the documentation of the classes or functions must be written in their docstrings. If you want to refer to the documentation, please leave the source code link, or write them in the following Others section. For example:

  - `DemoSampler1`
  - `DemoSampler2`
  - `demo_function1`
  

• An Installation section that describes how to install the additional dependencies if required. If your package contains requirements.txt, it will be available at https://hub.optuna.org/{category}/{your_package_name}/requirements.txt. Then, the package dependencies can be installed as follows.

  $ pip install -r https://hub.optuna.org/{category}/{your_package_name}/requirements.txt
  

• An Example section that describes how to use the package. It should be a python code block. It should be a few lines of code snippets that show how to use the package. If you want to provide a full example, please create a separete file like example.py and refer to it. For example:

  ```python
  sampler = DemoSampler()
  study = optuna.create_study(sampler=sampler)
  ```
  See `example.py <path/to/example.py>` for more details.
  

• An Others section that describes supplementary information about the package such as the paper reference or the original source code link. For example:

  - [Original Paper](Link/to/the/original/paper)
  - [Source Code](Link/to/the/source/code)
  

It is highly recommended that you confirm your package works properly (cf. How to Debug Your Algorithm Before Registering in OptunaHub) before making a pull request.

Before making a pull request, please ensure the code examples in README.md and example.py do not contain your local directory and/or your fork of the registry. Code such as load_local_module("your_package", registry_root=”your_local_directory”) or load_module("your_package_name", repo_owner=”your_github_id”, ref=”your_working_branch”) should be load_module("your_package_name").

After merging your pull request, your package will be available on the OptunaHub in about 1 hour.