Suggest a coupled tram's usual partner from tramwar.pl

tramwar.pl lists the set every 105Na, 105N2k-family and 123N car runs
in. The second-car sheet now offers that car first, as "usually runs
with it", ahead of the photo, the feed and the ±1 guess. That puts the
right neighbour first, and finds the four sets that aren't neighbours
at all (1381+1341, 1387+1383, 1390+1386, 2064+2037). Issue #84.

Sets do change after a crash or a works visit, so it stays a
suggestion like the others. tramwar.pl is a private site, so the sets
are saved to data/tramwar-sets.json by hand (--tramwar), never fetched
nightly. They ride in fleet.json as "pairs", which older builds ignore.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: TheFilipcom4607

Tabor/Core/Fleet.swift

@@ -89,6 +89,9 @@ public struct VehicleModel: Codable, Hashable, Sendable, Identifiable {
     /// Cars that always run together, e.g. [[1000, 1001]]. In a model that isn't `coupled`,
     /// only these cars are.
     public let sets: [[Int]]
+    /// The sets its cars usually run in, per tramwar.pl, e.g. [[1282, 1281]]. Unlike `sets`
+    /// they can change (after a crash, a works visit), so they're only ever a suggestion.
+    public let pairs: [[Int]]
     /// Its cars with no motor of their own, e.g. the vintage ND #1620: they run hitched behind a
     /// car of a model that `tows`, any one of them, so they're paired across models.
     public let trailers: [Int]
@@ -103,7 +106,7 @@ public struct VehicleModel: Codable, Hashable, Sendable, Identifiable {
                 vintage: Bool = false, onTest: Bool = false, works: Bool = false, runs: String? = nil,
                 trial: String? = nil, runsPl: String? = nil, trialPl: String? = nil, specs: ModelSpecs? = nil,
                 variants: [SpecVariant] = [],
-                liveries: [String: String]? = nil, coupled: Bool = false, sets: [[Int]] = [],
+                liveries: [String: String]? = nil, coupled: Bool = false, sets: [[Int]] = [], pairs: [[Int]] = [],
                 trailers: [Int] = [], tows: Bool = false, formerly: [String] = []) {
         self.id = id
         self.name = name
@@ -128,14 +131,15 @@ public struct VehicleModel: Codable, Hashable, Sendable, Identifiable {
         self.liveries = liveries
         self.coupled = coupled
         self.sets = sets
+        self.pairs = pairs
         self.trailers = trailers
         self.tows = tows
         self.formerly = formerly
     }
 
     private enum CodingKeys: String, CodingKey {
         case id, name, namePl, make, code, kind, operators, fleet, firstYear, lastYear, batches, vintage, onTest, works, runs, trial,
-             runsPl, trialPl, specs, variants, liveries, coupled, sets, trailers, tows, formerly
+             runsPl, trialPl, specs, variants, liveries, coupled, sets, pairs, trailers, tows, formerly
     }
 
     public init(from decoder: Decoder) throws {
@@ -165,6 +169,7 @@ public struct VehicleModel: Codable, Hashable, Sendable, Identifiable {
         liveries = try? c.decodeIfPresent([String: String].self, forKey: .liveries)
         coupled = try c.decodeIfPresent(Bool.self, forKey: .coupled) ?? false
         sets = (try? c.decodeIfPresent([[Int]].self, forKey: .sets)) ?? []
+        pairs = (try? c.decodeIfPresent([[Int]].self, forKey: .pairs)) ?? []
         trailers = (try? c.decodeIfPresent([Int].self, forKey: .trailers)) ?? []
         tows = (try? c.decodeIfPresent(Bool.self, forKey: .tows)) ?? false
         formerly = (try? c.decodeIfPresent([String].self, forKey: .formerly)) ?? []
@@ -189,7 +194,7 @@ public struct VehicleModel: Codable, Hashable, Sendable, Identifiable {
                      lastYear: [lastYear, more.lastYear].compactMap { $0 }.max(),
                      batches: batches + more.batches, vintage: vintage, onTest: onTest, works: works,
                      runs: runs, trial: trial, runsPl: runsPl, trialPl: trialPl, specs: specs, variants: variants,
-                     liveries: liveries, coupled: coupled, sets: sets, trailers: trailers, tows: tows, formerly: formerly)
+                     liveries: liveries, coupled: coupled, sets: sets, pairs: pairs, trailers: trailers, tows: tows, formerly: formerly)
     }
 
     public var yearsDisplay: String? {
@@ -246,6 +251,11 @@ public struct VehicleModel: Codable, Hashable, Sendable, Identifiable {
         sets.first { $0.contains(number) }?.first { $0 != number }
     }
 
+    /// The cars it usually runs with (one, or two in a three-car set), if tramwar.pl knows.
+    public func usualPartners(of number: Int) -> [Int] {
+        pairs.first { $0.contains(number) }?.filter { $0 != number } ?? []
+    }
+
     /// This vehicle's own specs.
     public func specs(of number: Int) -> ModelSpecs? {
         variants.first { $0.numbers.contains(number) }?.specs ?? specs

Tabor/Core/LiveFleet.swift

@@ -283,15 +283,15 @@ public enum CoupledSet {
 
     public struct Suggestion: Sendable, Equatable {
         public enum Source: String, Sendable {
-            case fixed, photo, feed, trailer
+            case fixed, usual, photo, feed, trailer
             case neighbour = "±1"
         }
         public let number: Int
         public let source: Source
     }
 
     /// Up to three numbers for the car coupled to `number`, likeliest first: its fixed partner,
-    /// another car it can run with read in the photo, the feed's lead car, a motor car's
+    /// the set tramwar.pl has it in, another car it can run with read in the photo, the feed's lead car, a motor car's
     /// trailers, then n−1 and n+1. Only cars it can really run with, never the caught number.
     public static func suggestions(for number: Int, model: VehicleModel, photoNumbers: [Int],
                                    nearby: [NearbyVehicle], catalog: FleetCatalog) -> [Suggestion] {
@@ -303,6 +303,7 @@ public enum CoupledSet {
             out.append(Suggestion(number: n, source: source))
         }
         add(model.fixedPartner(of: number), .fixed)
+        model.usualPartners(of: number).forEach { add($0, .usual) }
         photoNumbers.forEach { add($0, .photo) }
         add(partner(of: number, model: model, nearby: nearby, catalog: catalog)?.number, .feed)
         if model.pullsTrailers(number) { catalog.trailers.forEach { add($0, .trailer) } }

Tabor/Resources/Localizable.xcstrings

@@ -4617,6 +4617,17 @@
         }
       }
     },
+    "USUALLY RUNS WITH IT": {
+      "comment": "Second-car suggestion: the set tramwar.pl lists it in",
+      "localizations": {
+        "pl": {
+          "stringUnit": {
+            "state": "translated",
+            "value": "ZWYKLE JEŹDZI Z NIM"
+          }
+        }
+      }
+    },
     "OPEN": {
       "localizations": {
         "pl": {

Tabor/Resources/fleet.json

@@ -120,6 +120,7 @@ struct PartnerSheet: View {
     private func why(_ source: CoupledSet.Suggestion.Source) -> String {
         switch source {
         case .fixed: String(localized: "ALWAYS RUNS WITH IT")
+        case .usual: String(localized: "USUALLY RUNS WITH IT", comment: "Second-car suggestion: the set tramwar.pl lists it in")
         case .photo: String(localized: "ALSO READ IN YOUR PHOTO")
         case .feed: String(localized: "RUNNING RIGHT HERE NOW")
         case .trailer: String(localized: "VINTAGE TRAILER")

Tabor/Screens/PartnerSheet.swift

@@ -1553,15 +1553,31 @@ private let n13 = catalog.model(id: "tram-konstal-13n")!
 }
 
 @Test func partnerSuggestionsInOrder() {
+    // tramwar.pl has 1283 in 1284+1283.
     let s = CoupledSet.suggestions(for: 1283, model: n105, photoNumbers: [1286], nearby: nearby([live(1282, .tram)]), catalog: catalog)
-    #expect(s.map(\.number) == [1286, 1282, 1284])
-    #expect(s.map(\.source) == [.photo, .feed, .neighbour])
+    #expect(s.map(\.number) == [1284, 1286, 1282])
+    #expect(s.map(\.source) == [.usual, .photo, .feed])
     let fixed = CoupledSet.suggestions(for: 1252, model: n105Vintage, photoNumbers: [1000], nearby: nearby([live(1001, .tram)]), catalog: catalog)
     #expect(fixed.map(\.number) == [1251, 1000, 1001])
     #expect(fixed.first?.source == .fixed)
     // The caught number and numbers not in the model are skipped, and three is the most.
     let capped = CoupledSet.suggestions(for: 1283, model: n105, photoNumbers: [1283, 99_999, 1286, 1289, 1290], nearby: [], catalog: catalog)
-    #expect(capped.map(\.number) == [1286, 1289, 1290])
+    #expect(capped.map(\.number) == [1284, 1286, 1289])
+}
+
+@Test func usualPartnerNeedNotBeANeighbour() {
+    // Sets ±1 can't find (tramwar.pl): 1381+1341, 2064+2037.
+    #expect(n105.usualPartners(of: 1341) == [1381])
+    #expect(CoupledSet.suggestions(for: 1381, model: n105, photoNumbers: [], nearby: [], catalog: catalog).map(\.number)
+            == [1341, 1380])
+    let n2k = catalog.model(id: "tram-alstom-konstal-105n2k")!
+    let s = CoupledSet.suggestions(for: 2037, model: n2k, photoNumbers: [], nearby: [], catalog: catalog)
+    #expect(s.first == CoupledSet.Suggestion(number: 2064, source: .usual))
+    // Every running car of a coupled model is in a set; #2046 is parked.
+    for m in catalog.models where m.coupled {
+        let paired = Set(m.pairs.joined())
+        #expect(Set(m.numbers).subtracting(paired).subtracting([2046]).isEmpty, "\(m.id)")
+    }
 }
 
 @Test func partnerSuggestionsStayInTheModel() {

Tests/TaborCoreTests/TaborCoreTests.swift

@@ -0,0 +1 @@
+{"fetched": "2026-10-14", "source": ["https://tramwar.pl/tram105n.html", "https://tramwar.pl/tram105n2k.html"], "sets": [[1252, 1251], [1276, 1275], [1282, 1281], [1284, 1283], [1286, 1285], [1290, 1289], [1294, 1293], [1296, 1295], [1298, 1297], [1300, 1299], [1302, 1301], [1304, 1303], [1306, 1305], [1308, 1307], [1310, 1309], [1312, 1311], [1314, 1313], [1318, 1317], [1320, 1319], [1322, 1321], [1324, 1323], [1326, 1325], [1328, 1327], [1330, 1329], [1332, 1331], [1334, 1333], [1336, 1335], [1338, 1337], [1340, 1339], [1344, 1343], [1346, 1345], [1350, 1349], [1352, 1351], [1354, 1353], [1356, 1355], [1358, 1357], [1360, 1359], [1362, 1361], [1364, 1363], [1366, 1365], [1368, 1367], [1370, 1369], [1372, 1371], [1374, 1373], [1378, 1377], [1380, 1379], [1381, 1341], [1384, 1385], [1387, 1383], [1388, 1389], [1390, 1386], [1392, 1391], [1394, 1393], [1396, 1395], [1398, 1397], [1400, 1399], [1402, 1401], [1404, 1403], [1406, 1405], [1408, 1407], [1410, 1409], [1412, 1411], [1414, 1413], [1416, 1415], [1418, 1417], [1420, 1419], [1422, 1421], [1424, 1423], [1426, 1425], [1428, 1427], [1430, 1429], [1432, 1431], [1434, 1433], [1436, 1435], [1438, 1437], [1440, 1439], [1442, 1441], [1444, 1443], [1446, 1445], [1448, 1447], [1450, 1449], [1452, 1451], [1454, 1453], [1456, 1455], [1458, 1457], [1460, 1459], [1462, 1461], [1464, 1463], [1466, 1465], [1468, 1467], [1470, 1469], [2006, 2007], [2008, 2009], [2010, 2011], [2012, 2013], [2014, 2015], [2016, 2017], [2018, 2019], [2020, 2021], [2022, 2023], [2024, 2025], [2026, 2027], [2028, 2029], [2030, 2031], [2032, 2033], [2034, 2035], [2038, 2039], [2040, 2041], [2042, 2043], [2044, 2045], [2048, 2049], [2050, 2051], [2052, 2053], [2054, 2055], [2056, 2057], [2058, 2059], [2060, 2061], [2062, 2063], [2064, 2037], [2066, 2067], [2068, 2069], [2070, 2071], [2072, 2073], [2074, 2075], [2076, 2077], [2078, 2079], [2080, 2081], [2082, 2083], [2084, 2085], [2086, 2087], [2088, 2089], [2090, 2091], [2092, 2093], [2094, 2095], [2096, 2097], [2098, 2099], [2100, 2101], [2102, 2103], [2104, 2105], [2106, 2107], [2108, 2109], [2110, 2111], [2112, 2113], [2114, 2115], [2116, 2117], [2118, 2119], [2120, 2121], [2122, 2123], [2124, 2125], [2126, 2127], [2128, 2129], [2130, 2131], [2132, 2133], [2134, 2135], [2136, 2137], [2138, 2139], [2140, 2141], [2142, 2143], [2144, 2145], [2146, 2147], [2148, 2149], [2150, 2151], [2152, 2153], [2154, 2155], [2156, 2157], [2158, 2159], [2160, 2161], [2162, 2163], [2164, 2165]]}

data/tramwar-sets.json

@@ -13,6 +13,7 @@
 Usage:  python3 scripts/fetch_fleet.py            # fetch the city's list + build
         python3 scripts/fetch_fleet.py --offline  # rebuild from the saved files
         python3 scripts/fetch_fleet.py --scrape   # re-scrape ZTM's database too (slow)
+        python3 scripts/fetch_fleet.py --tramwar  # refresh the coupled sets from tramwar.pl too
         python3 scripts/fetch_fleet.py --allow-drop  # let model ids disappear (on purpose)
         python3 scripts/fetch_fleet.py --touch    # restamp `fetched` even if nothing changed
 
@@ -33,6 +34,7 @@
 ROOT = Path(__file__).resolve().parent.parent
 RAW = ROOT / "data" / "ztm-vehicles.json"
 CITY = ROOT / "data" / "ztm-pojazdy.json"
+SETS = ROOT / "data" / "tramwar-sets.json"
 OUT = ROOT / "Tabor" / "Resources" / "fleet.json"
 DANE = "https://dane.um.warszawa.pl/api/action/get_ztm_pojazdy"
 BASE = "https://www.ztm.waw.pl/baza-danych-pojazdow/"
@@ -182,6 +184,32 @@ def fetch_city():
     return city
 
 
+# ---------------------------------------------------------------- tramwar.pl's sets
+
+# Which car each coupled tram runs with, per tramwar.pl (a private site, so fetched by hand with
+# --tramwar, never nightly). Sets change rarely, after a crash or a works visit, so the app only
+# suggests them (issue #84).
+TRAMWAR_SETS = ["https://tramwar.pl/tram105n.html", "https://tramwar.pl/tram105n2k.html"]
+
+
+def fetch_sets():
+    sets = []
+    for url in TRAMWAR_SETS:
+        req = urllib.request.Request(url, headers=HEADERS)
+        with urllib.request.urlopen(req, timeout=30) as r:
+            # ISO 8859-2; only the digits matter here.
+            text = re.sub(r"<[^>]+>", " ", r.read().decode("latin-1"))
+        # "1252+1251", or "1392"+1391" with quotes marking the second car to carry a number.
+        found = [[int(n) for n in re.findall(r"\d{3,4}", m)]
+                 for m in re.findall(r"\b\d{3,4}[\"']*(?:\+\d{3,4}[\"']*)+", text)]
+        if len(found) < 15:
+            raise RuntimeError(f"only {len(found)} sets on {url}: has the page changed?")
+        sets += found
+    SETS.write_text(json.dumps({"fetched": date.today().isoformat(), "source": TRAMWAR_SETS,
+                                "sets": sorted(sets)}))
+    print(f"tramwar: {len(sets)} sets")
+
+
 def with_city(vehicles, city, report=True):
     """The scrape plus the vehicles only the city lists. A new number joins the model most
     numbers of its type (idMarki) already belong to; a type nothing known belongs to is
@@ -823,6 +851,15 @@ def build(vehicles, city=None):
             m["trailers"] = trailers
         if m["id"] in TOWING:
             m["tows"] = True
+    # tramwar.pl's sets, on the coupled model that has every car of one. A set across models
+    # (or with a car we don't have) is printed and left out. Emitted as "pairs", which older
+    # app versions ignore.
+    coupled = [m for m in models if m["id"] in COUPLED]
+    for cars in json.loads(SETS.read_text())["sets"] if SETS.exists() else []:
+        if m := next((m for m in coupled if set(cars) <= numbers[m["id"]]), None):
+            m.setdefault("pairs", []).append(cars)
+        elif any(set(cars) & numbers[m["id"]] for m in coupled):
+            print(f"  - tramwar set {'+'.join(map(str, cars))} isn't within one model, left out")
     assert sum(len(m.get("trailers", [])) for m in models) == len(TRAILERS), "a TRAILERS number isn't in the data"
     assert not TOWING - numbers.keys(), f"TOWING ids not in the data any more: {TOWING - numbers.keys()}"
     missing = COUPLED - numbers.keys()
@@ -901,6 +938,8 @@ def build(vehicles, city=None):
 if __name__ == "__main__":
     if "--scrape" in sys.argv:
         scrape()
+    if "--tramwar" in sys.argv:
+        fetch_sets()
     if "--offline" not in sys.argv:
         fetch_city()
     city = load_city()