



  

Cortex2.0 documentation

 [Cortex2.0](index.html#document-index) 

 latest

 

User Documentation

* [Installation](index.html#document-install)

* [Getting Started](index.html#document-getting_started)

* [cortex](index.html#document-modules)

* [Develop](index.html#document-develop)

* [Custom demos](index.html#document-build)

* [A walkthrough a custom classifier:](index.html#a-walkthrough-a-custom-classifier)

* [Defining losses and results](index.html#defining-losses-and-results)

* [Visualization](index.html#visualization)

* [Putting it together](index.html#putting-it-together)

[Cortex2.0](index.html#document-index)

* [Docs](index.html#document-index) »

* Cortex2.0 documentation

* [Edit on GitHub](https://github.com/rdevon/cortex2.0/blob/master/docs/source/index.rst)

---

Welcome to Cortex2.0[¶](#welcome-to-cortex2-0 "Permalink to this headline")

===========================================================================

Installation[¶](#installation "Permalink to this headline")

-----------------------------------------------------------

### Prerequisites[¶](#prerequisites "Permalink to this headline")

#### Visdom[¶](#visdom "Permalink to this headline")

```

$pip install visdom

```

### From Source[¶](#from-source "Permalink to this headline")

```

$git clone https://github.com/rdevon/cortex2.0.git

$cd cortex2.0

$pip install .

```

Getting Started[¶](#getting-started "Permalink to this headline")

-----------------------------------------------------------------

### Configuration[¶](#configuration "Permalink to this headline")

The first thing to do is to set up the config.yaml. This file is

user-specific (it got tracked at some point, so I need to fix this), and

will tell cortex everything user-specific regarding data locations,

visualation, and outputs.

```

$ rm -rf ~/.cortex.yml

$ cortex setup

```

#### Configuration File Example[¶](#configuration-file-example "Permalink to this headline")

Located at `~/.cortex.yml`

```

torchvision\_data\_path: /data/milatmp1/hjelmdev/data/

data\_paths: {

 Imagenet-12: /data/lisa/data/ImageNet2012\_jpeg, CelebA: /tmp/hjelmdev/CelebA}viz: {

 font: /usr/share/fonts/truetype/liberation/LiberationSerif-Regular.ttf, server: 'http://132.204.26.180'}

out\_path: /data/milatmp1/hjelmdev/outs/

```

These are as follows:

* torchvision\_data\_path: the path to all torchvision-specific

datasets (details can be found in torchvision.datasets)

* data\_paths: user-specified custom datasets. Currently, only support

is for image folders (a la imagenet), but other dataset types (e.g.,

text) are planned in the near-future.

* vis: visdom specific arguments.

* out\_path: Out path for experiment outputs

#### Usage[¶](#usage "Permalink to this headline")

> 

> cortex –help

#### Built-ins[¶](#built-ins "Permalink to this headline")

| setup: | Setup cortex configuration. |

| GAN: | Generative adversarial network. |

| VAE: | Variational autoencoder. |

| AdversarialAutoencoder: |

|  | Adversarial Autoencoder. |

| ALI: | Adversarially learned inference. |

| ImageClassification: |

|  | Basic image classifier. |

| GAN\_MINE: | GAN + MINE. |

#### Options[¶](#options "Permalink to this headline")

| `-h, --help` | show this help message and exit |

| `-o OUT\_PATH, --out\_path OUT\_PATH` |

|  | Output path directory. All model results will go

here. If a new directory, a new one will be

created, as long as parent exists. |

| `-n NAME, --name NAME` |

|  | Name of the experiment. If given, base name of

output directory will be –name. If not given,

name will be the base name of the –out\_path |

| `-r RELOAD, --reload RELOAD` |

|  | Path to model to reload. |

| `-M LOAD\_MODELS, --load\_models LOAD\_MODELS` |

|  | Path to model to reload. Does not load args, info,

etc |

| `-m META, --meta META` |

|  | TODO |

| `-c CONFIG\_FILE, --config\_file CONFIG\_FILE` |

|  | Configuration yaml file. See exps/ for examples |

| `-k, --clean` | Cleans the output directory. This cannot be undone! |

| `-v VERBOSITY, --verbosity VERBOSITY` |

|  | Verbosity of the logging. (0, 1, 2) |

| `-d DEVICE, --device DEVICE` |

|  | TODO |

#### Usage Example[¶](#usage-example "Permalink to this headline")

To run an experiment.

```

cortex GAN --d.source CIFAR10 --d.copy\_to\_local

```

#### Custom models[¶](#custom-models "Permalink to this headline")

It is possible to run experiments with custom models made with Pytorch under the Cortex framework. For doing so, the model has to

be added to the demos folder under the root of the project. You can have a look to the given demo autoencoder and classifier already

implemented. The main difference is that, rather than registering the plugins, the run function of main.py has to be called. For example,

```

if \_\_name\_\_ == '\_\_main\_\_':

classifier = MyClassifier()

run(model=classifier)

```

To run an experiment with a custom model.

```

python my\_model.py --d.source <Dataset> --d.copy\_to\_local

```

cortex[¶](#cortex "Permalink to this headline")

-----------------------------------------------

### cortex package[¶](#cortex-package "Permalink to this headline")

#### Subpackages[¶](#subpackages "Permalink to this headline")

#### Submodules[¶](#submodules "Permalink to this headline")

#### cortex.main module[¶](#cortex-main-module "Permalink to this headline")

#### cortex.plugins module[¶](#cortex-plugins-module "Permalink to this headline")

#### Module contents[¶](#module-contents "Permalink to this headline")

Develop[¶](#develop "Permalink to this headline")

-------------------------------------------------

### Documentation[¶](#documentation "Permalink to this headline")

Make sure that the cortex package is installed and configured. For development purpose, if you are

making changes to documentation, for example modifications inside docstrings or changes in some .rst

files

#### Building Documentation[¶](#building-documentation "Permalink to this headline")

To build the documentation, the docs.py script under the root of the project is facilitating the process.

Before making a Pull Request to the remote repository, you should run the script.

```

$ python docs.py

```

#### Serving Documentation Locally[¶](#serving-documentation-locally "Permalink to this headline")

If you want to have a look at your changes before making a Pull Request on GitHub, it is possible to

serve locally the generated html files.

```

$ cd docs/build/html

$ python -m http.server 8000 --bind 127.0.0.1

```

Custom demos[¶](#custom-demos "Permalink to this headline")

-----------------------------------------------------------

While cortex has built-in functionality, but it is meant to meant to be

used with your own modules. An example of making a model that works with

cortex can be found at:

<https://github.com/rdevon/cortex/blob/master/demos/demo_classifier.py>

and <https://github.com/rdevon/cortex/blob/master/demos/demo_custom_ae.py>

Documentation on the API can be found here:

<https://github.com/rdevon/cortex/blob/master/cortex/plugins.py>

For instance, the demo autoencoder can be used as:

```

python cortex/demos/demo\_custom\_ae.py --help

```

A walkthrough a custom classifier:[¶](#a-walkthrough-a-custom-classifier "Permalink to this headline")

------------------------------------------------------------------------------------------------------

Let’s look a little more closely at the autoencoder demo above to see

what’s going on. cortex relies on using and overriding methods of

plugins classes.

First, let’s look at the methods, `build`, `routine`, and

`visualize`. These are special methods for the plugin that can be

overridden to change the behavior of your model for your needs.

The signature of these functions look like:

```

def build(self, dim\_z=64, dim\_encoder\_out=64):

    ...

def routine(self, inputs, targets, ae\_criterion=F.mse\_loss):

    ...

def visualize(self, inputs, targets):

    ...

```

Each of these functions have arguments and keyword arguments. Note that

the keyword arguments showed up in the help in the above example. This

is part of the functionality of cortex: it manages your hyperparameters

to these functions, organizes them, and provides command line control

automatically. Even the docstrings are used in the command line, so

other users can get the usage docs directly from there.

The arguments are *data*, which are to be manipulated as needed in those

methods. These are for the most part handled automatically, but all of

these methods can be used as normal functions as well.

### Building models[¶](#building-models "Permalink to this headline")

The `build` function takes the hyperparameters and sets networks.

```

class Autoencoder(nn.Module):

    def \_\_init\_\_(self, encoder, decoder):

        super(Autoencoder, self).\_\_init\_\_()

        self.encoder = encoder

        self.decoder = decoder

    def forward(self, x, nonlinearity=None):

        encoded = self.encoder(x)

        decoded = self.decoder(encoded)

        return decoded

...

    def build(self, dim\_z=64, dim\_encoder\_out=64):

        encoder = nn.Sequential(

            nn.Linear(28, 256),

            nn.ReLU(True),

            nn.Linear(256, 28),

            nn.ReLU(True))

        decoder = nn.Sequential(

            nn.Linear(28, 256),

            nn.ReLU(True),

            nn.Linear(256, 28),

            nn.Sigmoid())

        self.nets.ae = Autoencoder(encoder, decoder)

```

All that’s being done here is the hyperparameters are being used to

create an instance of an `nn.Module` subclass, which is being added to

the set of “nets”. Note that they keyword `ae` is very important, as

this is going to be how you retrieve your nets and define their losses

farther down.

Also note that cortex *only* currently supports `nn.Module` subclasses

from Pytorch.

Defining losses and results[¶](#defining-losses-and-results "Permalink to this headline")

-----------------------------------------------------------------------------------------

Adding losses and results from your model is easy, just compute your

graph given you models and data, then add the losses and results by

setting those members:

```

def routine(self, inputs, targets, ae\_criterion=F.mse\_loss):

    encoded = self.nets.ae.encoder(inputs)

    outputs = self.nets.ae.decoder(encoded)

    r\_loss = ae\_criterion(

        outputs, inputs, size\_average=False) / inputs.size(0)

    self.losses.ae = r\_loss

```

Additional results can be added similarly. For instance, in the demo

classifier:

```

def routine(self, inputs, targets, criterion=nn.CrossEntropyLoss()):

    ...

    classifier = self.nets.classifier

    outputs = classifier(inputs)

    predicted = torch.max(F.log\_softmax(outputs, dim=1).data, 1)[1]

    loss = criterion(outputs, targets)

    correct = 100. \* predicted.eq(

        targets.data).cpu().sum() / targets.size(0)

    self.losses.classifier = loss

    self.results.accuracy = correct

```

Visualization[¶](#visualization "Permalink to this headline")

-------------------------------------------------------------

Cortex allows for visualization using visdom, and this can be defined in

a similar way as above:

```

def visualize(self, images, inputs, targets):

    predicted = self.predict(inputs)

    self.add\_image(images.data, labels=(targets.data, predicted.data),

                   name='gt\_pred')

```

See the ModelPlugin API for more more details.

Putting it together[¶](#putting-it-together "Permalink to this headline")

-------------------------------------------------------------------------

Finally, we can specify default arguments:

```

defaults = dict(

    data=dict(

        batch\_size=dict(train=64, test=64), inputs=dict(inputs='images')),

    optimizer=dict(optimizer='Adam', learning\_rate=1e-4),

    train=dict(save\_on\_lowest='losses.ae'))

```

and then add `cortex.main.run` to `\_\_main\_\_`:

```

if \_\_name\_\_ == '\_\_main\_\_':

    autoencoder = AE()

    run(model=autoencoder)

```

And that’s it. cortex also allows for lower-level functions to be

overridden (e.g., train\_step, eval\_step, train\_loop, etc) with more

customizability coming soon. For more examples of usage, see the

built-in models:

<https://github.com/rdevon/cortex/tree/master/cortex/built_ins/models>

