How Jupyter Notebooks Are Organized Across PyTorch and TensorFlow Versions Per Lesson

The microsoft/AI-For-Beginners repository structures each lesson into dedicated folders containing parallel Jupyter Notebooks with framework-specific suffixes, allowing learners to choose between PyTorch and TensorFlow implementations while maintaining identical educational narratives.

The microsoft/AI-For-Beginners curriculum employs a dual-framework architecture that ensures every major concept is taught through both PyTorch and TensorFlow lenses. This article examines how Jupyter Notebooks are organized across PyTorch and TensorFlow versions per lesson, revealing the systematic folder hierarchy and naming conventions that keep the codebase maintainable and learner-friendly.

Folder Structure and Naming Conventions

One-Folder-Per-Lesson Architecture

The repository adheres to a strict one-folder-per-lesson design principle. Each teaching unit resides in a dedicated directory named with the pattern <lesson-id>-<LessonName>. For example, the Convolutional Neural Networks lesson occupies lessons/4-ComputerVision/07-ConvNets/, while the Named Entity Recognition lesson is located at lessons/5-NLP/19-NER/.

This containerization ensures that all assets—notebooks, data references, and supplementary files—remain logically grouped regardless of which deep learning framework the learner selects.

Framework-Specific File Suffixes

Within each lesson folder, notebooks follow a rigorous framework suffix convention:

• PyTorch implementations use the suffix PyTorch.ipynb (e.g., ConvNetsPyTorch.ipynb)
• TensorFlow implementations use the suffix TF.ipynb (e.g., ConvNetsTF.ipynb)

This naming strategy makes the target library explicit at the filesystem level and enables automated scripts to programmatically select the appropriate file. The only exception to this pattern appears in lessons/3-NeuralNetworks/05-Frameworks/IntroPyTorch.ipynb, which serves as an introductory notebook demonstrating basic setup concepts before the parallel track system begins.

Implementation Examples by Domain

Computer Vision Lessons

The Computer Vision module (lessons/4-ComputerVision/) demonstrates the parallel notebook pattern clearly. In the ConvNets lesson at lessons/4-ComputerVision/07-ConvNets/, learners find ConvNetsPyTorch.ipynb alongside ConvNetsTF.ipynb. Both files cover identical CNN architectures and training workflows, differing only in API implementations—torch.nn versus tensorflow.keras layers.

Similarly, the GANs lesson in lessons/4-ComputerVision/10-GANs/ splits into GANPyTorch.ipynb and GANTF.ipynb, while the Transfer Learning lesson at lessons/4-ComputerVision/08-TransferLearning/ maintains the convention with TransferLearningPyTorch.ipynb and TransferLearningTF.ipynb.

Natural Language Processing Tracks

The NLP section (lessons/5-NLP/) extends this organization across sequential modeling tasks. The Named Entity Recognition implementation at lessons/5-NLP/19-NER/NER-TF.ipynb provides the TensorFlow approach, while lessons/5-NLP/19-NER/NER-PyTorch.ipynb delivers the PyTorch equivalent.

Language modeling exercises follow suit: lessons/5-NLP/15-LanguageModeling/ contains CBoW-PyTorch.ipynb paired with CBoW-TF.ipynb, and the Transformers lesson at lessons/5-NLP/18-Transformers/ offers both TransformersPyTorch.ipynb and TransformersTF.ipynb.

Deep Reinforcement Learning

Even specialized domains maintain framework parity. The Deep RL lesson located at lessons/6-Other/22-DeepRL/ includes CartPole-RL-PyTorch.ipynb and CartPole-RL-TF.ipynb, allowing learners to implement policy gradient methods using their preferred backend.

Pedagogical Design Principles

Parallel Content Architecture

The narrative text, markdown explanations, and dataset handling remain largely identical across both versions; only the code cells differ to reflect the API of the chosen framework. This parallel structure reinforces conceptual understanding while highlighting framework-specific syntax differences.

Consistent Import Patterns

Every notebook begins with standardized import blocks that immediately signal the framework context:

# PyTorch variant

import torch
import torch.nn as nn

# TensorFlow variant  

import tensorflow as tf
from tensorflow import keras

This consistency ensures that learners can context-switch between frameworks without encountering unexpected structural variations.

Shared Data Assets

Datasets such as MNIST and CIFAR-10 reside outside the notebooks in shared directories. Both framework versions load identical data sources without file duplication, reducing repository bloat and ensuring reproducibility across implementations.

Localization Support

The framework-split design propagates through the localization system. Each lesson folder is duplicated under translations/<lang>/lessons/... while preserving the same naming scheme, ensuring that international learners have access to both PyTorch and TensorFlow versions in their preferred language.

Programmatic Discovery of Framework-Specific Notebooks

The systematic naming convention enables automation for curriculum tools or custom launchers. The following function locates the correct notebook for any given lesson and framework:

import pathlib
import nbformat

def get_notebook_path(lesson_dir: str, framework: str) -> pathlib.Path:
    """
    Return the path to the notebook matching the requested framework.
    framework must be either 'pytorch' or 'tf'.
    """
    base = pathlib.Path(lesson_dir)
    suffix = "PyTorch.ipynb" if framework.lower() == "pytorch" else "TF.ipynb"
    candidates = list(base.glob(f"*{suffix}"))
    if not candidates:
        raise FileNotFoundError(f"No notebook for {framework} in {lesson_dir}")
    return candidates[0]

# Example: locate the notebook for lesson 07-ConvNets in PyTorch

lesson_path = "lessons/4-ComputerVision/07-ConvNets"
nb_path = get_notebook_path(lesson_path, "pytorch")
nb = nbformat.read(nb_path, as_version=4)
print(f"Loaded {nb_path.name} with {len(nb.cells)} cells")

This pattern allows educational platforms to dynamically serve the appropriate framework version while maintaining a single source of truth for lesson metadata.

Summary

• Folder containment: Each lesson lives in a dedicated <lesson-id>-<LessonName> directory under its respective module (e.g., lessons/4-ComputerVision/).
• Suffix convention: Files ending in PyTorch.ipynb contain PyTorch code, while TF.ipynb files contain TensorFlow implementations of the same lesson.
• Content parity: Educational narrative and dataset references remain identical across both versions; only implementation code differs.
• Translation inheritance: The dual-framework structure persists across all language translations in the translations/ directory.
• Automation support: The predictable naming scheme enables programmatic notebook discovery and curriculum management tools.

Frequently Asked Questions

How do I identify which framework versions are available for a specific lesson?

Navigate to the lesson's directory (e.g., lessons/5-NLP/19-NER/) and inspect the file listing. If the folder contains both NER-PyTorch.ipynb and NER-TF.ipynb, both implementations are supported. Some introductory lessons, such as lessons/3-NeuralNetworks/05-Frameworks/IntroPyTorch.ipynb, may initially offer only one framework before the parallel tracks begin.

Are datasets duplicated for each framework version?

No. Shared data files for MNIST, CIFAR-10, and other standard datasets live outside the notebooks in common directories. Both ConvNetsPyTorch.ipynb and ConvNetsTF.ipynb reference the same data sources, eliminating duplication while ensuring that learners working in either framework train on identical inputs.

Does the repository maintain translations for both PyTorch and TensorFlow versions?

Yes. The repository duplicates each lesson folder under translations/<lang>/lessons/ while preserving the exact folder hierarchy and naming conventions. A Spanish learner, for example, can access both PyTorch and TensorFlow versions of lessons/4-ComputerVision/07-ConvNets/ within the Spanish translation tree.

Can I switch between PyTorch and TensorFlow while working through the same lesson?

Absolutely. Because the notebooks share identical markdown explanations and section headers, you can abandon ConvNetsPyTorch.ipynb at any cell boundary and resume the same conceptual position in ConvNetsTF.ipynb. The only adjustment required is adapting to the framework-specific API calls (e.g., replacing torch.nn.Conv2d with tf.keras.layers.Conv2D), as the underlying mathematical concepts and training workflows remain consistent.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}