{"id":18826905,"url":"https://github.com/maswag/falcaun","last_synced_at":"2025-04-14T01:53:00.228Z","repository":{"id":37688915,"uuid":"188825309","full_name":"MasWag/FalCAuN","owner":"MasWag","description":"Falsification of CPS via Automata Learning","archived":false,"fork":false,"pushed_at":"2025-04-04T20:41:48.000Z","size":3278,"stargazers_count":4,"open_issues_count":12,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-14T01:52:54.657Z","etag":null,"topics":["automata-learning","model-based-testing","simulink","testing-tools"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MasWag.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":"2019-05-27T10:49:15.000Z","updated_at":"2025-04-01T06:46:00.000Z","dependencies_parsed_at":"2024-04-04T14:27:17.557Z","dependency_job_id":"50263655-7dcb-44ce-8baa-51afcf36cc96","html_url":"https://github.com/MasWag/FalCAuN","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MasWag%2FFalCAuN","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MasWag%2FFalCAuN/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MasWag%2FFalCAuN/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MasWag%2FFalCAuN/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MasWag","download_url":"https://codeload.github.com/MasWag/FalCAuN/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248809032,"owners_count":21164895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["automata-learning","model-based-testing","simulink","testing-tools"],"created_at":"2024-11-08T01:09:05.958Z","updated_at":"2025-04-14T01:53:00.201Z","avatar_url":"https://github.com/MasWag.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"FalCAuN\n=======\n\n[![JUnit](https://github.com/MasWag/FalCAuN/workflows/JUnit/badge.svg)](https://github.com/MasWag/FalCAuN/actions?query=workflow%3AJUnit)\n[![CircleCI](https://circleci.com/gh/MasWag/FalCAuN/tree/master.svg?style=svg)](https://circleci.com/gh/MasWag/FalCAuN/tree/master)\n[![Javadoc](https://img.shields.io/badge/Javadoc-latest-green)](https://maswag.github.io/FalCAuN/maven-site/latest/apidocs/)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](./LICENSE)\n\nThis is the source code repository for FalCAuN ---  Falsification of CPSs via Automata Learning.\nFalCAuN is a toolkit for testing black-box systems (e.g., cyber-physical systems) based on automata learning and model checking. Currently, systems implemented in Java and Simulink are supported.\n\nInstallation\n------------\n\nFalCAuN is implemented in Java. We suppose FalCAuN works on many UNIX-like operating systems. We tested FalCAuN on macOS 14.4.1 Sonoma, Ubuntu 22.04, and Arch Linux.\n\n### Requirements\n\nThe requirements for the core module of FalCAuN are as follows.\n\n- Java 17\n- Maven\n- LTSMin 3.1.0\n  - This is not officially released yet.\n  - You can download it from [HERE](https://github.com/Meijuh/ltsmin/releases/tag/v3.1.0).\n\nThe matlab module also requires the following.\n\n- MATLAB/Simulink\n  - We tested with MATLAB R2024a but any later version should be fine.\n\n### Installation of the core Module\n\nHere, we provide the instructions to install the core module of FalCAuN.\n\n#### 1. Install the Requirements\n\nYou need to install the requirements above. For example, on Ubuntu, you can install Java 17 and Maven by the following command.\n\n```sh\nsudo apt-get install maven openjdk-17-jdk-headless -y\n```\n\nYou have to manually install LTSMin 3.1.0 and MATLAB/Simulink. For example, you can install LTSMin 3.1.0 with the following commands.\n\n```sh\nwget https://github.com/Meijuh/ltsmin/releases/download/v3.1.0/ltsmin-v3.1.0-linux.tgz -O ltsmin-v3.1.0-linux.tgz\ntar xvf ltsmin-v3.1.0-linux.tgz\nsudo cp -r ./v3.1.0/share /usr/local/share\nsudo cp -r ./v3.1.0/include /usr/local/include\nsudo install ./v3.1.0/bin/* /usr/local/bin\n```\n\nWe provide a script to check if some of the requirements are installed. You can run the script by the following command. Since this script also checks the dependencies of the matlab module, you can ignore the error messages related to the matlab module.\n\n```sh\n./utils/check_env.sh\n```\n\n#### 2. Build and Install FalCAuN\n\nYou can build and install FalCAuN using Maven. An example of installing the core module and the top-level module is as follows.\n\n```sh\nmvn install --also-make --projects core\n```\n\n### Installation of the matlab Module\n\nHere, we provide the instructions to install the matlab module.\n\n#### 1. Install the Requirements\n\nYou need to install MATLAB/Simulink manually. Please follow the instructions on the official website of Mathworks.\n\n#### 2. Setup the environment variable\n\nWe assume that the environment variable `MATLAB_HOME` shows where MATLAB is installed. An example is as follows.\n\n```sh\nexport MATLAB_HOME=\u003cpath/to/matlab/home\u003e\n## Example:\n# export MATLAB_HOME=/usr/local/MATLAB/R2024a/\n```\n\n#### 3. Build and Install FalCAuN\n\nYou can build and install FalCAuN using Maven. You have to execute `mvn clean` to set up the Java API of MATLAB. An example to install the matlab module, as well as the others, is as follows.\n\n```sh\nmvn clean --projects matlab\nmvn install\n```\n\n### Installation of LTSMin 3.1.0 on macOS with ARM Processors\n\nFalCAuN works on macOS with ARM Processors, but the setup of LTSMin is a bit tricky because it only supports x86\\_64. One can still run LTSMin using Rosetta and libtool for x86\\_64.\n\n1. Set up Rosetta on the macOS\n2. Install Homebrew for intel processors with `arch -x86_64 /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)\"`\n3. Install `libtool` for x86_64 with `/usr/local/bin/brew install libtool`\n\n### Notes\n\n- For the matlab module, the unit test on `mvn install` is disabled by default because it takes much time. If you want, you can run it by `mvn test -DskipTests=false`.\n    - Perhaps you have to explicitly specify `JAVA_HOME`, for example, `JAVA_HOME=$(/usr/libexec/java_home -v 17) mvn test -DskipTests=False`.\n    - Also, the automatic transmission model requires parameters defined in an example by Mathworks. To load it, you probably need to set up the example by Mathworks and the path beforehand. \n        - The example by Mathworks can be opened with `openExample('simulink_automotive/ModelingAnAutomaticTransmissionControllerExample')`\n        - See `./src/test/resources/MATLAB/initAT.m` for an example to set the path.\n\nExamples\n--------\n\nWe provide some examples in the `./example/kotlin` directory. The following is the list of examples. To run the examples, you need to install [kscript](https://github.com/kscripting/kscript) because the examples are written in Kotlin script.\n\nThe following example does not require MATLAB/Simulink.\n\n- `./example/kotlin/mealy.main.kts`\n  - This example is a simple example to test some properties of a Mealy machine, which is handled as black-box.\n\nThe following examples require MATLAB/Simulink.\n\n- `./example/kotlin/ATS1.main.kts`\n- `./example/kotlin/ATS2.kts`\n- `./example/kotlin/ATS6a.main.kts`\n- `./example/kotlin/ATS6b.main.kts`\n- `./example/kotlin/pacemaker.main.kts`\n\nSTL\n---\n\nThe definition of signal temporal logic in FalCAuN is as follows.\n\n```\nexpr : atomic\n     | expr \u0026\u0026 expr\n     | expr || expr\n     | expr -\u003e expr\n     | ! expr\n     | GLOBALLY expr\n     | GLOBALLY _ INTERVAL expr\n     | EVENTUALLY expr\n     | EVENTUALLY _ INTERVAL expr\n     | X expr\n     | expr U expr\n     | expr U _ INTERVAL expr\n     | ( expr )\n\natomic : signal(NATURAL) == value\n       | signal(NATURAL) \u003c value\n       | signal(NATURAL) \u003e value\n       | signal(NATURAL) != value\n       | input(NATURAL) == value\n       | input(NATURAL) \u003c value\n       | input(NATURAL) \u003e value\n       | input(NATURAL) != value\n       | output(NATURAL) == value\n       | output(NATURAL) \u003c value\n       | output(NATURAL) \u003e value\n       | output(NATURAL) != value\n\nvalue : -? NATURAL | -? FLOAT\n\nGLOBALLY : '[]' | 'alw' | 'G'\n\nEVENTUALLY : '\u003c\u003e' | 'ev' | 'F'\n\nINTERVAL : [ NATURAL , NATURAL ]\n```\n\nJavadoc\n--------\n\nThe source code is partially commented on using the Javadoc syntax. The document is hosted on [GitHub Pages](https://maswag.github.io/FalCAuN/maven-site/latest/apidocs/).\nIf you want to generate the document locally under `./target/site/apidocs/` by `mvn javadoc:aggregate.`\n\nObsolete CLI interface\n-----------------------\n\nAfter FalCAuN 1.0, FalCAuN is mainly intended to be used as a library called from a program written in some JVM language, such as Kotlin. The CLI interface is still available for backward compatibility, but it is not actively maintained.\n\nTo execute FalCAuN via the CLI interface, you can use the helper shell script `falcaun` in the root directory of the repository. The script is a wrapper of the CLI interface of FalCAuN. The script is written in POSIX sh and should work on most UNIX-like operating systems.\nAn example of usage is as follows. This takes at least a few minutes for MATLAB to start up and another few minutes to falsify all the STL formulas in `./example/AT_M4.stl`. Please be patient!!\n\n```sh\n./falcaun --stl-file=./example/AT_M4.stl --output-mapper=./example/AT_M4.omap.tsv --input-mapper=./example/AT.imap.tsv --equiv=GA --step-time=1.0 --signal-length=30  --init='cd ./example; initAT' --max-test=50000 --param-names=\"throttle brake\" --ga-crossover-prob=0.5 --ga-mutation-prob=0.01 --population-size=150 --ga-selection-kind=Tournament\n```\n\nYou can also install this script as follows.\n\n```sh\nsudo install falcaun /usr/local/bin\n```\n\n### Usage of the CLI interface\n\n#### Symopsis\n\n     ./falcaun [OPTIONS] --stl=[STLFormula] --input-mapper=[InputMapperFile] --output-mapper=[OutputMapperFile] --equiv=[HC|random|WP|SA|GA]\n\n#### General Options\n\n**-h**, **--help** Print a help message. \u003cbr /\u003e\n**-v**, **--verbose** It outputs extra information, mainly for debugging. \u003cbr /\u003e\n**-V**, **--version** Print the version \u003cbr /\u003e\n**-t** *timeout*, **--timeout** *timeout* Set timeout [seconds]\n**-f** *file*, **--stl-file** *file* Read a STL formula from *file*. \u003cbr /\u003e\n**-e** *STLFormula*, **--stl** *STLFormula* Specify *STLFormula* by signal temporal logic. \u003cbr /\u003e\n**-I** *file*, **--input-mapper** *file* Read the input mapper configuration from *file*. \u003cbr /\u003e\n**-O** *file*, **--output-mapper** *file* Read the output mapper configuration from *file*. \u003cbr /\u003e\n**-S** *file*, **--signal-mapper** *file* Read the signal mapper from *file*. \u003cbr /\u003e\n**-E** *algorithm*, **--equiv** *algorithm* Specify the equivalence testing algorithm. See below for the detail. \u003cbr /\u003e\n**-o** *file*, **--output-dot** *file* Write the learned Mealy machine to *file* in DOT format. \u003cbr /\u003e\n**--output-etf** *file* Write the learned Mealy machine to *file* in ETF format. \u003cbr /\u003e\n**-s** *step-time*, **--step-time** *step-time* Specify the step time of the sampling. \u003cbr /\u003e\n**-l** *length*, **--signal-length** *length* Specify the length of the sampled signals. \u003cbr /\u003e\n**-i** *script*, **--init** *script* The initial script of MATLAB \u003cbr /\u003e\n**-p** *param1 param2 ... paramN*, **--param-names** *param1 param2 ... paramN* The parameter names of the Simulink\nmodel \u003cbr /\u003e\n**-M** *test-size*, **--max-test** *test-size* The maximum test size \u003cbr /\u003e\n**--disable-adaptive-stl** Disable the adaptive STL updater in [Shijubo+, RV'21]\n\n#### Options Specific to the Equivalence Testing\n\nWhen you use GA, SA, or WP for the equivalence testing, you have to specify the following options in addition.\n\n#### GA (Genetic Algorithm)\n\n**--population-size** *size* The size of the population \u003cbr /\u003e\n**--ga-crossover-prob** *prob* The crossover probability (should be between 0 and 1) \u003cbr /\u003e\n**--ga-mutation-prob** *prob* The mutation probability (should be between 0 and 1) \u003cbr /\u003e\n**--ga-selection-kind** *[bestsolution|tournament]* The selection in the genetic algorithm. Either best solution selection or binary tournament.\n\n#### SA (Simulated Annealing)\n\n**--sa-alpha** *alpha* The alpha parameter for simulated annealing (should be between 0 and 1)\n\n##### WP (Wp-method)\n\n**--wp-max-depth** *depth* The maximum depth in the Wp-method\n\n### File format of the mapper\n\nBoth input and output mappers are specified by TSV files.\n\n#### Input mapper\n\nInput mapper specifies the possible input values of each signal (e.g., break and throttle). Each signal can take different number of inputs i.e., N0 and N1 can be different.\n\n```\n\u003cvalue 1 of signal(0)\u003e\t\u003cvalue 2 of signal(0)\u003e\t...\t\u003cvalue N0 of signal(0)\u003e\n\u003cvalue 1 of signal(1)\u003e\t\u003cvalue 2 of signal(1)\u003e\t...\t\u003cvalue N1 of signal(1)\u003e\n...\t\t\t\t\t\t\n```\n\nFor example, the following shows that:\n\n- the domain of `signal(0)` is 10 and 40; and\n- the domain of `signal(1)` is 0, 50, and 100.\n\n```\n10\t40\n0\t50\t100\n```\n\n#### Output mapper\n\nOutput mapper specifies how we map the real-valued signal to an atomic proposition. Precisely, we split the vector space R^n by grids. Each grid is one atomic proposition. Since the maximum upper bound is the positive infinity, the last cell for each signal must be `inf`.\n\n```\n\u003cupper bound of signal(0) for AP0-1\u003e\t\u003cupper bound of signal(0) for AP0-2\u003e\t...\t\u003cupper bound of signal(0) for AP0-N0\u003e\n\u003cupper bound of signal(0) for AP1-1\u003e\t\u003cupper bound of signal(1) for AP1-2\u003e\t...\t\u003cupper bound of signal(1) for AP1-N1\u003e\n...\n```\nFor example, the following output mapper stands for as follows.\n\n- For `signal(0)`:\n  - `AP0-1` holds if `signal(0)` \u003c= 10;\n  - `AP0-2` holds if 10 \u003c `signal(0)` \u003c= 40; and\n  - `AP0-3` holds if 40 \u003c `signal(0)`.\n- For `signal(1)`:\n  - `AP1-1` holds if `signal(1)` \u003c= 0;\n  - `AP1-2` holds if 0 \u003c `signal(1)` \u003c= 50;\n  - `AP1-3` holds if 50 \u003c `signal(1)` \u003c= 100; and\n  - `AP1-4` holds if 100 \u003c `signal(1)`.\n- For `signal(2)`, `AP2-1` always holds.\n\n```\n10\t40\tinf\n0\t50\t100\tinf\ninf\n```\n\nContributors\n------------\n\n- Masaki Waga: 2019--\n- Junya Shijubo: 2021--2022\n\n\nFAQ\n---\n\n- FalCAuN says ``infinite robustness''. What should I do?\n    - It can be because the generated signal is too short for the temporal formula. Please make \"--signal-length\" as\n      long as the time window of the STL formulas.\n\n\nReferences\n----------\n\n- [Shijubo+, RV'21] Efficient Black-Box Checking via Model Checking with Strengthened Specifications. Junya Shijubo, Masaki Waga, and Kohei Suenaga\n- [Waga, HSCC'20] Falsification of cyber-physical systems with robustness-guided black-box checking. Masaki Waga\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaswag%2Ffalcaun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaswag%2Ffalcaun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaswag%2Ffalcaun/lists"}