Prerequisites#

XNAS does not provide installation via pip currently. To run XNAS, python>=3.7 and pytorch==1.9 are required. Other versions of PyTorch may also work well, but there are potential API differences that can cause warnings to be generated.

We have listed other requirements in requirements.txt file.

Installation#

  1. Clone this repo.

  2. (Optional) Create a virtualenv for this library.

virtualenv venv
  1. Install dependencies.

pip install -r requirements.txt
  1. Set the $PYTHONPATH environment variable.

export PYTHONPATH=$PYTHONPATH:/Path/to/XNAS
  1. Set the visible GPU device for XNAS. Currently XNAS supports single GPU only, but we will provide support for multi-GPUs soon.

export CUDA_VISIBLE_DEVICES=0

Notably, environment variables are valid only for the current terminal. For ease of use, we recommend adding commands within your environment profile (like ~/.bashrc for bash) to automatically configure environment variables after login:

echo "export PYTHONPATH=$PYTHONPATH:/Path/to/XNAS" >> ~/.bashrc

some search spaces or algorithms supported by XNAS require specific APIs provided by NAS benchmarks. Installation and properly setting are required to run these code.

Benchmarks supported by XNAS and their linkes are following.

For detailed instructions to install these benchmarks, please refer to Data Preparation.

Usage#

Before running code in XNAS, please make sure you have followed instructions in Data Preparation in our docs to complete preparing the necessary data.

The main program entries for the search and training process are in the $XNAS/scripts folder. To modify and add NAS code, please place files in this folder.

Configuration Files#

XNAS uses the .yaml file format to organize the configuration files. All configuration files are placed under $XNAS/configs directory. To ensure the uniformity and clarity of files, we strongly recommend using the following naming convention:

Algorithm_Space_Dataset[_Evaluation][_ModifiedParams].yaml

For example, using DARTS algorithm, searching on NASBench201 space and CIFAR-10 dataset, evaluated by NASBench301 while modifying MAX_EPOCH parameter to 75, then the file should be named as this:

darts_nasbench201_cifar10_nasbench301_maxepoch75.yaml

Running Examples#

XNAS reads configuration files from the command line. A simple running example is following:

python scripts/search/DARTS.py --cfg configs/search/darts_darts_cifar10.yaml

The configuration file can be overridden by adding or modifying additional parameters on the command line. For example, run with the modified output directory:

python scripts/search/DARTS.py --cfg configs/search/darts_darts_cifar10.yaml OUT_DIR exp/another_folder

Using .sh files to save commands is very efficient for when you need to run and modify parameters repeatedly. We provide shell scripts under $XNAS/examples folder, together with other potential test code added in the future. It can be simply run with the following command:

./examples/darts_darts_cifar10.sh

A common mistake is forgetting to add run permissions to these files:

chmod +x examples/*/*.sh examples/*/*/*.sh

The script files follow the same naming convention as the configuration file above, and set the output directory to the same folder. You can achieve a continuous search/training process by adding multiple lines of commands to the script file at once.