# `utopya` module

The `utopya` module is the top level access to the various UTOPyA classes and routines.

## Purpose

UTOPyA is a set of Python scripts and classes to faciliate configuration, building, and running model simulations.

Here we provide a short overview of the available Python classes; details can be found in the class documentations. See the section on modules and classes for the hierarchy of the classes and the modules in which they are implemented.

- The `utopya_runscript` is provided to quickly setup a run script that accepts some common arguments.

- The `utopya_jobscript` module defines a number of classes that can be used to create and run job scripts. Classes are present to run job scripts in foreground, background, or submit them to a batch job system.

- The `utopya_jobtree` module defines classes that could be used to create a sequence of jobs. Each job in the sequence automically starts the next one, and eventually terminates the sequence on certain conditions.

- The `utopya_build` module defines classes to copy and configure source files and build executables.

- The `utopya_install` module defines a class that could be used to copy files or series of files to the local file system. This is typcially used to install input data. The reverse operation is to archive output; for this, the module `utopya_archive` is available.

All the above classes are build on one of the following base classes:

- The `UtopyaBase` class is the ancestor of all UTOPyA classes.

- The `UtopyaRc` class is an extension of the base class holding configurations settings read from a ‘rcfile’.

In addition, the `utopya_tools` module provides a number of general purpose tools used by the other modules.

## Utopya modules

Actual implementations can be found in submodules:

- `utopya_base` module
- `UtopyaBase`
- `utopya_rc` module
- `UtopyaRc`
- `utopya_jobscript` module
- `UtopyaJobScript`
- `UtopyaJobScriptForeground`
- `UtopyaJobScriptRedirect`
- `UtopyaJobScriptBackground`
- `UtopyaJobScriptBatch`
- `UtopyaJobScriptBatchTest`
- `UtopyaJobScriptBatchLSF`
- `UtopyaJobScriptBatchPBS`
- `UtopyaJobScriptBatchSGE`
- `UtopyaJobScriptBatchSlurm`
- `UtopyaJobScriptBatchLoadLeveler`
- `utopya_jobtree` module
- `UtopyaJobStep`
- `UtopyaJobTree`
- `UtopyaJobParallel`
- `UtopyaJobParallelWait`
- `UtopyaJobIteration`
- `UtopyaJobIteration_CheckFile`
- `UtopyaJobTask`
- `UtopyaJobTaskSubmit`
- `UtopyaJobTaskRun`
- `UtopyaJobTaskWait`
- `UtopyaRcCommand`
- `UtopyaJobTreeTiming`
- `utopya_runscript` module
- `UtopyaRunScript`
- `UtopyaRunScriptRc`
- `utopya_tools` module
- `ImportClass()`
- `CreateFilePath()`
- `CreateDirs()`
- `WriteTextFile()`
- `UpdateTextFile()`
- `ReadNcVariable()`
- `GetValuesFunction()`
- `Call`
- `CallingError`
- `StatusError`
- `utopya_build` module
- `UtopyaBuild`
- `UtopyaCopy`
- `UtopyaConfigure`
- `UtopyaCompilerSettings`
- `UtopyaCompilerSettingsFortran`
- `UtopyaCompilerSettingsF2Py`
- `UtopyaLibSettings`
- `UtopyaDependencies`
- `UtopyaMake`
- `utopya_post` module
- `UtopyaHtmlFile`
- `UtopyaPlot`
- `UtopyaBarPlot`
- `utopya_index` module
- `Indexer`
- `GetIndexPart()`
- `IndexPart`
- `IndexSections`
- `IndexList`
- `IndexTableRow`
- `IndexTableCol`
- `IndexColumn`
- `IndexText`
- `IndexImg`
- `IndexTxtFile`

## Utopya classes

The UTOPyA python classes could be imported from the utopya module, and are defined according to the following hierchy:

- `UtopyaBase`

  - `UtopyaRc`

    - `UtopyaJobStep`

      - `UtopyaJobTree`

        - `UtopyaJobIteration`

    - `UtopyaCopy`

    - `UtopyaConfigure`

    - `UtopyaCompilerSettings`

      - `UtopyaCompilerSettingsFortran`

      - `UtopyaCompilerSettingsF2py`

    - `UtopyaLibSettings`

    - `UtopyaDependencies`

    - `UtopyaMake`

    - `Indexer`

    - `IndexPart`

      - `IndexSections`

      - `IndexList`

      - `IndexTableRow`

      - `IndexTableCol`

      - `IndexText`

      - `IndexImg`

  - `UtopyaRunScript`

  - `UtopyaJobScript`

    - `UtopyaJobScriptForeground`

    - `UtopyaJobScriptRedirect`

    - `UtopyaJobScriptBackground`

    - `UtopyaJobScriptBatch`

      - `UtopyaJobScriptBatchTest`

      - `UtopyaJobScriptBatchLSF`

      - `UtopyaJobScriptBatchSlurm`

      - `UtopyaJobScriptBatchPBS`

      - `UtopyaJobScriptBatchLoadLeveler`