Running the COMPAS Docker image¶
COMPAS can be configured as usual via command line arguments passed to the COMPAS executable or via a runSubmit.py
file in the
Docker
environment.
via runSubmit.py¶
To run COMPAS via a runSubmit.py
file, type:
docker run \
--rm \
-it \
-v $(pwd)/compas-input:/app/COMPAS/config \
-v $(pwd)/compas-logs:/app/COMPAS/logs \
-v $(pwd)/runSubmit.py:/app/starts/runSubmit.py \
-v $(pwd)/compasConfigDefault.yaml:/app/COMPAS/compasConfigDefault.yaml \
-e COMPAS_EXECUTABLE_PATH=/app/COMPAS/bin/COMPAS \
-e COMPAS_INPUT_DIR_PATH=/app/COMPAS/config \
-e COMPAS_LOGS_OUTPUT_DIR_PATH=/app/COMPAS/logs \
teamcompas/compas \
python3 /app/starts/runSubmit.py
NOTE: if you decide to execute using runSubmit.py
, you will need a compasConfigDefault.yaml
file in the same directory.
This file can be found in the same directory as the runSubmit.py
, and contains the default COMPAS choices for stellar and
binary physics. These choices can be changed by modifying the options available in the compasConfigDefault.yaml
file.
NOTE2: when running on a MacOS with the M1 chip that runs on amd64 architecture you likely need to add the line --platform linux/amd64 to the note above
Breaking down this command:
docker run
creates a container.
--rm
destroy the container once it finishes running the command[1].
-it
short for [-i and -t] - provides an interactive terminal[2].
-v <path-on-host>:<path-in-container>
mount <path-on-host>
to <path-in-container>
[3].
This time we not only want to read the COMPAS input files (i.e. grid file and/or logfile-definitions file) on the
host from the container, and get the output from COMPAS in the container onto the host machine, we also want to
supply a runSubmit.py
to the container from the host machine.
-e VAR_NAME=value
set the environment variable VAR_VAME
to value[4].
teamcompas/compas
the image to run.
python3 /app/starts/runSubmit.py
the command to run when the container starts.
via the command line¶
To run the COMPAS executable from the command line (i.e. without runSubmit.py
), type:
docker run \
--rm \
-it \
-v $(pwd)/compas-input:/app/COMPAS/config \
-v $(pwd)/compas-logs:/app/COMPAS/logs \
teamcompas/compas \
bin/COMPAS \
--number-of-systems=5 \
--output-path=/app/COMPAS/logs
Breaking down this command:
docker run
creates a container[5].
--rm
destroy the container once it finishes running the command[1].
-it
short for [-i and -t] - provides an interactive terminal[2].
-v <path-on-host>:<path-in-container>
mount <path-on-host>
to <path-in-container>
[3].
- In this instance, make it so
$(pwd)/compas-input on my machine is the same as /app/COMPAS/config inside the container.
$(pwd)/compas-logs on my machine is the same as /app/COMPAS/logs inside the container.
teamcompas/compas
the image to run.
bin/COMPAS
the command to run when the container starts.
--number-of-systems=5
the flag to set the number of binaries.
--output-path=/app/COMPAS/logs
forces logs to go to the directory that is mapped to the host machine.
Environment variables¶
Three new environment variables are used in runSubmit.py
. These environment variables are used primarily in the Docker
environment, and are non-breaking changes (i.e. benign to other environments).
COMPAS_EXECUTABLE_PATH
specifies where runSubmit.py
looks for the COMPAS executable. This override exists purely for
ease-of-use from the command line.
COMPAS_LOGS_OUTPUT_DIR_PATH specifies where COMPAS output log files are created. The override exists because the mounted directory (option -v) is created before COMPAS runs. COMPAS sees that the directory where it's supposed to put logs already exists, so it creates a different (i.e. non-mapped) directory for the output log files.
COMPAS_INPUT_DIR_PATH specifies where input files (such as the grid
file, or logfile-definitions
file are located.
Detached mode¶
The docker run
examples above use the -it
option.
To run multiple instances of COMPAS, an alternative is to use detached mode (-d)[6]. In detached mode, containers are run in
the background of the current shell - they do not receive input or display output.
Typing:
docker run --rm -d -v $(pwd)/compas-logs/run_0:/app/COMPAS/logs -v $(pwd)/runSubmitMMsolar_01.py:/app/starts/runSubmit.py teamcompas/compas python3 /app/starts/runSubmit.py &
docker run --rm -d -v $(pwd)/compas-logs/run_1:/app/COMPAS/logs -v $(pwd)/runSubmitMMsolar_02.py:/app/starts/runSubmit.py teamcompas/compas python3 /app/starts/runSubmit.py &
docker run --rm -d -v $(pwd)/compas-logs/run_2:/app/COMPAS/logs -v $(pwd)/runSubmitMMsolar_03.py:/app/starts/runSubmit.py teamcompas/compas python3 /app/starts/runSubmit.py &
docker run --rm -d -v $(pwd)/compas-logs/run_3:/app/COMPAS/logs -v $(pwd)/runSubmitMMsolar_04.py:/app/starts/runSubmit.py teamcompas/compas python3 /app/starts/runSubmit.py &
runs 4 separate instances of COMPAS, each with its own runSubmit.py
file and logging directory, and all local console output suppressed.
To see the console output of detached containers to check progress, first type:
docker ps
to get the container id of interest, then type:
docker logs container_id
Footnotes