Toml files

Much of the input in OrcaNet is given as toml files. This page shows examples for the proper format, as well as possible options.

toml files for the Organizer

The orcanet.core.Organizer takes a list_file and a config_file argument, which are the pathes to the respective files.

Here are examples for the proper file formats:

list_file

examples/list.toml

# Defines the input files of the network. In this example, we want to read
# from two different sets of files at the same time.


# Name of this input set. If this is the name of an input layer of the
# model, it will get data from this set. Otherwise, you have to use a
# sample modifier.
[input_A]

# A list of files used during training.
train_files = [
"path/to/train_file_1_input_A.h5",
"path/to/train_file_2_input_A.h5",
]

# A list of files used during valdation. Per default, validation will be
# a part of the training process, so these are required to train a model.
validation_files = [
"path/to/val_file_1_input_A.h5",
]

# An optional list of files to apply trained models on. Instead of giving
# explicit filepaths, one can also give a directory containing all the h5 files:
inference_files = [
"path/to/inference_files_input_A/",
]

# Another input set, e.g. for a second input layer of the model.
# Each input must have the same number of training, validation,
# and/or inference files.
[input_B]
train_files = [
"path/to/train_file_1_input_B.h5",
"path/to/train_file_2_input_B.h5",
]

validation_files = [
"path/to/val_file_1_input_B.h5",
]

inference_files = [
"path/to/inference_files_input_B/",
]

config_file

An important paramter of the config files are the modifiers. Check out Modifiers for more info. You can find various built-in modifiers in orcanet.lib.

examples/config.toml

# Example configuration file for OrcaNet
#
# These options define the various configurable setting of the Organizer.
# Possible options, together with their default values, are listed in the
# doc of orcanet.core.Configuration.
#

[config]
# Batchsize that will be used for the training and validation of the network
batchsize=32
# The learning rate for the training. Here, it is a float, so the
# learning rate will be constantly this value.
learning_rate=0.002
# shuffle the order at which the batches are read from the training files
shuffle_train = true
# Use a special sample modifer that is used for EdgeConv networks.
sample_modifier="GraphEdgeConv"
# 'GraphEdgeConv' also has optional arguments. They can be set e.g. like this:
# sample_modifier={name=”GraphEdgeConv”, with_lightspeed=False}
# the same syntax is also used for label modifiers and dataset modifiers.

toml files for the model builder

Models can be built with OrcaNet using a toml file. The path is handed over as the model_file argument of orcanet.model_builder.ModelBuilder. You can find various built-in layer blocks in orcanet.builder_util.layer_blocks, and some built-in losses in orcanet.lib.losses.

from orcanet.model_builder import ModelBuilder

mb = ModelBuilder(model_file="model.toml")
model = mb.build(organizer)

Here is an example for the proper file format (See Example models for more examples):

examples/model_files/explanation.toml

# Info for building a model with the ModelBuilder. This will produce a
# compiled keras model, with the input shape adapted to the input data given
# to the Organizer.
# Using this class to build a model is not required to use orca_train,
# as any model can be used for that.
#
# The model itself consists of a
# sequence of predefined layer blocks. E.g., the model might consist of convolutional
# layer blocks (convolution, BatchNorm, Activation, MaxPooling and/or Dropout),
# and end with a special last block, e.g. a flatten layer followed by some dense layer blocks,
# which produce a categorical output.
#
# Info for compiling the model is given in the section [compile]. This includes
# the used optimizer (e.g. adam) and the loss functions for each output
# of the network.

# ----------------------------------------------------------------------
[model]
# First, the default values for the layer blocks of the network. If a
# layer block has this parameter, its default is set to the given value
# (kwargs are not resolved).
#
# Type of the block to be added, mandatory for any block
# See orcanet/builder_util/layer_blocks.py for all available blocks, as well
# as their possible arguments.
type = "ConvBlock"
# Specifies the dimension of convolutional blocks, either 1, 2 or 3
conv_dim = 3
# Kernel size of the convolution.
kernel_size = 3
# Add a dropout layer with given rate.
dropout = 0.2
# Pool size of a MaxPooling layer, e.g. (1,1,2)
# pool_sizes = 2
# Activation function that should be used. e.g. 'linear', 'relu'...
activation = 'relu'
# Add a batch normalization layer
batchnorm=true
# l2 regularizer for the weights of the layer.
# kernel_l2_reg = 0.00001


# Then, the blocks in the body section of the resulting network.
# Each dict makes a new block. These will overwrite the default values from above.
blocks = [
    {filters=64},
    {filters=64},
    {filters=64, pool_size=[2, 2, 2]},
    {filters=64},
    {filters=64},
    {filters=64},
    {filters=128, pool_size=[2, 2, 2]},
    {filters=128},
    {filters=128},
    {filters=128, dropout=0.0},
    # This is the last layer of the network. In this case, its a special output block
    # called 'OutputReg. It has 3 dense layer blocks, followed by one dense layer
    # for each output_name.
    # Other (output) blocks are also available, see orcanet/builder_util/layer_blocks.py
    {type="OutputReg", output_name='direction_xyz', output_neurons=3}
]

# ----------------------------------------------------------------------
[compile]
# Options for the compilation of the network
# The optimizer to use for compiling, either 'adam' or 'sgd' for predefined
# orca optimizers, or keras:XXX for keras optimizers
optimizer = "adam"  # or e.g. keras:Adam
# Settings for the optimizer
epsilon=0.1

[compile.losses]
# The loss(es) of the model are listed here.
# Each entry is the name of the respective layer in the model, for which
# this loss is used. The value is a dict with the following keys:
# 'function': loss function to it will use
# 'metrics' : list of metrics to use (optional)
# 'weight' : weight for this loss, useful when using multiple outputs (optional)
direction_xyz = {function="mse", metrics=["mae",], weight=1.0}