Why PolyzyMD uses colored logging

PolyzyMD workflows can produce output from several subsystems in one run: configuration checks, system building, simulation setup, progress reporting, analysis, and export steps. Colored logging gives those messages a visual structure so users and new contributors can quickly tell what kind of work is happening and how urgently they need to respond.

The colors are meant as a readability aid, not as the only source of meaning. The message text and severity level still carry the essential information, so logs remain useful when color is disabled in scripts, continuous integration, or redirected output.

Color Scheme

For routine INFO and DEBUG messages, color mainly answers “which part of PolyzyMD is speaking?” WARNING is always amber/yellow and ERROR is always red, regardless of subsystem, because severity should be visible before module identity.

Output area	What it usually means	Color description
CLI / workflow	Commands, orchestration, and workflow-level decisions	Lavender (bright blue on 16-color terminals)
Building	System preparation and molecular construction	Sage green (bright green)
Simulation	OpenMM run setup, continuation, and recovery messages	Warm peach (bright magenta)
Progress	Runtime progress and signal-handling updates	Steel blue (bright cyan)
Core	Shared PolyzyMD data structures and core services	Parchment (dark yellow)
Data	Bundled data and resource-loading messages	Aqua/mint (dark cyan)
Exporters	Format conversion and export messages	Lilac (dark magenta)
Utilities	General supporting utilities	Neutral gray (white)

The parenthesized colors are the 16-color ANSI fallbacks used on terminals that do not support 256-color or truecolor mode (common on HPC login nodes).

Terminal Support Levels

PolyzyMD adapts its own colorized log output to the terminal it detects:

Level	Detection	What you see
Truecolor (24-bit RGB)	`COLORTERM=truecolor` or `COLORTERM=24bit`	Full RGB tints from the table above
256-color	`TERM` contains `256color`	Closest xterm-256 palette match
16-color (BASIC)	Any other TTY (e.g. `TERM=xterm-16color`)	Bright/dark ANSI color fallbacks
None	Pipe, `TERM=dumb`, `NO_COLOR` set, or `--no-color` flag	No PolyzyMD color codes emitted

Most personal terminals (iTerm2, Windows Terminal, GNOME Terminal) support truecolor. HPC login nodes typically report TERM=xterm-16color and use the 16-color fallbacks.

Disabling Colors

There are three ways to disable PolyzyMD’s color infrastructure:

1. `--no-color` CLI flag

Pass --no-color before the subcommand name:

polyzymd --no-color check-progress -c config.yaml
polyzymd --no-color build -c config.yaml
polyzymd --no-color recover -c config.yaml -r 1

Important: --no-color is a global option and must appear before the subcommand. Placing it after (e.g. polyzymd check-progress --no-color) will produce an error.

The flag disables PolyzyMD-managed color handling. Some command-line messages may still use Click’s own styling behavior; those messages are not governed by PolyzyMD’s subsystem color scheme.

2. `NO_COLOR` environment variable

Set NO_COLOR to any non-empty value. This follows the no-color.org convention and is useful for shell scripts or CI pipelines:

export NO_COLOR=1
polyzymd check-progress -c config.yaml   # no colors

Or for a single command:

NO_COLOR=1 polyzymd check-progress -c config.yaml

3. Automatic detection

Colors are automatically disabled when:

Standard error is not a TTY (e.g. output is piped or redirected)
TERM=dumb

Click-styled messages

A small number of CLI messages use Click’s built-in success or error styling instead of the subsystem colors described above. Treat those messages as plain success/error indicators rather than as signs that a particular PolyzyMD module produced the output. Their behavior follows Click’s terminal handling, not PolyzyMD’s color scheme.

Examples include:

“Build complete!” (green)
“Simulation is complete – nothing to recover.” (green)
Error exit messages (red)

Design rationale for contributors

Colored output should make PolyzyMD easier to scan without making logs harder to capture, search, or compare. Contributors should therefore use the shared logging and color helpers rather than adding ad hoc ANSI escape codes or module-specific terminal checks.

Using the shared helpers keeps behavior consistent across interactive shells, HPC login nodes, redirected output, and automation. It also ensures output respects common controls such as NO_COLOR, pipes, TERM=dumb, and terminal color capability. If a new workflow area needs distinct presentation, prefer extending the shared conventions over creating a separate color system.