litenv

litenv

This file will become your README and also the index of your documentation.

Developer Guide

Setup

# create conda environment
$ mamba env create -f env.yml

# update conda environment
$ mamba env update -n litenv --file env.yml
# $ mamba env update -n litenv --file env.mac.yml

Install

pip install -e .

# install from pypi
pip install litenv

nbdev

# activate conda environment
$ conda activate litenv

# make sure the litenv package is installed in development mode
$ pip install -e .

# make changes under nbs/ directory
# ...

# compile to have changes apply to the litenv package
$ nbdev_prepare

Publishing

# publish to pypi
$ nbdev_pypi

# publish to conda
$ nbdev_conda --build_args '-c conda-forge'

Usage

Installation

Install latest from the GitHub repository:

$ pip install git+https://github.com/dsm-72/litenv.git

or from conda

$ conda install -c dsm-72 litenv

or from pypi

$ pip install litenv

Documentation

Documentation can be found hosted on GitHub repository pages. Additionally you can find package manager specific guidelines on conda and pypi respectively.

$ litenv --help

Option	Short Option	Type	Description	Default Value
--name	-n	TEXT	The name of the environment you want to make.	litenv
--file	-f	TEXT	The YAML file to save the environment specifications to.	env.yml
--theme	-t	TEXT	The theme from which to style choices.	blue_night
--specification-file	-s	TEXT	The template file from which to generate choices.	/Users/solst/Projects/litenv/litenv/../data/litenv.yml
--prefix-name	-p		Prefix the environment name to the YAML file.	True
--print-tree	-r		Print the dependency tree.
--conda	-c		Use conda to create the environment. Otherwise, use mamba.
--make-env	-m		Create the environment.
--install-completion			Install completion for the current shell.
--show-completion			Show completion for the current shell, to copy it or customize the installation.
--help			Show this message and exit.

Specification File

Overview

The application specification file is a YAML (YAML Ain’t Markup Language) file that is used to specify various configurations for your application. It defines the requirements and dependencies for your application, allowing you to control the environment in which your application will run. YAML is a human-readable data serialization language that has become a standard for configuration files in software development and deployment.

Structure of the Specification File

python

The python field specifies the required Python version for the application. For example:

python: '>=3.10'

This entry implies that the application requires a Python version of 3.10 or higher.

channels

This field specifies additional channels that might be needed for your application. Channels in Python are paths where packages are stored and can be accessed when needed. For example:

channels:  
  - pytorch
  - conda-forge  

This implies that packages for the application may be sourced from the pytorch or conda-forge channels.

categories

The categories field contains several subfields defining different groups of dependencies for your application.

Each category has a name, a checked field (which may be set to true or false, indicating whether this category should be checked by default or not), a dependencies field (which lists the specific packages required in this category), and optional subcategories.

Each dependency could optionally include attributes such as channel, note, always, pypi_name, cuda_only, version, pip_only and no_arm_support.

For example:

categories:
  utils:
    name: 'Utilities'
    checked: true
    dependencies:
      tqdm:
        always: true
      pyyaml:

In this example, the utils category includes two dependencies, tqdm and pyyaml. The always: true field for tqdm implies that this dependency should always be included when the utils category is checked.

accelerators

The accelerators field specifies the type of hardware accelerator that your application supports. This includes options like ‘mps’, ‘cpu’, or ‘cuda’.

accelerators:
  - mps
  - cpu
  - cuda

This entry implies that the application can use either MPS, CPU, or CUDA as the hardware accelerator.

Creating a Specification File

Creating a specification file involves defining these fields and values to suit your application’s needs. YAML’s indentation-based scoping and simple syntax make this task straightforward. The values to be used depend on the requirements of your specific application.

For Python dependencies, you can often find the exact names and versions you need by using the package management system (like pip or conda) or by referring to the documentation of the library in question. For hardware requirements, you will need to understand your application’s performance needs and the capabilities of the hardware where the application will be run.

Remember to keep the file updated as the requirements of your application evolve. Regular updates will ensure that your application always has the resources it needs to run efficiently.