This document provides a high-level overview of SSPlot, a Java-based plotting utility and numerical simulator for studying dynamical systems. It describes the application's purpose, execution modes, architectural structure, and primary code components.
For detailed information about specific subsystems, see:
Sources: README.md1-81 pom.xml15-24
SSPlot is a cross-platform application that enables users to:
The application supports 2D and 3D plotting with customizable appearance, interactive zoom/pan/rotation, and multiple visualization modes (normal, overlay, animate).
Sources: README.md1-24 pom.xml15-24 io.github.babaissarkar.ssplot.metainfo.xml20-30
SSPlot operates in two primary modes:
Launched via MainFrame.main(), provides a complete graphical interface with windowed frames for equation input, plotting, and data management. The GUI uses Swing components enhanced with a custom reactive UI framework.
Launched via SSPlotCLI.main() with command-line arguments, enables batch processing and REPL (Read-Eval-Print Loop) for mathematical expressions without graphical overhead.
Sources: README.md32-33 pom.xml127-128 pom.xml152
Sources: README.md32-33 pom.xml127 pom.xml152
SSPlot is organized into four primary architectural layers:
Swing-based GUI components with custom reactive controls (StateVar, UIInput, UIButton) that provide fluent APIs and automatic state synchronization. The MainFrame class orchestrates internal frames (JInternalFrame instances) within a JDesktopPane.
Coordinates user workflows between input, computation, and visualization. Key classes include SystemInputFrame for equation definition and DataView for tabular data management.
Mathematical processing components:
Parser / ParserManager: Expression parsing using JavaCC-generated TreeParser or JSR-223 ScriptParserSolver: Implements RK4 integration, map iteration, direction fields, cobweb diagramsEquationSystem: Immutable problem specification built via fluent Builder patternRendering (Canvas, Plotter), file I/O (NumParse), logging (InfoLogger, StatLogger), and 3D projection (Project2D).
Sources: README.md1-81 pom.xml1-206
Sources: README.md1-81 pom.xml1-206
The following diagram shows how data flows from user input through processing to visualization:
Sources: README.md1-81
mvnw, mvnw.cmd)com.formdev:flatlaf:3.2 - Modern Swing look-and-feelcom.formdev:flatlaf-intellij-themes:3.2 - Additional themesorg.junit.jupiter:junit-jupiter:5.10.0 - Testing framework (test scope)javacc-maven-plugin:3.1.1 - Generates parser from grammar filemaven-shade-plugin:3.5.0 - Creates uber JAR with dependenciesjpackage-maven-plugin:1.5.0 - Produces native installers (MSI, DEB)maven-checkstyle-plugin:3.2.0 - Code quality checksmaven-surefire-plugin:3.1.2 - Test executionSources: pom.xml42-73 pom.xml91-203 README.md8-9 README.md41-44
SSPlot is distributed in multiple formats for cross-platform compatibility:
| Format | Platform | Description | Source |
|---|---|---|---|
| JAR | Cross-platform | Self-contained executable JAR with all dependencies | mvnw package |
| MSI | Windows | Native installer with bundled JRE, creates Start Menu entry | mvnw jpackage:jpackage@win |
| DEB | Debian/Ubuntu | Native package for APT-based systems | mvnw jpackage:jpackage@linux |
| AppImage | Linux | Portable executable with bundled JRE, no installation required | generate_all.sh |
| Snap | Linux | Sandboxed universal package via Snap Store | snapcraft.yaml |
| Flatpak | Linux | Sandboxed universal package via Flathub | Flathub repository |
The build system uses GitHub Actions workflows for continuous integration, producing artifacts for all supported platforms.
Sources: README.md11-33 pom.xml140-178 generate_all.sh1-14 snapcraft.yaml1-48 .github/workflows/snap-build.yml1-28
SSPlot supports two mathematical expression parsing strategies:
TreeParser generated from src/main/java/com/babai/ssplot/math/system/parser/internal/SSMathParser.jj using JavaCC. Evaluates expressions by building an abstract syntax tree (TreeNode hierarchy).
ScriptParser wraps JSR-223 compatible engines (Jython, Rhino) loaded from classpath. Selected via SSPLOT_ENGINE environment variable. The ParserManager singleton determines which parser to instantiate based on availability.
Sources: README.md56-75 pom.xml92-109
The repository follows Maven's standard directory layout:
ssplot/
├── src/main/
│ ├── java/com/babai/ssplot/
│ │ ├── cli/ # Command-line interface
│ │ ├── data/ # File I/O (NumParse)
│ │ ├── math/system/ # Equation solving, parsing
│ │ ├── plotter/ # Rendering (Plotter, Canvas, PlotData)
│ │ ├── ui/ # GUI components (MainFrame, frames)
│ │ └── ui/controls/ # Custom reactive UI controls
│ └── resources/
│ ├── ssplot.png # Application icon
│ ├── font/ # Bundled Cantarell font
│ └── filtered/ # Processed resources
├── packaging/ # AppImage build scripts
├── pom.xml # Maven build configuration
├── snapcraft.yaml # Snap package definition
├── generate_all.sh # Multi-format build script
└── .github/workflows/ # CI/CD automation
Sources: README.md1-81 pom.xml1-206 generate_all.sh1-14
SSPlot employs several design patterns:
EquationSystem.Builder for fluent problem specificationDUI class provides centralized UI component creationStateVar<T> maintains observer callbacks for reactive updatesParserManager provides single parser instanceParser interface with TreeParser and ScriptParser implementationsPlotData), views (PlotView, Canvas), and controllers (Plotter, SystemInputFrame)Sources: README.md1-81 pom.xml1-206
SSPlot is licensed under LGPL 2.1 or later. The bundled Cantarell font is licensed under the SIL Open Font License 1.1.
Sources: README.md77-79 pom.xml35-40
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.