# duongpm/spso architecture

> Architecture diagram of the GitHub repository duongpm/spso, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/duongpm/spso
- Repository: https://github.com/duongpm/spso

## Overview

1. This repository is a small MATLAB research codebase for Spherical Vector-based Particle Swarm Optimization (SPSO), specialized here for UAV path planning. The architecture is flat: one main driver script, a handful of helper functions, and a terrain image used as the environment input.

2. The top-level orchestration lives in `SPSO_MAIN.m`. It is the entry point the README says to run, and it likely coordinates the full optimization loop: model setup, swarm initialization, cost evaluation, particle updates, and final visualization.

3. The environment/model boundary is handled by `CreateModel.m` together with the input file `ChrismasTerrain.tif`. This is the repository’s main problem-definition layer: it turns the terrain/map data into whatever internal representation the optimizer uses for obstacles, feasible space, and path endpoints.

4. The optimization-state initialization is split out into `CreateRandomSolution.m`. This function is likely responsible for generating initial UAV paths or particle positions in the spherical-vector representation used by SPSO, so the search starts from valid or at least diverse candidate solutions.

5. The objective and constraint logic is concentrated in `MyCost.m`. This is the key evaluation boundary between the swarm and the environment: it scores candidate paths based on path quality and safety, and probably penalizes collisions or terrain violations using data from the model.

6. Several small geometry utilities support that cost evaluation. `DistP2S.m` computes point-to-segment distance, which is a typical primitive for collision checks and clearance calculations, while `SphericalToCart.m` converts spherical vectors to Cartesian coordinates, matching the algorithm’s spherical representation to 3D path geometry.

7. Visualization is separated from optimization. `PlotModel.m` renders the terrain/environment and `PlotSolution.m` renders candidate or final paths over that environment. This keeps the optimization loop independent from plotting, which is useful both for debugging and for reproducing paper figures.

8. The data flow is therefore: terrain image and parameters into `CreateModel.m`, candidate paths from `CreateRandomSolution.m`, repeated fitness evaluation through `MyCost.m` and geometry helpers, iterative swarm updates in `SPSO_MAIN.m`, then final rendering through the plotting functions.

9. The main architectural boundary is between “search logic” and “problem geometry.” The swarm algorithm itself appears to be generic SPSO machinery embedded in the main script, while all UAV/terrain specifics are isolated in the model, cost, and geometry helpers. That makes the code adaptable to other path-planning problems by replacing those problem-specific parts.

10. Tooling/runtime-wise, this is standard MATLAB code, with a note in the README that the Curve Fitting Toolbox may be required depending on MATLAB version. There are no web services, databases, or distributed components; the entire system runs locally as a single MATLAB optimization workflow.

Main entry points: [`SPSO_MAIN.m`](https://github.com/duongpm/spso/blob/main/SPSO_MAIN.m) (SPSO_MAIN), [`MyCost.m`](https://github.com/duongpm/spso/blob/main/MyCost.m) (MyCost), [`CreateModel.m`](https://github.com/duongpm/spso/blob/main/CreateModel.m) (CreateModel), [`PlotModel.m`](https://github.com/duongpm/spso/blob/main/PlotModel.m) (PlotModel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["SPSO workflow"]
  node_main["SPSO_MAIN<br/>driver script<br/>[SPSO_MAIN.m]"]
  node_model["CreateModel<br/>model builder<br/>[CreateModel.m]"]
  node_terrain["Terrain<br/>map data"]
  node_init["CreateRandomSolution<br/>initializer"]
  node_cost["MyCost<br/>objective<br/>[MyCost.m]"]
  node_dist["DistP2S<br/>geometry util<br/>[DistP2S.m]"]
  node_sph["SphericalToCart<br/>geometry util<br/>[SphericalToCart.m]"]
  node_plotm["PlotModel<br/>visualizer<br/>[PlotModel.m]"]
  node_plots["PlotSolution<br/>visualizer<br/>[PlotSolution.m]"]
end

node_main -->|"build model"| node_model
node_model -->|"loads"| node_terrain
node_main -->|"seed swarm"| node_init
node_main -->|"evaluate"| node_cost
node_cost -->|"collision check"| node_dist
node_cost -->|"convert"| node_sph
node_main -->|"render env"| node_plotm
node_main -->|"render path"| node_plots
node_plotm -->|"overlay"| node_terrain
node_plots -->|"overlay"| node_model

click node_main "https://github.com/duongpm/spso/blob/main/SPSO_MAIN.m"
click node_model "https://github.com/duongpm/spso/blob/main/CreateModel.m"
click node_terrain "https://github.com/duongpm/spso/blob/main/ChrismasTerrain.tif"
click node_init "https://github.com/duongpm/spso/blob/main/CreateRandomSolution.m"
click node_cost "https://github.com/duongpm/spso/blob/main/MyCost.m"
click node_dist "https://github.com/duongpm/spso/blob/main/DistP2S.m"
click node_sph "https://github.com/duongpm/spso/blob/main/SphericalToCart.m"
click node_plotm "https://github.com/duongpm/spso/blob/main/PlotModel.m"
click node_plots "https://github.com/duongpm/spso/blob/main/PlotSolution.m"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_model,node_terrain,node_init,node_cost,node_dist,node_sph,node_plotm,node_plots toneBlue
```

## Components

### SPSO workflow

Main optimization flow, problem setup, evaluation, and plotting.

- [SPSO_MAIN](https://github.com/duongpm/spso/blob/main/SPSO_MAIN.m): driver script · Entry point that runs the SPSO-based UAV path planning workflow. · `SPSO_MAIN.m`
- [CreateModel](https://github.com/duongpm/spso/blob/main/CreateModel.m): model builder · Builds the terrain and planning model used by the optimizer. · `CreateModel.m`
- [Terrain](https://github.com/duongpm/spso/blob/main/ChrismasTerrain.tif): map data · Input terrain image used as the environment definition. · `ChrismasTerrain.tif`
- [CreateRandomSolution](https://github.com/duongpm/spso/blob/main/CreateRandomSolution.m): initializer · Generates initial candidate UAV paths or particle states. · `CreateRandomSolution.m`
- [MyCost](https://github.com/duongpm/spso/blob/main/MyCost.m): objective · Evaluates candidate paths and applies safety or feasibility penalties. · `MyCost.m`
- [DistP2S](https://github.com/duongpm/spso/blob/main/DistP2S.m): geometry util · Computes point-to-segment distance for clearance and collision checks. · `DistP2S.m`
- [SphericalToCart](https://github.com/duongpm/spso/blob/main/SphericalToCart.m): geometry util · Converts spherical-vector representation into Cartesian coordinates. · `SphericalToCart.m`
- [PlotModel](https://github.com/duongpm/spso/blob/main/PlotModel.m): visualizer · Renders the terrain and planning environment. · `PlotModel.m`
- [PlotSolution](https://github.com/duongpm/spso/blob/main/PlotSolution.m): visualizer · Renders candidate or final paths over the model. · `PlotSolution.m`

## Connections

- SPSO_MAIN → CreateModel: build model · Initializes the environment and planning bounds before optimization.
- CreateModel → Terrain: loads · Uses the terrain image as the problem input.
- SPSO_MAIN → CreateRandomSolution: seed swarm · Creates the initial population or candidate paths.
- SPSO_MAIN → MyCost: evaluate · Scores particles during the optimization loop.
- MyCost → DistP2S: collision check · Uses segment distance to measure clearance and violations.
- MyCost → SphericalToCart: convert · Maps spherical particle variables into Cartesian path geometry.
- SPSO_MAIN → PlotModel: render env · Produces the environment visualization.
- SPSO_MAIN → PlotSolution: render path · Draws final or intermediate solutions.
- PlotModel → Terrain: overlay · Displays the planning results on top of the terrain map.
- PlotSolution → CreateModel: overlay · Uses the model context for path rendering.
