{"id":43571317,"url":"https://github.com/opensha/opensha-fault-sys-tools","last_synced_at":"2026-02-03T22:15:32.415Z","repository":{"id":86485134,"uuid":"399540816","full_name":"opensha/opensha-fault-sys-tools","owner":"opensha","description":"Tools for Fault Systems: building and analyzing Rupture Sets, inverting for Solutions, computing and disaggregating hazard","archived":false,"fork":false,"pushed_at":"2025-02-03T17:39:00.000Z","size":63181,"stargazers_count":3,"open_issues_count":4,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-02-03T18:43:46.654Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opensha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-24T16:52:19.000Z","updated_at":"2025-02-03T17:39:03.000Z","dependencies_parsed_at":"2025-02-03T18:40:23.127Z","dependency_job_id":null,"html_url":"https://github.com/opensha/opensha-fault-sys-tools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/opensha/opensha-fault-sys-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensha%2Fopensha-fault-sys-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensha%2Fopensha-fault-sys-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensha%2Fopensha-fault-sys-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensha%2Fopensha-fault-sys-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opensha","download_url":"https://codeload.github.com/opensha/opensha-fault-sys-tools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensha%2Fopensha-fault-sys-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29059486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T20:13:53.544Z","status":"ssl_error","status_checked_at":"2026-02-03T20:13:40.507Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-03T22:15:32.004Z","updated_at":"2026-02-03T22:15:32.407Z","avatar_url":"https://github.com/opensha.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenSHA Fault System Tools\n\nTools for Fault Systems: building and analyzing [Rupture Sets](doc/glossary.md#rupture-set), inverting for [Solutions](doc/glossary.md#solution), computing and disaggregating hazard.\n\n## Prerequisites\n\n* Java (either JRE or JDK) 11 or above in your path: https://adoptopenjdk.net/\n  * confirm by typing `java -version` in a terminal\n* Unix-like environment: Linux, Mac OS X, Windows Subsystem for Linux (WSL)\n* Basic command line skills (changing directories, defining environmental variables, editing text files, running scripts)\n\n## Setup\n\nFirst, clone this entire repository from GitHub or download it as a zip file. Here's the command to do it in a terminal:\n\n```\ngit clone https://github.com/opensha/opensha-fault-sys-tools.git\n```\n\nFor convenience, you may want to add the `sbin` directory of this repository to your PATH, otherwise you will have to manually type the full path to each scrip that you want to execute. This is outside the scope of this documentation, but for most users adding the following line to `~/.bash_profile` should work:\n\n```\nexport PATH=$PATH:/path/to/opensha-fault-sys-tools/sbin\n```\n\nIf you want to allocate a specific maximum amount of memory to Java when running these tools, you can specify the maximum amount of memory in gigabytes by defining the `OPENSHA_MEM_GB` environmental variable in your `~/.bash_profile` script, e.g., to allocation 12 GB:\n\n```\nexport OPENSHA_MEM_GB=12\n```\n\nIf not specified, up to 80% of total system memory will be allocated.\n\n### Building and Updating OpenSHA\n\nThe first time you attempt to run a script, it will attempt to download/build OpenSHA. The preferred method is to fully check out and build the [OpenSHA source code from GitHub](https://github.com/opensha/opensha). If the tools required to build OpenSHA are not avaiable, then a pre-built version of OpenSHA will be downloaded.\n\nIf you check out the OpenSHA project, updates will be checked when you run Fault System Tools scrips (at most once an hour). If you download a pre-built jar file, updates will be checked weekly. Automatic updates can be fully disabled by setting the environmental variable `OPENSHA_JAR_DISABLE_UPDATE=1`.\n\nYou can force an update at any time by running `fst_force_opensha_update.sh`, which you might want to do now to ensure that you can successfully download/build OpenSHA.\n\nIf you encounter any problems, or wish to switch your build/update method, you can safely delete the 'opensha' subdirectory and try again.\n\n## Calculation Pipeline and Example\n\n### Defining Your Fault Model\n\nThe first step is to define your [fault sections](doc/glossary.md#fault-section) in the [OpenSHA GeoJSON format](https://opensha.org/Geospatial-File-Formats). An example input file, consisting of UCERF3 Southern San Andreas fault sections is [available here](data/u3_ssaf_sects.geojson). You can skip this step if you wish to use an existing UCERF3 Fault Model.\n\n### Building Fault Subsections\n\nThen, you must convert your fault model into smaller, approximately equal length [fault subsections](doc/glossary.md#fault-subsections) with the [Subsection Builder Tool](doc/sub_sect_builder.md). For example, to convert the example S.SAF fault model to subsections:\n\n```\nopensha-fault-sys-tools$ fst_sub_sect_builder.sh --input-file data/u3_ssaf_sects.geojson --output-file u3_ssaf_sub_sects.geojson \nLoaded 10 fault sections.\nBuilt 88 subsections\nWriting sections to u3_ssaf_sub_sects.geojson\n```\n\nOr to use a NSHM23 WUS fault model, in this case FM v3:\n\n```\nopensha-fault-sys-tools$ fst_sub_sect_builder.sh --nshm23 --fault-model WUS_FM_v3 --output-file fm_v3_sub_sects.geojson\nLoaded 1016 fault sections.\nBuilt 5548 subsections\nBuilt 5548 subsections\nWriting sections to /data/kevin/git/opensha-fst-stable/fm_v3_sub_sects.geojson\n```\n\n### Build a Rupture Set\n\nNext, you can build a [Rupture Set](doc/glossary.md#rupture-set) using those subsections with the [Rupture Set Builder Tool](doc/rup_set_builder.md). This tool has a number of options and various [multifault rupture](doc/glossary.md#multifault-rupture) plausibility models, but the basic usage is as follows to build a [simple azimuthal](doc/rup_set_builder.md#simple-azimuthal) rupture set from the S.SAF demo subsections:\n\n```\nopensha-fault-sys-tools$ fst_rup_set_builder.sh --sub-sections data/u3_ssaf_sub_sects.geojson --preset SIMPLE_AZIMUTHAL --scale MEAN_NSHM23 --output-file u3_ssaf_simple_rup_set.zip \nRupture plausibility preset: SIMPLE_AZIMUTHAL\nLoaded 88 sub-sections\nScaling relationship: Mean UCERF3 Scaling Relationship\nInitializing connections w/ 32 threads...\nBuilding ruptures with 32 threads...\nWaiting on 10 cluster build futures\nNew largest rup has 10 subsections with 0 jumps and 0 splays.\n\t67 total unique passing ruptures found, longest has 10 subsections.\tClusters: 10 running (16 futures), 0 completed, 10 total. \tRate: 3,526 rups/s (3,526 rups/s over last 0.0s)\nNew largest rup has 20 subsections with 2 jumps and 0 splays.\n\t272 total unique passing ruptures found, longest has 20 subsections.\tClusters: 10 running (59 futures), 0 completed, 10 total. \tRate: 5,551 rups/s (6,833 rups/s over last 0.0s)\nNew largest rup has 30 subsections with 3 jumps and 0 splays.\n\t806 total unique passing ruptures found, longest has 30 subsections.\tClusters: 10 running (111 futures), 0 completed, 10 total. \tRate: 11,514 rups/s (25,429 rups/s over last 0.0s)\n\t1,000 total unique passing ruptures found, longest has 34 subsections.\tClusters: 10 running (118 futures), 0 completed, 10 total. \tRate: 12,658 rups/s (21,556 rups/s over last 0.0s)\nNew largest rup has 40 subsections with 4 jumps and 0 splays.\n\t1,196 total unique passing ruptures found, longest has 40 subsections.\tClusters: 10 running (122 futures), 0 completed, 10 total. \tRate: 13,907 rups/s (28,000 rups/s over last 0.0s)\nNew largest rup has 50 subsections with 6 jumps and 0 splays.\n\t1,377 total unique passing ruptures found, longest has 50 subsections.\tClusters: 10 running (121 futures), 0 completed, 10 total. \tRate: 15,132 rups/s (36,200 rups/s over last 0.0s)\nNew largest rup has 60 subsections with 7 jumps and 0 splays.\n\t1,598 total unique passing ruptures found, longest has 60 subsections.\tClusters: 10 running (118 futures), 0 completed, 10 total. \tRate: 16,306 rups/s (31,571 rups/s over last 0.0s)\nNew largest rup has 70 subsections with 8 jumps and 0 splays.\n\t1,870 total unique passing ruptures found, longest has 70 subsections.\tClusters: 10 running (107 futures), 0 completed, 10 total. \tRate: 17,642 rups/s (34,000 rups/s over last 0.0s)\n\t2,000 total unique passing ruptures found, longest has 73 subsections.\tClusters: 10 running (101 futures), 0 completed, 10 total. \tRate: 18,182 rups/s (32,500 rups/s over last 0.0s)\nNew largest rup has 80 subsections with 9 jumps and 0 splays.\n\t2,242 total unique passing ruptures found, longest has 80 subsections.\tClusters: 10 running (92 futures), 0 completed, 10 total. \tRate: 18,840 rups/s (26,889 rups/s over last 0.0s)\n\t3,000 total unique passing ruptures found, longest has 85 subsections.\tClusters: 4 running (37 futures), 6 completed, 10 total. \tRate: 18,182 rups/s (16,478 rups/s over last 0.0s)\nMerged in 870 ruptures after processing start cluster 1/10 (id=295): San Andreas (Coachella) rev (870 new, 870 incl. possible duplicates).\n\t3,081 total unique passing ruptures found, longest has 88 subsections.\tClusters: 0 running (0 futures), 10 completed, 10 total. \tRate: 15,719 rups/s (2,613 rups/s over last 0.0s)\nMerged in 1,311 ruptures after processing start cluster 2/10 (id=284): San Andreas (San Gorgonio Pass-Garnet HIll) (441 new, 441 incl. possible duplicates).\nMerged in 1,650 ruptures after processing start cluster 3/10 (id=283): San Andreas (San Bernardino S) (339 new, 339 incl. possible duplicates).\nMerged in 1,905 ruptures after processing start cluster 4/10 (id=282): San Andreas (San Bernardino N) (255 new, 255 incl. possible duplicates).\nMerged in 2,486 ruptures after processing start cluster 5/10 (id=301): San Andreas (Mojave S) (581 new, 581 incl. possible duplicates).\nMerged in 2,616 ruptures after processing start cluster 6/10 (id=286): San Andreas (Mojave N) (130 new, 130 incl. possible duplicates).\nMerged in 2,781 ruptures after processing start cluster 7/10 (id=287): San Andreas (Big Bend) (165 new, 165 incl. possible duplicates).\nMerged in 2,928 ruptures after processing start cluster 8/10 (id=300): San Andreas (Carrizo) rev (147 new, 147 incl. possible duplicates).\nMerged in 3,053 ruptures after processing start cluster 9/10 (id=285): San Andreas (Cholame) rev (125 new, 125 incl. possible duplicates).\nMerged in 3,081 ruptures after processing start cluster 10/10 (id=32): San Andreas (Parkfield) (28 new, 28 incl. possible duplicates).\nBuilt 3,081 ruptures in 0.20 secs = 0.00 mins. Total rate: 15,328 rups/s\n...\n------------ WRITING ARCHIVE ------------\nTemporary archive: /data/kevin/git/opensha-fault-sys-tools/u3_ssaf_simple_rup_set.zip.tmp\nWriting 1 modules\n\tWriting module: Rupture Set\n...\nMoving to /data/kevin/git/opensha-fault-sys-tools/u3_ssaf_simple_rup_set.zip\n---------- END WRITING ARCHIVE ----------\n```\n\n### Build a Rupture Set Report\n\nOnce you have a [Rupture Set](doc/glossary.md#rupture-set), you can build a report with lots of different plots and diagnostic information with the [Rupture Set/Solution Report Builder Tool](doc/report_builder.md). The basic usage is as follows:\n\n```\nopensha-fault-sys-tools$ fst_report_builder.sh --input-file data/u3_ssaf_simple_rup_set.zip --output-dir report\n```\n\nYou can [view an example report here](examples/rup_set_report).\n\n### Invert for a Solution\n\nNow it's time to solve for the rate of each rupture in a Rupture Set with the [Inversion Runner Tool](doc/inversion_runner.md). This is done with the UCERF3 [Simulated Annealing](glossary.md#simulated-annealing) algorithm, and requires at least one data constraint. Various constraint options exist, e.g., MFD and slip rate constraints. Here is an example command to run a quick (2 minute) inversion constrained to match the slip rates on the S.SAF example rupture set:\n\n```\nopensha-fault-sys-tools$ fst_inversion_runner.sh --rupture-set data/u3_ssaf_simple_rup_set.zip --output-file data/u3_ssaf_simple_sol.zip --slip-constraint --completion 2m\n------------ LOADING ARCHIVE ------------\nArchive: data/u3_ssaf_simple_rup_set.zip\n...\n---------- END LOADING ARCHIVE ----------\nGenerating inversion inputs with 3081 ruptures and 1 constraints\nBuilding empty intial solution (all zeroes)\nCalculating constraint row counts\n\tSlipRate: [0..88), 88 rows (took 0 ms)\nTook 7 ms to get row counts\nBuilding A matrix with 88 rows and 3081 columns\nEncoding matrices\n\tEncoding Slip Rate, ineq=false\n\t\tDONE, took 51 ms to encode 95685 values (density: 35.3 %)\nDONE encoding, took 59 ms to encode 95685 values (density: 35.3 %)\nTook 75 ms to generate inputs\nComputing variable perturbation basis:\n\tInferring target GR from slip rates\nInferring target G-R\nPerturbation-basis range: [1.2706653E-6, 0.07460762]\nAnnealing!\nThreaded Simulated Annealing starting with 32 threads, TimeCompletionCriteria(milis: 120000 = 120.0 seconds), SUB: TimeCompletionCriteria(milis: 1000 = 1.0 seconds)\nThreaded total round 1 DONE after 1 secs, 2,512,720 total iterations (2,490,307 /sec).\t2,309/3,081 = 74.94% non-zero rates.\nBest energy after 1,949,173 total perturbations:\n\tTotal:\t1.8534018E-5\tEquality:\t1.8534018E-5\tEntropy:\t0.0\n\tInequality:\t0.0\tSlipRate:\t1.8534018E-5\nThreaded total round 2 DONE after 2 secs, 5,864,866 total iterations (2,909,160 /sec).\t2,345/3,081 = 76.11% non-zero rates.\nBest energy after 4,436,692 total perturbations:\n\tTotal:\t9.632446E-6 (-48.03%)\tEquality:\t9.632446E-6 (-48.03%)\tEntropy:\t0.0 (NaN)\n\tInequality:\t0.0 (NaN)\tSlipRate:\t9.632446E-6 (-48.03%)\nThreaded total round 3 DONE after 3 secs, 9,802,925 total iterations (3,247,077 /sec).\t2,338/3,081 = 75.88% non-zero rates.\nBest energy after 7,440,634 total perturbations:\n\tTotal:\t5.701911E-6 (-40.81%)\tEquality:\t5.701911E-6 (-40.81%)\tEntropy:\t0.0 (NaN)\n\tInequality:\t0.0 (NaN)\tSlipRate:\t5.701911E-6 (-40.81%)\n...\nThreaded total round 120 DONE after 2 mins 0.1 secs, 466,913,800 total iterations (3,887,482 /sec).\t2,324/3,081 = 75.43% non-zero rates.\nBest energy after 245,766,967 total perturbations:\n\tTotal:\t1.1790262E-7 (-0.23%)\tEquality:\t1.1790262E-7 (-0.23%)\tEntropy:\t0.0 (NaN)\n\tInequality:\t0.0 (NaN)\tSlipRate:\t1.1790262E-7 (-0.23%)\nThreaded annealing schedule completed.\nDone with Inversion after 2 mins 0.1 secs.\nRounds: 120\nTotal Iterations: 466913800\nTotal Perturbations: 245766967\nBest energy:\n\tTotal:\t1.1790262E-7\tEquality:\t1.1790262E-7\tEntropy:\t0.0\n\tInequality:\t0.0\tSlipRate:\t1.1790262E-7\nDONE. Building solution...\n```\n\n### Build a Solution Report\n\nOnce you have a [Solution](doc/glossary.md#solution), you can build a report with lots of different plots and diagnostic information with the same [Rupture Set/Solution Report Builder Tool](doc/report_builder.md):\n\n```\nopensha-fault-sys-tools$ fst_report_builder.sh --input-file data/u3_ssaf_simple_solution.zip --output-dir report\n```\n\nYou can [view an example report here](examples/sol_report).\n\n### Compute and Disaggregate Hazard\n\nYou can compute and disaggregate hazard curves and spectra at individual sites with the [Hazard Calculation Tool](doc/hazard_calculator.md). You can also compute hazard maps with the [Hazard Map Calculation Tool](doc/hazard_map_calculator.md).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopensha%2Fopensha-fault-sys-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopensha%2Fopensha-fault-sys-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopensha%2Fopensha-fault-sys-tools/lists"}