andern/pplex

1. What this repo is

- pplex is a Java-based simplex-method teaching tool for linear programs.

- It has two front doors: a desktop app and an applet, both driving the same LP parsing/simulation core.

- The app is centered on showing how an LP dictionary changes step by step, especially for educational/demo cases.

2. Top-level runtime split

- src/controller/Main.java is the main desktop entrypoint.

- src/controller/Applet.java is the browser/applet entrypoint.

- src/controller/GUI.java and src/controller/Console.java suggest two interaction modes:

- a graphical visualization mode,

- a text-command shell mode (also supported by -nogui per README).

3. Core domain model

- src/model/LP.java is the main in-memory representation of a linear program/dictionary.

- This is the central state object that all commands operate on.

- The design implies a mostly stateful flow: parse LP → store in LP → mutate via simplex commands → render current state.

4. Input parsing boundary

- LP files are read from the input/ examples and user-supplied .lps files.

- src/parser/LpFileFormat.g is an ANTLR grammar, so file parsing is generated from a formal LP language definition.

- This separates file syntax from the simplex engine: parsing produces model state, but the simplex logic does not appear to live in the parser.

5. Command-driven simplex engine

- src/controller/shellcommands/ contains the operational commands exposed in the console:

- Read, Phase1, Phase2, Pivot, Undo, Redo

- inspection commands like Show, ShowDual, ShowFeas, ShowOpt, ShowPrimal

- utility/meta commands like FormatCmd, Conditions, Warranty, Exit

- These are the main mutation and inspection boundary around the LP state.

- The architecture is essentially a command dispatcher over a shared LP/session object.

6. Dual representation: computation vs presentation

- src/output/Output.java, OLP.java, and OMatrix.java indicate a formatting layer that converts LP/matrix state into user-visible text or structured output.

- This layer is separate from the model, so the app can present the same LP state in multiple forms:

- primal/dual views,

- feasibility/optimality views,

- matrix/dictionary views.

- That boundary matters for the diagram: the model is not rendered directly; it is adapted through output classes.

7. Visualization subsystem

- The README emphasizes graphical visualization of the simplex dictionary evolution.

- src/controller/VisLP.java likely bridges LP state into a visual form usable by the GUI.

- src/controller/Screenshot.java suggests the GUI can export the current visualization.

- The GUI is likely limited to small-dimensional LPs, consistent with the README note that visual mode is only relevant for two-variable problems.

8. Application flow

- Typical flow is:

- user loads an .lps file with Read

- parser builds an LP

- user runs Phase1, Phase2, or Pivot

- command updates LP state

- GUI/console output reflects the current dictionary, feasibility, or optimality status

- Undo/redo indicate the app keeps a history of prior simplex states or command states.

9. Supporting assets and examples

- input/ contains many sample LPs demonstrating edge cases: cycling, degeneracy, dual-feasible cases, unboundedness, sensitivity, etc.

- doc/teaching_simplex/ contains matching explanatory material and example instances used for instruction.

- These are not runtime subsystems, but they show the app is designed for pedagogy and regression testing of simplex behavior.

10. External libraries and tooling that affect architecture

- Apache Commons Math is used for matrix handling, so the LP/matrix math is not hand-rolled.

- ANTLR is used for parsing.

- lightshell.jar suggests the console shell is built on a shell framework.

- Build is Ant-based (build.xml), producing pplex.jar and an applet target.

11. Deployment/runtime environment

- The app is a pure Java application requiring a JRE/JDK depending on whether it is run or built.

- It supports:

- direct jar execution,

- terminal/no-GUI mode,

- applet deployment via applet.html.

- That makes the architecture portable but still centered on a single JVM codebase.

12. Key architectural boundaries to show in a diagram

- UI boundary: console/GUI/applet entrypoints.

- Parsing boundary: .lps text → ANTLR grammar → LP model.

- Computation boundary: simplex commands mutate LP state.

- Presentation boundary: output/visualization adapters render the current state.

- State/history boundary: undo/redo and phase transitions manage progression through simplex execution.