Engine configuration utility

[Gamenot]

This adds an engine configuration utility to SMARTS.

• Add configuration utility.
• Add tests.
• Confirm that configuration can be shared between processes.
• Add issue to convert engine constants to use config. Convert engine constants to configuration #1854
• Update changelog.

[Gamenot]

I am somewhat struggling with figuring out a simple way to propagate the configuration.

1. Loop through the configuration and use them to set environment variables. (this should pass to subprocesses and workers but it would also mean only a single engine configuration of SMARTS could ever run on the same thread)
2. Explicitly send over the configuration to workers. This feels like it would be clunky but it would be consistent.
3. Share an instance id with all workers/subprocesses, this allows reference to a shared resource location, all workers/subprocesses intialize using information from that location.
4. Create and pass an environment capture object. When it deserializes it restores the global configuration.
5. Set a series of configuration paths (global user, local user, local directory) that are resolved in order of closeness to the project. Sub-processes will know about it inherently and each lazy loads the configuration independently.
6. Configure the engine through scl.

@Adaickalavan @saulfield Thoughts?

[Gamenot]

Discussion

We had some discussion regarding this issue.

1. Loop through the configuration and use them to set environment variables. (this should pass to subprocesses and workers but it would also mean only a single engine configuration of SMARTS could ever run on the same thread)

This seems viable, as it may allow us to make the engine configuration propagate across machines if a program propagates across workers (using something like ray) as long as the environment configuration resolves before the workers are generated (before something like ray.init().) It looks like this might be viable to implement.

With that said, any user using a cluster management system could just inline the configuration using environment variables.

2. Explicitly send over the configuration to workers. This feels like it would be clunky but it would be consistent.

This option is likely too clunky and there is some question about performance. We can enforce sending over the configuration by accessing workers only through utilities we provide. If a user decides not to use a utility they may get confused as to why the engine configuration does not carry over.

3. Share an instance id with all workers/subprocesses, this allows reference to a shared resource location, all workers/subprocesses intialise using information from that location.

This is probably the most intensive solution, because we would need to provide a central or distributed location for the processes to find the engine settings. We could use an event processing platform like apache kafka or ros, or a cluster management system ray, or a web server. All of these seem like too much work for the immediate need.

4. Create and pass an environment capture object. When it deserialises it restores the global configuration.

This is very similar to option 2, it still requires us to route the user through an engine utility but it ends up being perhaps even more mysterious to end users.

5. Set a series of configuration paths (global user, local user, local directory) that are resolved in order of closeness to the project. Sub-processes will know about it inherently and each process lazy loads the configuration independently.

This seems like the most reasonable option for now. The exact implementation will resolve each of the configuration in this priority:

1. Individual environment variables (e.g. SMARTS_SENSOR_WORKER_COUNT)
2. Local directory engine configuration (./smarts_engine.ini )
3. Local user engine configuration (~/.smarts/smarts_engine.ini ) if local directory configuration is not found.
4. Global engine configuration (/etc/smarts/smarts_engine.ini ) if local configuration is not found.
5. Package default configuration (${PYTHON_ENV}/lib/${PYTHON_VERSION}/site-packages/smarts/core/smarts_engine.ini).

6. Configure the engine through scl.

This is viable regardless of other features. It allows us in the case of scl run to provide a --configuration flag which we could pass in a configuration from a custom location and immediately resolve it before anything else is evaluated.

Direction

We decided to go with option 5 and combine it with option 2. At a later date we may want to bring in option 6.

[Gamenot]

This caused an odd bug. It could not resolve the difference between smarts and smarts.core.smarts. I believe should change smarts.core.smarts to smarts.core.engine.

[Adaickalavan]

Maybe keep files under a given toctree in the same folder?

[Gamenot]

It is hard to find where to put this since api/* is generated dynamically but environment variables and configuration files are related to sim but are relevant to API. Maybe not relevant enough. I am going to move it to resources.

[Gamenot]

I am thinking resources is not quite the right spot for it either so I am moving it to next steps.

[Adaickalavan]

Do check whether the docs build properly without any warnings before merging.

[saulfield]

I think pulling this out as a separate variable would make the expression more readable.