Howso Engine’s python client (
HowsoDirectClient) is designed to work well
without any special configuration. However, there may be circumstances where
additional options may be useful.
How to Create a Configuration File#
The configuration file is a simple YAML text file with the name
and is located in one of these places:
At any valid file path that is stored in an environment variable:
Within your current working directory,
Within your OS-specific “home” directory inside a directory called
On Windows, the “home” directory is stored in the
On MacOS or Linux, the “home” directory is the location stored in the
Within your configured
XDG_DIR_CONFIG_PATHpath (see documentation at freedesktop.org for more information).
If there are multiple
howso.yml files, they will be searched for in the above
order and the first one found will be used.
Structure of the configuration file#
The top-level of the file is the
This is the top-level for Howso Engine options. It has two primary sub-sections:
Set the client to use by it’s dotted Python path. The default value is
This is an advanced user option can be used to define and use other clients which subclass
HowsoDirectClientbut provide alternate behavior. This may be useful for adding additional authentication, for example.
This section is for providing options to Amalgam (
amalgam) and the Howso Engine (
Howso Engine is built upon Amalgam. This section holds options that are specific to the usage of Amalgam and/or the Python client: amalgam-lang. The options here are as follows:
trueUse this option for additional debugging information in the Amalgam trace files.
Set a full path to an Amalgam shared library (DLL, SO, DyLib). This is an advanced setting for developers who compile their own Amalgam shared object binaries.
Target CPU architecture of the amalgam library. This is determined programmatically by default and should only be overridden here by advanced users.
Valid values are:
x86_64- Most Windows, older MacOS, and linux machines
arm64- Modern MacOS and some Linux machines
arm64_8a- Specifically compiled for CPUs compatible with generation 1
aarch64instruction sets such as early Raspberry Pi’s and some early Graviton processors.
Set the desired path where tracefiles should be written. The path must be a valid directory with write permission for the operating user. The default value is the current working directory.
Set the desired file name for the trace files. Default value is
The Amalgam shared libraries are compiled for different modes of operation. Each of the valid values for this option are:
-mtfor Multithreaded operation. This is almost always the best option (and is thus the default on most systems).
-stfor Singlethreaded operation. In rare cases usually involving small Trainee models, this may be the best option.
-openmpfor Multi Processing using the OpenMP library. This option may be useful when latency is paramount.
-pgcfor “Pedantic Garbage Collection”. This is exclusively used by developers in Amalgam debugging scenarios.
Target operating system of the amalgam library. Valid values are:
false(default) - No trace files are written.
true- Use this option to generate tracefiles.
This section is for changing the behavior of the Howso Engine (the Amalgam shared objects).
By default, persisted trainees are stored in the current working directory. Set this option to a valid path with sufficient write permissions to store all persisted trainees if so desired.
Sets the location to look for the Howso Engine (core). This is an advanced setting used by developers.
Sets the filename for the Howso Engine (core). This is an advanced setting used by developers.
Sets the path to look for the howso-template howso-template. This is an advanced setting used by developers.
Example Configuration File#
By default, the Howso Engine will automatically choose sensible default values making a configuration file entirely optional.
This is an example
howso.yml file which overrides a few options for an
early model Raspberry Pi