Optimos V2

The next generation of Optimos. A Resource, Roster and Batching optimizer using Prosimos simulator.

Installation & Basic Usage

Installation

1. Create a fresh Python 3.10 virtual environment, e.g. with conda create --name optimos-python python=3.10
2. Install poetry on your system by following the offical guide. Make sure, poetry is NOT installed in the virtual environment.
3. Activate the environment, e.g. with conda activate optimos-python
4. Run poetry install in the root directory of this repository

Standalone Usage

For now there is no CLI interface for the optimizer, so you have to modify the main.py script to your needs

1. Open main.py in your editor
2. Change the timetable_path, constraints_path and bpmn_path to your needs.
   • If you need a basic set of constraints for your model, you can use the create_constraints.py script
3. Run python main.py to start the optimizer, you will see the output and process in the console
4. If you want to change settings like the number of iterations you can do so in the main.py script as well
5. LEGACY OPTIMOS SUPPORT: If you want optimos_v2 to behave like the old optimos, you can set the optimos_legacy_mode setting to True. This will disable all batching optimizations.

Usage within PIX (docker)

1. Install Docker and Docker-Compose, refer to the official website for installation instructions
2. Clone the pix-portal repository (git clone https://github.com/AutomatedProcessImprovement/pix-portal.git)
3. Checkout the integrate-optimos-v2 branch (git checkout integrate-optimos-v2)
4. Create the following secrets:
   • frontend/pix-web-ui/.session.secret
   • backend/services/api-server/.superuser_email.secret
   • backend/services/api-server/.system_email.secret
   • backend/services/api-server/.superuser_password.secret
   • backend/services/api-server/.key.secret
   • backend/services/api-server/.system_password.secret
   • For local development/testing you can just fill them with example values, e.g. "secret" or "[email protected]".
   • Furthermore create the following files: backend/workers/mail/.secret_gmail_username & backend/workers/mail/.secret_gmail_app_password; Those are the credentials for the gmail account that sends out mails. The Password is a gmail app password, not the actual password. If you don't want to send out mails, you still need to create the files, but can enter any value.
5. Create the following .env files:
   • backend/workers/mail/.env
   • backend/workers/kronos/.env
   • backend/workers/simulation-prosimos/.env
   • backend/workers/bps-discovery-simod/.env
   • backend/workers/optimos/.env
   • backend/services/api-server/.env
   • backend/services/kronos/.env
   • You will find a .env.example file in each of the folders, you can copy those file and rename them to .env
6. Run docker compose up --build in the root directory of the pix-portal repository. You may add the -d flag to run it in detached mode, so you can close the terminal afterwards.
7. This will take some time
8. Open your browser and go to localhost:9999. You can use the credentials from the .superuser_email.secret and .superuser_password.secret files to login.

Usage within PIX (local + debugging)

1. Do all of the Usage within PIX (docker) steps above
2. Stop the docker-based optimos: docker compose stop optimos
3. Modify the backend/workers/optimos/.env file to use the local host instead of the docker container, you can rename .env.example-local to .env for that
4. Create a new Python 3.10 virtual environment (e.g. with conda create --name optimos-python python=3.10)
5. Activate the environment, e.g. with conda activate optimos-python
6. Navigate to the backend/workers/optimos folder in the pix repo
7. Install the dependencies with poetry install
8. Start the optimos worker with python python optimos_worker/main.py
9. Alteratively: Start the optimos worker with the vs code debugger by running the Launch Optimos Worker configuration (most likely you'll need to adjust the python binary used there, you can do that in the .vscode/launch.json file)

Development

Updating the Optimos Version used by PIX

If you have pushed commits to the master, this change needs to be picked up by PIX, to do that do the following:

1. Navigate to the folder backend/workers/optimos in the pix project
2. Update the poetry.lock file: poetry lock
3. Rebuild & restart the optimos container: docker compose up -d --build optimos

Running Tests

To run the tests, run pytest. The tests should also automatically show up in the test explorer of your IDE. (For VSCode, you need to install the Python extension)

Collecting Coverage

To collect coverage, run pytest --cov --cov-report=lcov:lcov.info --cov-report=term. You can display it e.g. with the vscode extension Coverage Gutters.

Docs

While the code should be documented in most places, you can find additional information on e.g. the architecture in the docs folder

Improvements over Legacy Optimos

• Support to optimize Batching
• Fully Typed
• Unit Tested (with ~90% coverage)
• Follows a Action-Store-Reducer pattern, similar to Flux
• Multi-Threaded at important parts, takes cpu core count of host machine into account
• Almost all public interfaces are documented
• Class-Based (Not a huge monolithic script)
• No throwaway file creation; Everything in memory
• Immutable Data Structures, so no change to the timetable is ever unexpected