This document summarizes the workflow and practical tips I currently follow. Please note that this version is a draft.



# Workflow. 
This section provides an overview of tools and practices aimed at improving reproducibility, experiment tracking, and code reliability in research workflows. Each subsection briefly describes a component of the workflow, its purpose, and recommendations based on practical experience.

## Pre-commit  
Pre-commit is a useful tool for ensuring code standardization in a reproducible manner. I have tested several pre-commit configurations and, for research-oriented projects, I recommend using lightweight hooks such as those described [here](https://github.com/gardiens/research-project-template/blob/main/.pre-commit-config.yaml).  
To set it up, simply run `pre-commit install`. Once installed, the checks will automatically run with each commit.


## Hydra 
When doing more experiments, it is really important to be able to track and backtrack any improvements and changes. Hydra is a python framework that provides a (not) convenient way to create a hierarchical configuration by compisition and override through config files and command lines.  I will ( or should have) created a blogs about it

## TensorBoard / ClearML  
Effective experiment tracking requires a robust logging tool. I have personally used ClearML, which allows monitoring of experiment outcomes. In the future, I plan to systematically store my scripts alongside experiments to facilitate reproducibility and experimentation history. It is really important when writing report and competitions and you can feel the huge difference when you are using it or not.

## Workflows  
Automation workflows (e.g., GitHub Actions) can verify that code executes correctly upon each commit or push. They are especially useful for ensuring reproducibility of installations and validating that tests pass consistently. I recommend combining this with Pytest, although setting up workflows locally can be complex.

## Pytest  
Pytest provides a means to verify the core functionality of your codebase. In deep learning and prototyping contexts, extensive test coverage may not be essential, but testing core scripts such as `main.py` or major functions is beneficial. This ensures peace of mind when collaborating within a team.

## Auto Typer  
This tool has potential, but I do not yet have sufficient experience with it to incorporate it into my current workflow.


## Tips
### Writing the Results Section  
A colleague once recommended a clear structure for writing results:  
" we have **CAUSE** which causes **PROBLEMS**. therefore we or they do **CONTRIBUTION**  and **WHY WE SOLVE IT**"
This framework has significantly improved the clarity of my writing, especially in research papers where structure can make a substantial difference — including my own work.

### Python Notebooks  
Python notebooks have recently gained popularity as a convenient tool for writing and executing code in educational contexts such as labs or tutorials. However, for projects requiring more than one hour of sustained development, notebooks present several critical limitations:

- **Poor version control:** Traditional versioning systems like Git are not well-suited to notebooks. Commits do not clearly show line-by-line code changes, and merge conflicts are difficult to resolve.
- **Non-linear execution:** Notebooks allow cells to be executed in arbitrary order, which undermines reproducibility. It becomes difficult to ensure that the notebook can run from top to bottom without errors.
- **Resource inefficiency:** For memory- or GPU-intensive tasks, Jupyter can be inefficient and place significant load on system resources, making it less suitable for heavy computations.
- **Short lifecycle and poor maintainability:** In practice, notebooks often lack sufficient documentation and structure. Over time, users forget the purpose and logic of the code, leading to repeated, redundant work.

Based on these limitations, I recommend the following workflow:

- Core functions should be defined in `.py` files organized in a standard Python project structure. This promotes clarity, reuse, and traceability of changes through version control.
- The notebook itself should only contain function calls and minimal code for visualization or debugging. It should not serve as the primary implementation file.

In summary, I strongly discourage the use of notebooks as the main development environment. Instead, I advocate for using a proper logging system and structured Python scripts.

Workflow and Tips


This document presents a brief tutorial on the Hydra framework.



# Hydra


## Introduction 
Hydra is a python framework that provides a (not) convenient way to create a hierarchical configuration by compisition and override through config files and command lines. 
This tutorial is designed to hydra in this project as a **end-user** and will not cover it. We refer to the official documentation for more information.

From a personal standpoint, I would advise caution when using Hydra independently. The official documentation can be difficult to navigate, and community support (e.g., Stack Overflow) is currently limited. Unfortunately, viable alternatives are also scarce.

## Structure
all the `.yaml` files are located in the folder `configs/`. Every folder are (unless stated so ) an subconfiguration that will be called to initialize a part of SPT.

## Discover Hydra :
If you want to test by yourself, just create a python script my_app.py and paste this code:
```python
from omegaconf import DictConfig, OmegaConf
import hydra

@hydra.main(version_base=None, config_path=".", config_name="config")
def my_app(cfg):
    print(OmegaConf.to_yaml(cfg))

if __name__ == "__main__":
    my_app()
```
and create an adequate config.yaml next to this file based on what you want to test.

## Command Line :

### load a configuration:

To load a configuration, simply pass `name_configuration=NAME.yaml` after your script 

example:

```bash
python src/train.py datamodule=s3dis_simulated.yaml
```
will load in cfg.datamodule the .yaml `datamodule/s3dis_simulated.yaml`


example: 
```bash
python src/train.py experiment=train/s3dis_simulated.yaml
```

will load in `cfg.datamodule` the .yaml `experiment/train/s3dis_simulated.yaml`

> **Warning**: if you want to load a configuration nested in another package, you have to specify the relative path with / :
example:
 ```bash
python src/train.py experiment=train/s3dis_simulated.yaml predict=predict_s3dis_sim  predict/transfer_config@predict=s3dis_11g
```
> will load (IN PYTHON) in `cfg.predict.transfer_config` the .yaml `s3dis_11g`. Beware the `/` here. The @ is not important here and will be explained later. 

### Change a parameter:

To change a parameter in some config from command line, just write ` my_parameters=new_value`.

example: 

```bash
python src/train.py experiment=train/s3dis_simulated.yaml datamodule.pc_tiling=2
```


If the parameter is nested, you have to use a dot `.` 

example:

```bash
python src/train.py experiment=train/s3dis_simulated.yaml predict=predict_s3dis predict.on_predictions_parameters.save_pred_dataset_to_cloudpoint=True
```
will change the parameters `save_pred_dataset_to_cloudpoint` in  `cfg.predict.on_predictions_parameters` to  `True`



### Going Further

With the command line, you can do complex interpolation, see [interpolation](https://hydra.cc/docs/advanced/override_grammar/basic/) for more information. For more information , see [see](https://hydra.cc/docs/advanced/override_grammar/basic/) as well.

## From a .yaml file:

A Hydra .yaml files is usually composed of 2 things and one optional things: a defaults_list, a list of parameters and optionally a `@package` at the beginning. 


### the defaults list: 

[It](https://hydra.cc/docs/advanced/defaults_list/) specifies how other .yaml will be interconnected:

example: 
```yaml
defaults:
    - datamodule: s3dis.yaml
    - model: spt-2.yaml
```
will load the `datamodule.s3dis.yaml` in `cfg.datamodule` .

### list of parameters:

After the defaults list, it specify a list of entry of cfg. 


### the ` @`  :
the `@` specify how to build in the hierarchical structure.
If it i at the beginning of a .yaml file, it says that the parameters inside the .yaml will be append in the corresponding package:

example 
```yaml
# @package _global_

test: True
```
will set the key `cfg.test` to True even though it was called as a subconfig. 

For further information, see [here](https://hydra.cc/docs/advanced/overriding_packages/)




## TroobleShoot:

### What is the overrides thing ? 


Sometimes, some config can have the words override before, it is because some package can point to the same key several times, it is quite technical and change ` -datamodule: s3dis.yaml` to `override datamodule:s3dis.yaml` if the error happens, just add or remove override and see what works.


### Why do you have all those @ in some .yaml file:
 It specifies the relative place of a .yaml file in the hierarchical configuration. If you are using these, the intertwin between every configuration can be quite complex and not completely obvious.
 If you want to call a  `.yaml` and hydra cannot  find it , specify the ABSOLUTE path instead of the relative one, this should always works.
 
 example: 
 ```.yaml 
 /predict/transfer_config/default.yaml@_here_
 ```
will load the configuration `/predict/transfer_config/default.yaml` in the configuraton `cfg`. 


If the CI doesn't work and ask to appen some @ , just do it . 
  

Workflow and Tips

Hydra explained by a noob

My Socials

Mail :

Mail :