Skip to content

Quickstart

This quickstart guide will walk you through setting up Cubyc and running your first experiment.

Remote Only

Items displayed in a light blue box are optional and only necessary to save your experiments in the cloud.

Step 1: Prerequisites

Before diving in, make sure you have:

  • Python 3.8 or higher
  • Git

Remote Only

You'll also need a GitHub, GitLab, or Bitbucket account.

Step 2: Set Up Cubyc

Installing Cubyc is a breeze. Simply run:

pip install cubyc

Or, if you want the latest, clone our GitHub repo and run:

pip install .

Remote Only

To authenticate queries with your cloud repository provider, you need to save an access token in your machine.

  1. Create a new repository on GitHub

  2. Create a personal access token with full repo permissions

  3. Save your GitHub access token with Cubyc by running: 

cubyc login github <GITHUB_ACCESS_TOKEN>

  1. Create a new repository on GitLab

  2. Create a developer, maintainer, or owner access token with read_api permissions

  3. Save your GitLab access token with Cubyc by running:

cubyc login gitlab <GITLAB_ACCESS_TOKEN>

  1. Create a new repository on Bitbucket

  2. Create a repository, project, or workspace access token with read permissions

  3. Save your Bitbucket access token with Cubyc by running:

cubyc login bitbucket <BITBUCKET_ACCESS_TOKEN>

Create a new repository (step 1) for each project you want to save remotely. However, you only need to create an access token (step 2 and 3) once for all your projects.

Step 3 Initialize a Project

Create a directory for your project, navigate to it, and initialize a new Cubyc project:

cubyc init

Be sure to add any files you don't want to track to the auto-generated .gitignore file!

Remote Only

To automatically save your experiment runs to the cloud, you can add remote repositories with Git. If you clone an existing Git repository, the remote is already set up. Otherwise, add a remote repository to your project:

git remote add origin <YOUR_REPO_REMOTE_URL>

Step 4: Run Your Experiment

You're all done setting up Cubyc! Now, let's run a simple experiment to test it out. Inside your project, create and run a Python script with the following code:

run_script.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import numpy as np
from cubyc import Run

@Run(tags=["linear_algebra"])
def matrix_multiplication(n_size: int):
    A = np.random.rand(n_size, n_size)
    B = np.random.rand(n_size, n_size)

    _ = np.dot(A, B)

for n_size in [10, 20, 40, 80, 160, 320, 640]:
    matrix_multiplication(n_size=n_size)

Cubyc automatically commits the inputs, code, and outputs of your latest experiment run to the .cubyc directory. Your run history is preserved in the .git directory, and if configured, in a remote repository as well.

Remote Only

As an alternative to linking your project to a remote repository using Git (step 3), you can also save your experiment runs directly to the cloud by passing the remote repository URL to the Run constructor:

4
@Run(remote="https://github.com/owner/project", tags=["linear_algebra"])

Step 5: Query Your Results

To analyze your experiment results, you can use SQL queries with Cubyc. Create and run a new Python script in the same project directory with the following code:

query_script.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from cubyc import query

statement = """
                SELECT config.n_size, metadata.runtime
                FROM config
                INNER JOIN metadata ON config.id = metadata.id
                ORDER BY metadata.runtime ASC
            """

print(query(statement=statement))

Output: 

>>>    n_size   runtime
... 0      10  0.012209
... 1      20  1.455673
... 2      40  2.768197
... 3      80  4.073367
... 4     160  5.336599
... 5     320  6.663631
... 6     640  8.028414

This query returns the matrix n_size and duration of each run, ordered by duration. Notice how the runtime doesn't increase linearly with the matrix size?

Remote Only

You can also pass results from the cloud by passing the remote repository URL to the query function:

10
print(query(path="https://github.com/owner/project.git", statement=statement))

Congratulations, you just ran and analyzed your first experiment with Cubyc! For a more in-depth look at Cubyc's features, check out the concepts page.