********************* Runtime Configuration ********************* About ----- palaestrAI has a separate, often optional, configuration that takes care of all options not releated to experiment setup. This includes the results storage (the most commonly changed parameter), verbosity and form of palaestrAI's output, and several options to tweak performance. Quickstart ---------- Most commonly, only the connection to the results storage backend wants to be changed. Per default, sets the store URI to ``sqlite:///palaestrai.db``, i.e., if you run ``palaestrai database-create``, an SQLite database with the filename ``palaestrai.db`` is created in the local directory (and subsequently used by all operations). However, there is usually a central storage server that groups have set up. To use it, create a file named ``palaestrai.conf`` in your local directory from which you will run palaestrAI. Put the following contents in it:: store_uri: postgresql://user:password@host/database Of course, replace ``user``, ``password``, ``host`` and ``database`` with actual values. Setting and Loading the Configuration ------------------------------------- palaestrAI searches its configuration at several places: 1. $XDG_CONFIG_DIRS/palaestrai/runtime-conf.yaml 2. $HOME/.config/palaestrai/runtime-conf.yaml 3. $PWD/palaestrai.conf 4. $PWD/palaestrai-runtime.conf.yaml 5. $PWD/runtime.conf.yaml 6. (Built-in defaults) To determine an option, palaestrAI tries to read all sources, from 6 to 1 in the list, every time updating the current state with the new version. For this reason, palaestrAI has always a working runtime config and you can selectively overwrite whatever options you see fit. As mentioned in the introduction the configuration runs through seperate phases in configuring the RuntimeConfig, each updating the config and taking preference to the former. After loading the built-in default values the RuntimeConfig searches through its standard search paths. These search paths are generated at runtime. To check which paths your RuntimeConfig instance is looking up run the following command: ``palaestrai runtime-config-show-default`` To modify the beavior of the runtime search-path lookup, refer to the ``CONFIG_FILE_PATHS`` list in the *RunetimeConfig class*. The configuration of the RuntimeConfig goes through several phases. First it loads default values which are built into the framework. Then it looks up the standard search paths and then, subsequently, loads any stream, file path or dictionary that is supplied by the user. Note that the RuntimeConfig *always* runs through these phases and each subsequent load updates the config accordingly. That means that the user provided values have preference over the previous configurations. The seperate runtime configuration file is written in the *YAML* format. For an easy example please refer to an existing runtime configuration, for example: ``palaestrai/tests/fixtures/palaestrai-runtime-debug-conf.yaml`` Lets take a look at all available config file options. All examples were taking from the *default configuration*. (Note: you can display the default configuration at any time by running: ``palaestrai runtime-config-show-default`` To display the *currently effective* runtime configuration run: ``palaestrai runtime-config-show-effective``) Configuration Options --------------------- Results Storage ^^^^^^^^^^^^^^^ .. autoproperty:: palaestrai.core.runtime_config._RuntimeConfig.store_uri .. autoproperty:: palaestrai.core.runtime_config._RuntimeConfig.store_buffer_size .. autoproperty:: palaestrai.core.runtime_config._RuntimeConfig.data_path .. autoproperty:: palaestrai.core.runtime_config._RuntimeConfig.checkpoint Checkpointing and restart ^^^^^^^^^^^^^^^^^^^^^^^^^ Portable checkpointing is enabled by default for capable agents. PalaestrAI keeps only the latest complete checkpoint for each run instance and phase, and resume is always explicit. Set ``checkpoint.enabled: false`` to opt out. To restart, use ``checkpoint.resume: latest`` together with the exact ``checkpoint.resume_instance_uid`` and zero-based ``checkpoint.resume_phase``. Checkpoint packages are stored under the resolved absolute ``data_path``. See :doc:`portable-checkpoints` for copy-ready examples, verification steps, and troubleshooting. In-palaestrAI Communication ^^^^^^^^^^^^^^^^^^^^^^^^^^^ palaestrAI is a heavily decentralized piece of software. Modules communicate with each other through a ZeroMQ broker. .. autoproperty:: palaestrai.core.runtime_config._RuntimeConfig.broker_uri .. autoproperty:: palaestrai.core.runtime_config._RuntimeConfig.executor_bus_port .. autoproperty:: palaestrai.core.runtime_config._RuntimeConfig.public_bind .. autoproperty:: palaestrai.core.runtime_config._RuntimeConfig.logger_port Logging, Printing, and Profiling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. autoproperty:: palaestrai.core.runtime_config._RuntimeConfig.logging Performance Tuning ^^^^^^^^^^^^^^^^^^ .. autoproperty:: palaestrai.core.runtime_config._RuntimeConfig.fork_method .. autoproperty:: palaestrai.core.runtime_config._RuntimeConfig.esm_mode .. autoproperty:: palaestrai.core.runtime_config._RuntimeConfig.profile RuntimeConfig as an API ----------------------- When running palaestrAI from the command line interface, the configuration file is usually all that is needed. However, the runtime configuration can also be accessed and changed programmatically throught the :py:func:`palaestrai.core.RuntimeConfig` singleton method. This comes in handy in Jupyter Notebooks. .. note:: palaestrAI loads its runtime configuration automatically. I.e., it is usually not necessary to use the API, not even from Jupyter notebooks. The only difference exists when, e.g., a notebook should be self-contained. The `tutorials `_ make a case in this regard. .. autofunction:: palaestrai.core.RuntimeConfig .. automethod:: palaestrai.core.runtime_config._RuntimeConfig.load .. automethod:: palaestrai.core.runtime_config._RuntimeConfig.reset