Awesome

smilelogging

Python logging package for easy reproducible experimenting in research. Developed by the members of SMILE Lab.

Why this package may help you

This project is meant to provide an easy-to-use (as easy as possible) package to enable reproducible experimenting in research. Here is a struggling situation you may also encountered:

I am doing some project. I got a fatanstic idea some time (one week, one month, or even one year) ago. Now I am looking at the results of that experiment, but I just cannot reproduce them anymore. I cannot remember which script and what hyper-prarameters I used. Even worse, since then I've modified the code (a lot). I don't know where I messed it up ...:cold_sweat:

Usually, what you can do may be:

First, use Github to manage your code. Always run experiments after git commit.
Second, before each experiment, set up a unique experiment folder (with a unique ID to label that experiment -- we call it ExpID).
Third, when running an experiment, print your git commit ID (we call it CodeID) and arguments in the log.

Every result is uniquely binded with an ExpID, corresponding to a unique experiment folder. In that folder, CodeID, arguments, and others (logs, checkpoints, etc.) are saved. So ideally, as long as we know the ExpID, we should be able to rerun the experiment under the same condition.

These steps are pretty simple, but if you implement them over and over again in each project, it can still be quite annoying. This package is meant to save you with basically 2~3 lines of code change.

Usage

Step 0: Install the package (>= python3.4)

# We will use PyTorch code as an example, so please also install PyTorch here
pip install torch torchvision

# Clone this repo and install from source (pypi may not be the lastest!)
git clone https://github.com/MingSun-Tse/smilelogging.git
cd smilelogging
pip install -e .

Step 1: Modify your code

Here we use the PyTorch MNIST example to give a step-by-step example. In total, you only need to add 2 lines of code and replace 1 line.

from torch.optim.lr_scheduler import StepLR
from smilelogging import Logger  # ==> Add this line

# parser = argparse.ArgumentParser(description='PyTorch MNIST Example')
from smilelogging import argparser as parser  # ==> Replace above with this line

args = parser.parse_args()

# ==> Add this line. This will overwrite the system print function.
logger = Logger(args, overwrite_print=True)  

# ==> Or, if you do not want to overwrite the system print function, add this line. Then use `logger.info` to print.
logger = Logger(args)

We already put the modified code at test_example/main.py, so you do not need to edit any file now. Simply cd test_example and continue to next step.

Step 2: Run experiments

The original MNIST training snippet is:

python main.py

Now, try this:

python main.py --experiment_name lenet_mnist

This snippet will set up an experiment folder at path Experiments/lenet_mnist_XXX. That XXX thing is an ExpID automatically assigned by the time running this snippet. Below is an example on my PC:

Experiments/
└── lenet_mnist_SERVER138-20211022-184126
    ├── gen_img
    ├── log
    │   ├── git_status.txt
    │   ├── gpu_info.txt
    │   ├── log.txt
    │   ├── params.yaml
    │   └── plot
    └── weights

<h4 align="center">:sparkles:Congrats:beers:You're all set:exclamation:</h4>

As seen, there will be 3 folders automatically created: gen_img, weights, log. Log text will be saved in log/log.txt, arguments saved in log/params.yaml and in the head of log/log.txt. Below is an example of the first few lines of log/log.txt:

cd /home/wanghuan/Projects/smilelogging/test_example
python main.py --project_name lenet_mnist

('batch_size': 64) ('cache_ignore': ) ('CodeID': 023534a) ('debug': False) ('dry_run': False) ('epochs': 14) ('gamma': 0.7) ('log_interval': 10) ('lr': 1.0) ('no_cuda': False) ('note': ) ('project_name': lenet_mnist) ('save_model': False) ('seed': 1) ('test_batch_size': 1000)

[184126 6424 2021/10/22-18:41:29] ==> Caching various config files to 'Experiments/lenet_mnist_SERVER138-20211022-184126/.caches'

Note, it tells us

(1) where is the code
(2) what snippet is used when running this experiment
(3) what arguments are used
(4) what is the CodeID -- useful when rolling back to prior code versions (git reset --hard <CodeID>)
(5) where the code files (*.py, *.json, *.yaml etc) are backuped -- note the log line ==> Caching various config files to .... Ideally, CodeID is already enough to get previous code. Caching code files is a double insurance
(6) At the begining of each log line, the prefix [184126 6424 2021/10/22-18:41:29] is automatically added if the logger.print func is used for print, where 184126 is short for the full ExpID SERVER138-20211022-184126, 6424 is the program pid (useful if you want to kill the job, e.g., kill -9 6424)

More Explanantions about the Folder Settings

The weights folder is supposed to store the checkpoints during training; and gen_img is supposed to store the generated images during training (like in a generative model project). To use them in the code:

weights_path = logger.weights_path
gen_img_path = logger.gen_img_path
log_path = logger.log_path

For more these path names, see here.

More Explanantions about the Arguments and TIPs

If you are debugging code, you may not want to create an experiment folder under Experiments. Then use --debug, for example:

python main.py --debug

This will save all the logs in Debug_Dir, instead of Experiments (Experiments is expected to store the formal experiment results).

Mission of this project

We target 100% open scientific experimenting:

Every number or data point in the paper (either in tables or figures) is traceable with a log/checkpoint.
Releasing the reviewing comments and communication process.

Collaboration / Suggestions

Currently, this is still an alpha project. Any collaboration or suggestions are welcome to Huan Wang (Email: wang.huan@northeastern.edu).