Xmen¶

||||||||||||||||||||||||| WELCOME TO ||||||||||||||||||||||||||
||                                                           ||
||    \\\  ///  |||\\        //|||  |||||||||  |||\\   |||   ||
||     \\\///   |||\\\      ///|||  |||        |||\\\  |||   ||
||      ||||    ||| \\\    /// |||  ||||||     ||| \\\ |||   ||
||     ///\\\   |||  \\\  ///  |||  |||        |||  \\\|||   ||
||    ///  \\\  |||   \\\///   |||  |||||||||  |||   \\|||   ||
||                                                           ||
|||||||||||| FAST - REPRODUCIBLE - EXPERIMENTATION ||||||||||||

xmen¶

Define experiments in experiments

from xmen import Experiment, Root

# as classes... 
class HelloWorld(Experiment):
    """A class experiment"""
    a: str = 'Hello' # @p The first argument
    b: str = 'World' # @p The second argument

    def run(self):
        print(f'{a} {b}!')

# as functions...
def hello_world(
  root: Root, 
  a: str = 'Hello',  # the first argument
  b: str = 'World'   # the second argument
  ):
  """A functional experiment"""
  print(f'{a}  {b}')

Configure and run from the command line

# add an experiment
>>> xmen experiments --add xmen.examples.hello_world HelloWorld
# get documentation
>>> xmen experiments HelloWorld  
  A class experiment

  Parameters:
      a: str=Hello ~ the first argument
      b: str=World ~ the second argument
# initialise experient folder
>>> xmen init -n HelloWorld -r .
# link experiments
>>> xmen link -u "{a: Hello | Bye, b: World | Planet}"
# visulaise
>>> xgent list -ds -p ".*"
   root               name      status              created      a       b
0  exps   a=Hello__b=World  registered  2020-09-04-18-36-12  Hello   World
1  exps  a=Hello__b=Planet  registered  2020-09-04-18-36-11  Hello  Planet
2  exps     a=Bye__b=World  registered  2020-09-04-18-36-11    Bye   World
3  exps    a=Bye__b=Planet  registered  2020-09-04-18-36-10    Bye  Planet
# run
>>> xmen run "*" bash
>>> xmen run "*" screen -dm bash
>>> xmen run "*" docker ...
>>> xmen run "*" sbatch

Installation¶

To install xmen use pip

pip install git+https://github.com/robw4/xmen.git

Alternatively, clone the repo and then run pip if you also want access to the example scripts.

>>> git clone https://github.com/robw4/xmen.git ~/xmen
>>> pip install ~/xmen/experiments
>>> xmen

usage: xmen [-h]
            {experiments,config,init,link,run,note,reset,unlink,clean,rm,relink,list}
            ...

||||||||||||||||||||||||||| WELCOME TO |||||||||||||||||||||||||||
||                                                              ||
||          &@&@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@&@&%          ||
||         *@&@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@&         ||
||          &@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@&          ||
||           &@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@&          ||
||           &@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@#          ||
||           &@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@&.          ||
||           &@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@.          ||
||           &@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@*          ||
||           @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@          ||
||   #&@@@@@&%&&&&&&&@@@@@@@@@@@@@@@@@@@@@@@@@&&&&&&&&@@@@@@&#  ||
||  /#%%%%%%%%%&&@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@&&%%&%%%%%%#  ||
||   &%&&&&&&&&&&&@@@@@@@@@@@@@@@@@@@@@@@@@@@&&@&&&&&&&&&&&&&   ||
||     (@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@&.    ||
||      ...,*/#%@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@&##(*,...      ||
||                                                              ||
||    \\\  ///  |||\\        //|||  |||||||||  |||\\   |||      ||
||     \\\///   |||\\\      ///|||  |||        |||\\\  |||      ||
||      ||||    ||| \\\    /// |||  ||||||     ||| \\\ |||      ||
||     ///\\\   |||  \\\  ///  |||  |||        |||  \\\|||      ||
||    ///  \\\  |||   \\\///   |||  |||||||||  |||   \\|||      ||
||                                                              ||
||                      %@@,     (@@/                           ||
||                     @@@@@@@@@@@@@@@@@@@@@                    ||
||        @@        @@@@@@@@@@@@@@@@@@@@@@@@@@/        @#       ||
||       @@#     @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@#     @@       ||
||        @@@@@@@@@@@@@@@@@@@@@@@.@@@@@@@@@@@@@@@@@@@@@@.       ||
||           ,@@@@@@@@@@@@@@@%       @@@@@@@@@@@@@@@@           ||
||                                                              ||
|||||||||||||| FAST - REPRODUCIBLE - EXPERIMENTATION |||||||||||||

positional arguments:
  {experiments,config,init,link,run,note,reset,unlink,clean,rm,relink,list}
    experiments              Python interface
    config              View / edit the global configuration
    init                Initialise an experiment set
    link            Register a set of experiments
    run                 Run experiments matching glob in experiment set that have not yetbeen run.
    note                add notes to an experiment
    reset               Reset an experiment to registered status
    unlink              Unlink experiments from experiment set
    clean               Remove unlinked experiments (DESTRUCTIVE)
    rm                  Remove an experiment set (DESTRUCTIVE)
    relink              Relink experiments to global configuration or to a set root
    list                list experiments to screen

optional arguments:
  -h, --help            show this help message and exi

Tutorials, Examples, Documentation¶

Full documentation (including the experiments API) can be found here

Several example experiment definitions can be found in xmen.examples:

xmen.examples
├── hello_world.py
├── inheritance.py
├── monitor
│   ├── __init__.py
│   ├── checkpoint.py
│   ├── logger.py
│   ├── messenger
│   │   ├── __init__.py
│   │   ├── basic.py
│   │   ├── expand.py
│   │   ├── leader.py
│   │   └── prepend.py
│   └── tb_monitor.py
└── torch
    ├── functional.py
    ├── inheritance.py
    ├── models.py
    └── object.py

The following experiments are defined

from xmen.examples import hello_world, HelloWorld  # simple examples
from xmen.examples import AnotherExperiment, MultiParentsExperiment  # with inheritance
from xmen.examples import dcgan # functional dcgan in pytorch
from xmen.examples import Dcgan # object-orientated dcgan in pytorch
from xmen.examples import InheritedMnistGAN, InheritedMnistVae  # inheritance examples

All these experimens can be run from using the xmen commandline tool, eg.:

>> xmen --add xmen.examples Dcgan
>> xmen --list
...
Dcgan: /home/robw/.xmen/experiments/xmen.examples.Dcgan
...
>> xmen Dcgan

Jupyter notebook tutorials can be found at
- xmen/examples/tutorial.ipynb contains a quickstart guide to using xmen
- xmen/examples/class-api.ipynb contains further details about the experiments class api
For command line help run
```
>> xmen --help
```

Dependencies¶

Core Xmen dependencies:
- experiments>=3.6
- ruamel.yaml
- git-experiments
- pandas
Monitor Dependencies:
- pytorch
- tensorboard
Documentation:
- sphinx
- recommonmark
- nbsphinx
- sphinx_glpi_theme

Author, Issues, Contributions¶

Any issues, file an issue or contact me!
Contributions welcome! Just make a pull request :)