Submission Guidelines

MIREX 2024 Submission Guideline

Since this is the first year we are reviving MIREX, different tasks will have different submission guidelines. However, the general guideline is as follows:

Submission Format

• For tasks to submit code, a docker image is required.
• For tasks to submit results, a zip file is required.

Submission Portal

The submission portal is available at MIREX 2024 Submission Portal.

Docker Image

For people who are not familiar with docker, here is a brief introduction for python and c++ users. For other languages, please refer to the official docker documentation.

First, you need to install Docker on your machine. You can find the installation guide at Docker Installation Guide.

Then you need to create a docker image for your project. A docker image is a lightweight, standalone, executable package that includes everything needed to run a piece of software, including the code, a runtime, libraries, environment variables, and config files.

Python

Assume you have a python project with the following files:

project/
    main.py
    utils.py

The ideal case is that you can use pip to install the dependencies and run the task. To do this, you need to create a `requirements.txt` file in the project directory:

pip freeze > requirements.txt

To create a docker image, you need to create a file named Dockerfile in the project directory:

FROM python:3.8  # Start from an existing image. Change the version to the version you are using

WORKDIR /app  # Set the working directory

COPY requirements.txt ./  # Copy the requirements file to the working directory

RUN pip install --no-cache-dir -r requirements.txt  # Install the dependencies

COPY . .  # Copy the project files to the working directory

ENTRYPOINT [ "python", "main.py" ]  # Set the entry point

Then you can build the docker image:

docker build -t my_project .

C++

Assume you have a c++ project with the following files:

project/
    main.cpp
    utils.cpp
    Makefile

To create a docker image, you need to create a file named Dockerfile in the project directory:

FROM gcc:latest  # Use an official base image that includes a C++ compiler

WORKDIR /usr/src/app  # Set the working directory inside the container

COPY . .  # Copy the project files to the working directory

RUN make  # Compile the project

RUN mkdir -p /app  # Create the target directory for the binary

RUN mv * /app/  # Move the binary to the /app folder

ENTRYPOINT [ "/app/main" ]  # Set the entry point

Then you can build the docker image:

docker build -t my_project .

Upload Docker Image

Different tasks may require different ways to upload the docker image. Most likely, you will be asked to upload the docker image to the following places:

• Docker Hub: You can create a free account at Docker Hub and upload your docker image there.
• Github Container Registry: If you are using Github, you can use the Github Container Registry to upload your docker image.
• Google Drive: You can upload your docker image to Google Drive and share the link with the task captain.

Notice that MIREX server currently does not support docker image upload. This might be supported in future years.

Docker Hub

To upload your docker image to Docker Hub, you need to create a repository on Docker Hub. Then you can push your docker image to the repository:

docker tag my_project my_docker_hub_username/my_project
docker push my_docker_hub_username/my_project

Since your docker hub is likely private, you need to share the repository with the account `FutureMIREX (futuremirex@gmail.com)`. You can do this by going to the repository settings and adding the account as a collaborator.

Github Container Registry

To upload your docker image to Github Container Registry, you need to create a personal access token with the `write:packages` scope. Then you can push your docker image to the Github Container Registry:

docker login ghcr.io -u my_github_username -p my_personal_access_token
docker tag my_project ghcr.io/my_github_username/my_project
docker push ghcr.io/my_github_username/my_project

For private repo, you need to share the link to the docker image with the account `futuremirex`. You can do this by going to the repository settings and adding the account as a collaborator.

Google Drive

To upload your docker image to Google Drive, you need to first save the docker image as a tar file:

docker save -o my_project.tar my_project

Then you can upload the tar file to Google Drive and get a shareable link.

Potential Issues

Since docker images can be large, you may encounter issues when uploading the docker image especially with free accounts or slow internet connections. If you encounter issues, please contact the task captain for alternative ways to share the docker image.

Submission Portal

The submission portal is available at MIREX 2024 Submission Portal. There is a forum for each task where submissions are made. You may also ask questions about the task in the forum. Notice that some tasks may use external submission sites like codabench. The forum will have the link to the external submission site.

How to Submit

To submit for a task, you need to create a new topic in the forum of the task. The topic should contain the following information:

• Title: Your submission title (used for the leaderboard)
• Submission link: The link to your submission. Specifically,
  • For docker image submission to Docker Hub, the link should be the repository link (make sure to share the repository with `FutureMIREX`).
  • For docker image submission to Github Container Registry, the link should be the repository link (make sure to share the repository with `futuremirex`).
  • For docker image submission to Google Drive, the link should be the shareable link to the tar file.
  • For result submission, the link should be the shared link to the zip file.
• Description: A brief description of your submission. If you have included it in extended abstract, you can just write "See extended abstract".
• Extended abstract: An extended abstract of your submission.

Extended Abstract

Please submit a 2-4 page extended abstract PDF in the ISMIR format about the submitted program(s) to help us and the community better understand how the algorithm works when submitting their programme(s).

Other Questions

For other questions, please contact the task captain or the MIREX organizers.