pyside_Notebook

Imported from alimuh7x/pyside_Notebook (AGENTS.md). Install upstream with npx skills add alimuh7x/pyside_Notebook. Copyright stays with the author.

AGENTS.md

This file gives repo-wide instructions for Codex and other coding agents working in OPView.

Scope

• These rules apply to the whole project.
• Keep changes focused on the user request. Do not refactor unrelated areas.
• Prefer small, local edits over broad rewrites.

Project Structure

Placement rules:

• New feature code → closest existing module, not a new parallel structure
• Shared pure logic → utils/, not inside a callback or UI builder
• New global constants → config/constants.py
• New tab or dataset definition → config/tabs.py

Coding Rules

• Follow existing OPView patterns before introducing new abstractions.
• Prefer helper functions for non-trivial logic instead of embedding large blocks inside callbacks.
• Keep computation and validation out of UI builders when possible.
• Keep computation and parsing out of callbacks when possible.
• Normalize and validate user input defensively.
• Fail with clear, user-facing error messages instead of silent fallback when correctness matters.
• Use descriptive names and short docstrings for non-obvious helpers.
• Avoid adding dependencies unless they are clearly necessary.
• Do not rename, move, or split files unless the task needs it.
• Do not replace working callback flows with a new framework or pattern.
• Keep comments sparse and useful.
• Preserve backward-compatible behavior unless the user asked for a behavior change.

Dash and UI Rules

• Preserve the current separation between layout code and callback code.
• Match the existing style of Dash components, state dictionaries, and callback helpers.
• Extend existing panel/state structures instead of inventing a second state model.
• Reuse existing styling conventions and constants where possible.
• Do not introduce large visual redesigns unless the task explicitly asks for them.

UI Layout Conventions

Single-field controls (dropdowns, numeric inputs, steppers):

• Label on top, input below — not label-left / value-right.
• One field per block.

Multi-field rows (when one item has several related fields):

• Render as a table-like row: item label first, then related fields as columns with headers.

• Do not split related fields into separate stacked blocks unless explicitly asked.

• Example:

  Component | Type   | Value
  XX        | Stress | [-] 350e6 [+]
  YY        | None   | [-] 0    [+]
  ZZ        | Strain | [-] 0.01 [+]
  

Component Size Standards

All values below come from the existing codebase. Use them for all new UI to keep the interface consistent.

Typography

Shared control height

All interactive controls share one height. Use the CSS variable — never hardcode:

--control-height: 32px

In Python inline styles: "minHeight": "32px" or "height": "32px".

Text inputs

Note: Some feature panels define a local INPUT_STYLE dict with slightly different padding (5px 8px or 6px 10px) and border-radius (6px or 10px). These are inconsistencies in the existing code. For new code, follow the CSS values above (7px radius, 8px 11px padding).

Dropdowns

There are two dropdown sizes used in OPView:

Big dropdown — full-width, standalone field (e.g. trigger type selector):

Small dropdown — compact, inline in a row (e.g. BC type in component rows):

Both sizes share these CSS properties:

Never constrain dropdown menu width. The menu must always be wide enough to show the full option text.

Stepper inputs ([-] / [+] buttons)

Standard buttons (.btn class)

Icon-only buttons (.icon-btn class)

Compact reset button (.reset-btn class)

Panels and containers

Border radius for panels: 0px (flat edges — --radius-lg and --radius-md are both 0px). Panels do not have rounded corners.

Colors and Buttons

• Primary: #001f41 (deep blue — backgrounds, sidebar, button fill)
• Accent / active: #b60021 (red — active states, accents)
• Hover: #95041a (darker red — button hover)
• Accent dark: #9f051d (CSS --accent-dark — deepest red variant)
• Buttons: white text, soft shadow, 8px rounded corners. Do not introduce new colors for buttons.

Icons

All icons live in assets/. Use via CSS background-image or html.Img src='/assets/<file>'.

CSS classes already defined for common icons:

• .opview-image-close-btn — remove/close (uses remove.png)
• .opview-image-add-btn — add/plus (uses plus.png)
• .mechanical-remove-load-btn — remove in mechanical loads panel

Other available icons: bar-chart.png, color-scale.png, download.png, Reset.png, Horizontal.png, Vertical.png, OP_Logo.png, OP_Logo_main.png.

Formula and Data Logic

• Keep formula evaluation safe and explicit.
• Prefer pure helper functions for parsing, math, interpolation, and numeric analysis.
• Keep allowed-symbol or allowed-function lists centralized when working on formula features.
• When adding analysis features, make edge-case handling explicit for invalid, empty, non-finite, or shape-mismatched data.

Testing

Run tests:

source myenv/bin/activate && python -m pytest tests/

• Test new functions in utils/ — that is the only layer that is unit-testable in isolation.
• Use pytest style (assert) for new test files.
• Test edge cases explicitly: empty input, non-finite values, shape mismatches.
• Do not write tests for ui/ or callbacks/ — they require a running Dash server.

Debugging

Every new feature must print enough to verify it is working without opening the GUI.

• Print inputs before the operation: what data came in, what parameters were received.
• Print outputs after the operation: what was computed, what will be returned or stored.
• Print inside every exception path: the error, the input that caused it, and where it happened.
• Use print(f"[debug][<feature-name>] ...") so lines are easy to grep and remove later.

Example:

print(f"[debug][load-summary] inputs: loads={loads}")
result = build_loads_summary(loads)
print(f"[debug][load-summary] result: {result}")

Verification Scripts

For every new feature, write a short standalone script that calls the new code with realistic sample inputs and prints the outputs. Run it and read the output to confirm the feature works — no browser needed.

• Put it in tests/ named verify_<feature>.py.
• Call utils/ functions directly — they have no Dash dependency.
• For callback-level logic, call the underlying method directly on the manager instance with mock inputs.
• After writing the script, run it and read the output. Confirm the results look correct before marking the feature done.
• Never rely on the browser to verify. If it cannot be confirmed from the terminal, the feature is not done.

Example:

# tests/verify_load_summary.py
from utils.mechanical_loads_explorer import build_loads_summary, default_load_structure

load = default_load_structure()
load["bc_types"] = ["Stress", "None", "Strain", "None", "None", "None"]
load["bc_values"] = [350e6, 0.0, 0.01, 0.0, 0.0, 0.0]

print(f"[verify][load-summary] input: {load}")
result = build_loads_summary([load])
print(f"[verify][load-summary] result: {result}")

Run it, read the output, and confirm the result is correct:

source myenv/bin/activate && python tests/verify_load_summary.py