chefkoch package

Module contents

Introduction

Chefkoch is currently under development. The tool is aiming to help with structuring simulation code. Chefkoch takes a “recipe” and a “flavour” file. The recipe is the general workflow of the simulation. It contains simulation steps and the dependencies between the steps. The flavour file holds possible parameter sets to execute the simulation with. Chefkoch takes care of the execution of the simulations with all parameters and of saving the results consistently.

Read about the general design of chefkoch in our Architecture section. A detailed descriptions of the classes will soon appear in out Classes section.

Submodules

chefkoch.logs module

Settings for logging in whole project. Include with

from logs import *

so that the code is copied into each module and the __name__ variable references the module name. This way, each module has it’s own logger. Using the normal import would set __name__ to “logs” each time. Having seperate loggers for each submodule enables to set for example different logging levels for each module and other explicit settings.

chefkoch.namespace module

The namespace submodule holds key names or otherwise specific names, so that accidental spelling mistakes in the other modules don’t go unnoticed. Changes to keys or specific names can be made by changing one line in the namespace module instead of changing them everywhere, they occure and accidentally forgetting some appearances.

class chefkoch.namespace.NAME_RECIPE

Bases: object

NODE = 'nodes'

chefkoch.recipe module

The recipe file entered by the user declares all the steps taken in the simulation and the dependencies in form of exchanged data between the steps. The Recipe module holds all classes and functions needed to parse a json file into a recipe object and check integrity.

class chefkoch.recipe.FileParamValue(filepath, key)

Bases: object

A single parameter value which is a file, defined by filepath and optional key/passphrase to the file.

__init__(self, filepath, key)

Initialises a new parameter value, that holds a file.

Parameters:

filepath (str):

file path as given in flavour.json

key (str or None):

optional key or passphrase to the file

Raises:

IOError:

In case, the filepath is None or the path does not exist, there is an IOError raised and the functions returns.

file = ''

Saves the filepath, if the given file exists, defaults to “”.

key = ''

Saves optional passphrase to the given file, defaults to “”.

tostring(self)

Returns a printable and formatted string that shows the FileParamValue and its values.

Returns:

String that holds structured information on the FileParamValue

class chefkoch.recipe.Flavour

Bases: dict

The Flavour class extends the dictionary class and holds the parsed flavour file. The flavour file is the collection of all paramters needed for the simulation and all their values the simulation should be executed with. The goal is to find the best parameter combination. Paramter can have a constant value, a list of values or a range. They can also be files.

tostring(self)

Converts the data held inside the flavour object into a string.

Returns:

String that holds structured content of the flavour object

class chefkoch.recipe.Name(name)

Bases: object

Name convention for the name of a node inside the recipe.

__init__(self, name)

Takes a string or unicode and saves it if it is pure ascii.

Parameters:

name (str or unicode):

Name to be checked and saved

Raises:

TypeError:

If name is has another type.

ValueError:

If name contains non-ascii characters.

is_ascii(self, name)

Checks if string consists of only ascii characters.

Parameters:

name (str or unicode):

string

Returns:

True, if name only contains ascii characters.

class chefkoch.recipe.Node(name, inputdict, outputdict, stepsource)

Bases: object

A node encapsules a simulation step within a recipe. The step can be realised by a python file, a sub-recipe or a built-in function. Each node also has a name, a dict of inputs and a dict of outputs. To the inputdict, the key is the same input name that the step takes, the value is where the input comes from. To the outputdict, the key is the name the step uses, the value is the name under which the output is available to other nodes in the recipe (the same name used as value in another inputdict).

__init__(self, name, inputdict, outputdict, stepsource)

Initializes a node of the recipe. A node represents a simulation step.

Parameters:

name (str):

Name of the simulation step.

inputdict (dict):

Dictionary of all inputs needed to execute this step.

outputdict (dict):

Dictionary of all outputs of the simulation step.

stepsource (str):

Information on how to execute this step.

Raises:

TypeError:

If the input or output of a node are not given as a dict.

class chefkoch.recipe.Param(name, entry)

Bases: object

A parameter with all values attached to it.

__init__(self, name, entry)

Creates a new paramter from the JSON data gotten from the flavour file.

Parameters:

name (str):

name as provided as in flavour file

entry (dict):

if the falvour file was a dict, it was flavour[‘name’]

appendEntry(self, entry)

Appends a single entry within the JSON data received from the flavour file.

Parameters:

entry (dict):

file or range or any other value

appendFileParam(self, entry)

Appends a file parameter given in the JSON data to the Param.values list.

Parameters:

entry (dict):

dict with fields type, file and key

Raises:

ValueError:

If there is no ‘file’ field to the entry or if the given file path does not exist

appendValuesFromRange(self, entry)

Appends all values within a range given in the JSON data to Param.values

Parameters:

entry (dict):

dict with fields start, stop and step.

Raises:

KeyError:

If a field of the entry is missing.

tostring(self)

Returns a printable and formatted string that shows the Parameter and its values.

Returns:

String thta holds the content of the parameter

values = []

All possible values of the parameter

class chefkoch.recipe.Recipe(nodelist)

Bases: object

A recipe is the workflow representation of a simulation. It is struktured as a list of nodes of class Node. The nodes already contain information about the data flow and dependencies in the workflow, so there is not explicit representation of edges or dependencies needed.

__init__(self, nodelist)

Initialises a recipe by appending the nodelist to nodes.

Parameters:

nodelist (Node[]):

list of simulation steps as Node[]

findCircles(self)

Makes list of all nodes, which are those who only have flavour parameters as inputs. Then starts depth-first search for every root node. If there is a way back to a previously visited node, there is a warning about a circle.

Raises:

RecursionError:

If there is a circle in the recipe that would cause an endless recursion.

inputIntegrity(self)

Tests if there is exactly one incoming edge to every input. Warns, if there is no incoming edge. Excludes nodes from recipe, that have no incoming edge for a node or have uncomputable inputs because of missing inputs in parent nodes.

Raises:

NameError:

If two or more outputs share the same name.

inputIsValid(self, input)

Checks if a given input name is valid. An input is valid if it can be found either in the flavour file or is a file itself. It is also valid if it is an output name of another node, but this will not be checked.

Parameters:

input (str):

The input that is to be tested

Returns:

True if the input is valid.

nodes = []

recursiveDFS(self, node, nodesOnTheWay)

Recursive Depth First Search finding circles.

Parameters:

node (Node):

The node, the DFS starts in.

nodesOnTheWay (Node[]):

Previously visited nodes. If a node in there can be revisited by going deeper into the graph, there is a circle.

Returns:

returns:

True if there is a circle. False elsewise.

class chefkoch.recipe.StepSource(stepsource)

Bases: object

Specifies the function to be executed inside a node in the recipe.

__init__(self, stepsource)

Tests the step source if it is a recipe, a python executable or a built-in function and initialises it if so.

Parameters:

stepsource (str):

file path to a sub-recipe, a python executable or the name of a built-in function

Raises:

TypeError:

If the string does not match any of the above.

chefkoch.recipe.jsonToFlavour(data)

Turns data loaded from a json file into a flavour object.

Parameters:

data (dict or list):

dict or list depending on json file.

Returns:

flavour - object of class Flavour

rtype:Flavour ..

Raises:

TypeError:

If some data to the flavour file is missing.

Exception:

If some random error should occure.

chefkoch.recipe.jsonToRecipe(data)

Takes a dictionary or list of interpreted JSON and parses it into an object of class Recipe.

Parameters:

data (dict or list):

dict or list depending on the outer structure of JSON file

Returns:

recipe - object of class Recipe

rtype:Recipe ..

Raises:

TypeError:

If data ist not of type dictionary.

Exception:

Error while parsing json data into recipe object.

chefkoch.recipe.openjson(filename)

Opens a JSON file, makes sure it is valid JSON and the file exists at the given path. Loads the whole file at once. File should there- fore not be too big.

Parameters:

filename (str):

file path

Returns:

data - dict or list depending on JSON structure

Raises:

IOError:

If the file path or file name are incorrect.

ValueError:

If the given file is no valid JSON format.

chefkoch.recipe.printRecipe(recipe)

Prints the information held inside a Recipe object to the console.

Parameters:

recipe (Recipe):

object of class Recipe

chefkoch.recipe.readflavour(filename)

Opens a JSON file and parses it into a flavour object. Then outputs the data inside the flavour file.

Parameters:

filename (str):

file path

Returns:

flavour - object of type flavour.

rtype:Flavour ..

chefkoch.recipe.readjson(type, filename)

Wrapper function that calls either readrecipe or readflavour depending on the parameter type.

Parameters:

type (str):

Type of JSON-file that should be converted into a dictionary: {“recipe”, “flavour”}

Returns:

Recipe or Flavour object depending on the type parameter.

Raises:

TypeError:

If type is none of the above.

chefkoch.recipe.readrecipe(filename)

Opens a JSON file and parses it into a recipe object. Then outputs the data inside the recipe.

Parameters:

filename (str):

file path

Returns:

Object of class Recipe

rtype:Recipe ..

chefkoch.version module