Princess Elizabeth

A Quick Look at What Princess Elizabeth Actually Is

Princess Elizabeth is a lightweight Python training framework built for deep learning research workflows. It wraps around PyTorch and gives you a cleaner way to run experiments without writing the same boilerplate loops over and over again. The core idea is simple: define your dataset, model, and training loop in a config file, hand it off, and get structured outputs with logging, checkpointing, and early stopping handled for you. I started using it when my lab was cycling through five or six different training scripts for each experiment, and half of them had hardcoded batch sizes that broke when I switched GPUs. The switch to Princess Elizabeth cut our setup time for a new run from about forty minutes of fiddling down to roughly ten.

Installing and Running Princess Elizabeth

You can grab it from PyPI. A standard install looks like this: pip install princess-elizabeth It requires Python 3.9 or later and PyTorch 2.0+. I ran into an issue once where an older CUDA toolkit (11.3) conflicted with the default PyTorch version pulled in as a dependency, and the import failed silently with a weird C extension error. The workaround was straightforward — pin PyTorch to 2.1.0 before installing the package, and make sure your system CUDA matches. After that, it runs clean.

Here is a minimal training script you would write: from princess_elizabeth import Trainer, Config
config = Config("configs/my_experiment.yaml")
trainer = Trainer(config)
trainer.run() The YAML file is where everything lives. You define your data paths, model class, optimizer, learning rate schedule, validation frequency, and where checkpoints go. A typical config for a ResNet-50 image classification job might look like this:

model: resnet50
dataset: imagenet_subset
batch_size: 128
epochs: 50
optimizer: adamw
lr: 3e-4
checkpoint_dir: ./checkpoints/run_001
logging: tensorboard That is about it for the basic case. The framework handles the rest.

How It Actually Works Under the Hood

Princess Elizabeth does not reinvent the training loop. It generates one for you based on the config and injects hooks for validation, checkpointing, and metric tracking. The architecture follows a pipeline pattern where each stage — data loading, forward pass, loss computation, backward pass, optimizer step, and validation — is a pluggable component. This means you can swap out the DataLoader wrapper or the metric tracker without touching the core loop. One thing most people miss is that the framework supports distributed training out of the box via torch.distributed. You do not need to write any DDP boilerplate. You just set the backend flag in your config and launch with torchrun. I found this particularly useful when moving from single-GPU prototyping to an 8-GPU node. The only catch is that your dataset implementation needs to support sharding by rank and seed, or you will get duplicate samples across processes. I spent about two hours debugging strange validation metrics one time before realizing my custom Dataset was not seeding the sampler correctly across ranks. Once I added the rank-based split, everything normalized.

Advanced Usage and Common Pitfalls

The config system supports variable interpolation, so you can reference one value inside another. This is handy for keeping paths and names consistent without duplication. But it also means you need to be careful about the order in which keys are defined, since references are resolved at parse time. I once had a config where a path variable referenced another variable that was defined below it, and the framework threw a KeyError that took me a while to trace back to the ordering issue. Another thing worth noting is that the built-in logging covers TensorBoard and CSV. If you need Weights & Biases or a custom logger, you have to write a small adapter. The docs show an example, but it is easy to get the hook signature wrong and end up with silent data loss in your runs. I learned this the hard way when I switched to W&B and realized my custom adapter was dropping the validation loss values because of a key name mismatch. The framework also has a --resume flag that picks up from the latest checkpoint in your output directory. This works well for most cases, but it assumes your config has not changed between runs. If you modified the model architecture or the optimizer parameters after the checkpoint was saved, resuming will likely fail or produce incorrect results. Always double-check that your config is stable before relying on resumption for long runs.

When Princess Elizabeth Is Not the Right Tool

It is not designed for production inference pipelines. The overhead from the config parsing and hook system adds a small amount of latency, which matters when you are running millions of forward passes in a serving context. For inference, stick to raw PyTorch or TorchServe. It is also less suitable for non-standard architectures that require deeply custom training logic. If your model needs a novel gradient flow or a custom distributed strategy beyond what torch.distributed offers, you will end up fighting the framework more than helping with it. In those cases, writing your own loop is faster in the long run. The project is actively maintained, but releases are infrequent compared to something like Lightning. Feature requests sit in the issue tracker for months. If you need something quickly — like native support for a new optimizer or a specific mixed-precision mode — you are better off contributing a PR or using a different framework. For most research prototyping work, though, it does what it says. You define the experiment, you run it, you get the outputs. That is the whole point.