GitHub Repository: NVIDIA/cuda-q-academic
Path: blob/main/notebook_template.ipynb
⁵⁷⁹ views

Kernel: Unknown Kernel

In [ ]:

# SPDX-License-Identifier: Apache-2.0 AND CC-BY-NC-4.0
#
# Licensed 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.

Title of the Notebook

Overview

Include a code block above the Title of the Notebook which contains the licensing information. Provide a brief overview of the notebook's content and its objectives. Explain what the reader will learn and any prerequisites they need to understand. If possible, provide links to prerequisite learning material. Inlcude a list of measureable learning objectives using action verbs:

Apply someFunction to solve some problem
Write a function that takes two numbers and returns their sum
Use and interpret new notation and terminology
Experiment with different parameters to examine their effect on the solution
Benchmark someMethod against anotherMethod
Visualize the convergence of the model

Ideally, the exercises in the notebook should address all of the learning objectives.

Introduction

Introduce the topic in more detail. Provide background information and context to help the reader understand the importance of the topic. If the notebook is lengthy, provide a short outline or table of contents to help the reader navigate the material.

Setup

Include any necessary setup instructions here, such as:

Installing libraries
Downloading datasets
Setting up configurations

Code, not intended for immediate execution, should be included with three back ticks and the descriptor python as part of a markdown block:

# Example setup code in a markdown block
!pip install some-library

Code intended for the reader to execute should be included in separate python blocks:

In [ ]:

# Example setup code
!pip install some-library

Main Content

This section should contain the core content of the notebook. Use descriptive headers to organize the content. The main content can be distributed over multiple level two headers if it is lengthy. The main content can include:

Theoretical explanations
Examples and demonstrations
Visualizations
Code snippets
Video explanations

If using a data set, add a section to handle the data including:

Loading the data
Displaying the first few rows
Summarizing the dataset
Preprocessing the data

In [ ]:

# Example data exploration code
import pandas as pd

data = pd.read_csv('data.csv')
data.head()

While creating content, please keep the guidelines below in mind.

Style guidelines for Markdown

Use the following guidelines for styling the Markdown:

When they appear inline with the text; directive names, clauses, function or subroutine names, variable names, file names, commands and command-line arguments should appear between two back ticks.
Emphasis, including quotes made for emphasis and introduction of new terms should be highlighted between a single pair of asterisks.
A level 1 heading should appear at the top of the notebook as the title of the notebook.
A horizontal rule should appear between sections that begin with a level 2 heading.

Guidelines for Media

All images should be stored in a separate folder titled images. For screen readers, add descriptive text to any visual content.

Code Documentation Guidelines

To ensure that the code in the notebooks is easy to understand and maintain, please follow these documentation guidelines:

Use Comments: Add comments to explain the purpose of the code, especially for complex logic. Use inline comments for small explanations and block comments for larger sections.
```
# Load the dataset
data = pd.read_csv('data.csv')

# Fill missing values using forward fill method
data = data.fillna(method='ffill')
```

Docstrings: Use docstrings to describe functions, classes, and methods. Include information about parameters, return values, and any exceptions raised.

def preprocess_data(data):
    """
    Preprocess the input data by filling missing values.

    Parameters:
    data (DataFrame): The input data to preprocess.

    Returns:
    DataFrame: The preprocessed data.
    """
    return data.fillna(method='ffill')

Descriptive Variable Names: Use clear and descriptive variable names that convey the purpose of the variable.

# Split the data into features (X) and target (y)
features = data.drop('target', axis=1)
target = data['target']

Section Headers: Use markdown headers to organize the notebook into sections. This helps readers navigate through the content easily.
Explain Outputs: After displaying outputs (e.g., plots, tables), add markdown cells to explain what the output shows and its significance.
```
import matplotlib.pyplot as plt

plt.hist(data['column_name'])
plt.show()
```
The histogram above shows the distribution of values in the 'column_name' column. It indicates that most values are concentrated around the mean.

Guidelines for Exercises

Exercises for students are an important feature to include. They can be included within the narrative and/or in a separate section at the end of the notebook.

Clearly label exercises with a heading, such as ## Exercise.
Provide a brief description or question for the exercise.
If applicable, include starter code in a code block.
Use comments in the starter code to guide students on what to do.
Provide signposts for the portions of the code that the student should edit (i.e., # Edit code above/below this line, TODO, FIXME, etc.).
Provide solutions to exercises in a separate notebook stored in a solutions directory. Alternatively, contact the site administrator for instructions on contributing autograded code.

Example:

In [ ]:

## Exercise: Basic Arithmetic

# Write a function that takes two numbers and returns their sum.

# Starter code
def add_numbers(a, b):
    # TODO: Implement this function
    pass

# Example usage
print(add_numbers(2, 3))  # Expected output: 5

Conclusion

Summarize the key takeaways from the notebook. Provide any final thoughts or next steps for further exploration, including additional notebooks in the repository.

References

List any references or resources used in the notebook. Follow these formatting guidelines for consistency:

Books: Author(s), "Title of the Book," Edition (if applicable), Publisher, Year.
- Example: John Doe, "Data Science Fundamentals," 2nd Edition, Data Science Press, 2021.
Journal Articles: Author(s), "Title of the Article," Journal Name, Volume(Issue), Page numbers, Year.
- Example: Jane Smith, "A Study on Machine Learning Algorithms," Journal of Machine Learning, 15(3), 123-145, 2020.
Websites: Author(s) (if available), "Title of the Webpage," Website Name, URL, Accessed: Date.
- Example: John Doe, "Introduction to Python," Python.org, https://www.python.org/about/gettingstarted/, Accessed: October 15, 2023.
Datasets: Dataset Title, Provider, URL (if available), Accessed: Date.
- Example: "UCI Machine Learning Repository: Iris Data Set," UCI Machine Learning Repository, https://archive.ics.uci.edu/ml/datasets/iris, Accessed: October 15, 2023.

By following these guidelines, you will help ensure that the notebooks are clear, informative, and easy to understand for all users.

Thank you for contributing!