{"id":21761755,"url":"https://github.com/bigraph-toolkit-suite/bigraphs.bigraph-framework","last_synced_at":"2025-10-18T21:49:59.677Z","repository":{"id":204300226,"uuid":"711513470","full_name":"bigraph-toolkit-suite/bigraphs.bigraph-framework","owner":"bigraph-toolkit-suite","description":"A framework written in Java for the creation and simulation of bigraphs.","archived":false,"fork":false,"pushed_at":"2025-02-21T08:25:25.000Z","size":57962,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-21T09:27:11.879Z","etag":null,"topics":["bigraphs","builder","converter","framework","java","model-checking","simulation","visualization"],"latest_commit_sha":null,"homepage":"https://bigraphs.org/products/bigraph-framework/","language":"Java","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/bigraph-toolkit-suite.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":"2023-10-29T13:58:25.000Z","updated_at":"2025-01-28T02:52:28.000Z","dependencies_parsed_at":"2024-12-11T16:24:57.967Z","dependency_job_id":"e2c95972-d5ed-4ebc-ab6e-456b798ae175","html_url":"https://github.com/bigraph-toolkit-suite/bigraphs.bigraph-framework","commit_stats":null,"previous_names":["bigraph-toolkit-suite/bigraphs.bigraph-framework"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigraph-toolkit-suite%2Fbigraphs.bigraph-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigraph-toolkit-suite%2Fbigraphs.bigraph-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigraph-toolkit-suite%2Fbigraphs.bigraph-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigraph-toolkit-suite%2Fbigraphs.bigraph-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bigraph-toolkit-suite","download_url":"https://codeload.github.com/bigraph-toolkit-suite/bigraphs.bigraph-framework/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244739947,"owners_count":20501990,"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":["bigraphs","builder","converter","framework","java","model-checking","simulation","visualization"],"created_at":"2024-11-26T12:09:38.430Z","updated_at":"2025-10-18T21:49:59.659Z","avatar_url":"https://github.com/bigraph-toolkit-suite.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"etc/assets/bigraph-framework-logo.png\" style=\"zoom:67%;\" /\u003e\n\n\u003e Latest Version: **2.3.0**\n\n[![HiRSE Code Promo Badge](https://img.shields.io/badge/Promo-8db427?style=plastic\u0026label=HiRSE\u0026labelColor=005aa0\u0026link=https%3A%2F%2Fgo.fzj.de%2FCodePromo)](https://go.fzj.de/CodePromo)\n\n- User Manual: https://bigraphs.org/software/bigraph-framework/docs/\n\n- JavaDoc: https://bigraphs.org/software/bigraph-framework/apidocs/\n\n---\n\n# Bigraph Framework\n\n**What is Bigraph Framework?**\n\nBigraph Framework is a framework\nwritten in Java for the creation and simulation of bigraphs\nto foster the experimental evaluation of the bigraph theory in\nreal-world applications.\n\nThe goal of this framework is to facilitate the implementation of context-aware, agent-based systems, and reactive systems in general.\nIt provides means for model-driven software development based on the bigraph theory.\nThe high-level Java API eases the programming of bigraphical systems for real-world application.\n\n**Features**\n\n- Modelling and Storage\n    - Dynamic creation of bigraphs at design time and runtime based on the [Bigraph Ecore Metamodel (BEM)](https://github.com/bigraph-toolkit-suite/bigraphs.bigraph-ecore-metamodel)\n    - Read and write instance models and metamodels of a bigraph from and to the file system\n- Visualization\n    - Graphical export via GraphViz/DOT, PNG, Visualization of Compiler Graphs (VCG) format via yComp\n    - Interactive visualization via GraphStream\n- Bigraphical Reactive Systems (BRS): Simulate the evolution of bigraphs by reaction rules\n    - Bigraph matching and rewriting via [jLibBig](https://bigraphs.github.io/jlibbig/)\n    - Generation of a labeled transition system (LTS)\n    - Simulation and Model Checking (BFS, Random)\n    - Predicate checking\n    - Specify order of reaction rules via priorities\n    - Tracking rules (trace node identities across reactions)\n    - Conditional rules (not yet integrated in model checking procedure but available for custom usage)\n- Model Importer/Exporter\n    - Export a bigraph to common graph formats, e.g., DOT, GraphML, GXL, VCG\n    - Export to formats of other bigraph tools: BigMC, BigraphER, BigRed, jLibBig, ...\n- Attributed Bigraphs\n    - Add arbitrary attributes to nodes\n    - Attributes are preserved when doing rewriting (this requires tracking maps)\n\n**Requirements**\n- Java \u003e=17 (JDK)\n- Maven / Gradle\n- Graphviz for the visualization module\n  - Ubuntu 20.04/22.04: `sudo apt install graphviz`\n\n## Getting Started\n\nHere is a quick teaser of creating a pure concrete bigraph using _Bigraph Framework_ in Java.\n\n### Lean Bigraph API\n\nThe lean bigraph API allows fast bigraph creation and composition.\n\nTo following usage assumes the import statement `import static org.bigraphs.framework.core.factory.BigraphFactory.*`.\n\n```java\n// Create the signature\nDynamicSignature signature = pureSignatureBuilder()\n                // Straightforward:\n                .add(\"A\", 0)\n                .add(\"C\", 1)\n                // More verbose:\n                .newControl()\n                  .identifier(StringTypedName.of(\"User\"))\n                  .arity(FiniteOrdinal.ofInteger(1))\n                  .status(ControlStatus.ATOMIC).assign()\n                .create();\n\n// Create two bigraphs\nPureBigraph bigraph1 = pureBuilder(signature)\n        .root()\n        .child(\"A\").child(\"C\")\n        .create();\n\nPureBigraph bigraph2 = pureBuilder(signature)\n        // \"User\" is the control, \"alice\" is an outer name     \n        .root().child(\"User\", \"alice\").site()\n        .create();\n\n// compose two bigraphs\nBigraphComposite composite = ops(bigraph2).compose(bigraph1);\n```\n\n### Other APIs\n\n#### **Bigraph Builder: Connecting nodes by links**\n\nThe bigraph builder provides more utility methods helping to build more\ncomplex structures easily.\n\nThe following one shows, how to create nodes, and at the same time connecting them all with an edge:\n\n```java\nPureBigraphBuilder\u003cDynamicSignature\u003e builder = pureBuilder(signature);\nbuilder.root().connectByEdge(\n    \"Job\",\n            \"Job\",\n    signature.getControlByName(\"Job\")\n);\n```\n\nNow, we want to connect nodes located at different \"places\". Therefore, we\nlink them through an inner name, and\nafter, close the link to automatically transform it to an edge:\n```java\n// First, create an inner name\nBigraphEntity.InnerName tmp_link = builder.createInnerName(\"link\");\n\n// Create two nodes within different hierarchies\nbuilder.root().child(\"Printer\").linkInner(tmp_link);\nbuilder.root().child(\"Computer\").linkInner(tmp_link);\n\n// Finally, close the inner name. This will leave the edge intact.\nbuilder.closeInnerName(tmp_link);\n```\n\n#### **Exporting the Ecore metamodel and instance model**\n\n```java\nPureBigraph bigraph = ...;\n// Writes a bigraph to the filesystem\n        BigraphFileModelManagement.Store.exportAsMetaModel(bigraph, new FileOutputStream(\"./meta-model.ecore\"));\n        BigraphFileModelManagement.Store.exportAsInstanceModel(bigraph, new FileOutputStream(\"./instance-model.xmi\"));\n// prints bigraph on the console\n        BigraphFileModelManagement.Store.exportAsInstanceModel(bigraph, System.out);\n```\n\nSee the reference and documentation for a more comprehensive overview.\n\n#### **Bigraph Composition**\n\nTo get the composition and tensor product of two bigraphs:\n```java\nPureBigraph G = ...;\nPureBigraph F = ...;\nPureBigraph H = ...;\nBigraphComposite\u003cDynamicSignature\u003e composite = ops(G);\n\nBigraphComposite\u003cDynamicSignature\u003e result = composite.compose(F);\ncomposite.juxtapose(F);\ncomposite.juxtapose(F).parallelProduct(H);\n```\n\n## Project Configuration\n\n\u003e See also \u003ca href=\"#Building-the-Framework-from-Source\"\u003eBuilding from Source\u003c/a\u003e if you want to build the source by yourself and host them in your Maven local repository.\n\n### Maven\n\n```xml\n\u003cdependencies\u003e\n  \u003c!-- the core module --\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003eorg.bigraphs.framework\u003c/groupId\u003e\n    \u003cartifactId\u003ebigraph-core\u003c/artifactId\u003e\n    \u003cversion\u003e2.3.0\u003c/version\u003e\n  \u003c/dependency\u003e\n  \u003c!-- the rewriting module --\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003eorg.bigraphs.framework\u003c/groupId\u003e\n    \u003cartifactId\u003ebigraph-simulation\u003c/artifactId\u003e\n    \u003cversion\u003e2.3.0\u003c/version\u003e\n  \u003c/dependency\u003e\n  \u003c!-- the visualization module --\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003eorg.bigraphs.framework\u003c/groupId\u003e\n    \u003cartifactId\u003ebigraph-visualization\u003c/artifactId\u003e\n    \u003cversion\u003e2.3.0\u003c/version\u003e\n  \u003c/dependency\u003e\n  \u003c!-- the converter module --\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003eorg.bigraphs.framework\u003c/groupId\u003e\n    \u003cartifactId\u003ebigraph-converter\u003c/artifactId\u003e\n    \u003cversion\u003e2.3.0\u003c/version\u003e\n  \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n### Gradle\n\n```groovy\ncompile \"org.bigraphs.framework:bigraph-core:2.3.0\"\ncompile \"org.bigraphs.framework:bigraph-simulation:2.3.0\"\ncompile \"org.bigraphs.framework:bigraph-visualization:2.3.0\"\ncompile \"org.bigraphs.framework:bigraph-converter:2.3.0\"\n```\n\n### Logging\n\nThis framework employs SLF4J as a facade for the log4j logging framework.\n\nDepending on your project setup, you may need to include the following libraries in your `pom.xml` :\n\n```xml\n\u003c!-- For Spring --\u003e\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\n  \u003cartifactId\u003espring-boot-starter\u003c/artifactId\u003e\n  \u003cexclusions\u003e\n    \u003cexclusion\u003e\n      \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\n      \u003cartifactId\u003espring-boot-starter-logging\u003c/artifactId\u003e\n    \u003c/exclusion\u003e\n  \u003c/exclusions\u003e\n\u003c/dependency\u003e\n\u003cdependency\u003e\n\u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\n\u003cartifactId\u003espring-boot-starter-log4j2\u003c/artifactId\u003e\n\u003c/dependency\u003e\n\n        \u003c!-- For a bare Maven project --\u003e\n\u003cdependency\u003e\n\u003cgroupId\u003eorg.slf4j\u003c/groupId\u003e\n\u003cartifactId\u003eslf4j-log4j12\u003c/artifactId\u003e\n\u003cversion\u003e1.7.30\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nThe example above shows how to use log4j2 in your project as the underlying logging framework.\n\n## Module Details\n\nA brief description of each module's purpose is given below.\n\n### bigraph-core\n\n- Provides builders, factories and interfaces to create concrete bigraphs and elementary bigraphs.\n- Concrete Bigraphs and their metamodel (with the signature only) can be written/loaded to/from the file system.\n\n### bigraph-simulation\n\n- Simulate bigraphs by creating bigraphical reactive systems, reaction rules and agents.\n- Check a system according to some specification by defining various types of predicates.\n\n### bigraph-visualization\n\n- Provides simple means to export bigraphs and transition systems as graphic files.\n- Currently, DOT is used in combination with GraphViz. Bigraphs can be exported as `*.png` and `*.jpg`.\n\n**Requirements**\n\nIn order to use the functionality of the visualization module, the following tools must be installed on the machine:\n- Graphviz: `apt install -y graphviz`\n\n### bigraph-converter\n\n- Provides several ways to convert bigraphs into other representations.\n- For example, bigraphs to GraphML format, BigraphER's specification language or BigMC's term language.\n\n### A User-Friendly API for the Bigraph Ecore Metamodel (BEM)\n\n- Internally, bigraphs are described by a metamodel based on Ecore.\n  The project can be found in this [GitHub repository](https://github.com/bigraph-toolkit-suite/bigraphs.bigraph-ecore-metamodel).\n- To create concrete bigraphs, a signature must be provided.\n  To do so, this metamodel is extended when creating a new bigraphical signature which is then called \"metamodel over a signature\" of an abstract bigraph (described by the Ecore model).\n  We say that the signature is mapped to the metamodel over a signature.\n  From that, multiple instance models can be created where the instance bigraph relates to the signature _S_, thus, corresponds to the metamodel over the signature _S_.\n- Extending the metamodel with a signature by hand is time-consuming\n  especially when many models are created. The framework allows to create\n  bigraphs dynamically at runtime by letting the user providing a description\n  of the signature. The metamodel over a signature is kept in memory and\n  instances can be created from it. As a result, the bigraph metamodel must\n  not be touched manually. Both the metamodel over a signature and the\n  instance model can be stored on the filesystem.\n- That very metamodel serves only as a data model for the *Bigraph Framework*\n  which provides additional functionality and a user-friendly API for the\n  creation and simulation of bigraphical reactive systems. Furthermore, we\n  achieve Separation of concerns: The metamodel itself is implementation-agnostic.\n  The Bigraph Framework adds specific behavior superimposed upon this meta\n  model. Meaning, the implementation-specific details are kept out from the metamodel.\n\n## Development\n\n### Build Configuration\n\nIt is not necessary to build from source to use *Bigraph Framework* but if you want to try out the latest version, the project can be easily built with the [maven wrapper](https://maven.apache.org/tools/wrapper/) or the regular `mvn` command.\n\n\u003e **Note:** The required version of Maven is \u003e= 3.8.3 and Java JDK \u003e=17.\n\nThe recommendation here is to build it with the regular `mvn` command.\n\nOn Debian systems you can install it by issuing the following command:\n```shell\n$ sudo apt install maven\n```\n\nSee [Installation](https://maven.apache.org/install.html) for other options.\n\n### Building the Framework from Source\n\n**Initialize**\n\nThe following command has to be run once:\n```shell\n$ mvn initialize\n```\nIt installs some dependencies located in the `./etc/libs/` folder of this project in your local Maven repository, which is usually located at `~/.m2/`.\nThese are required for the development.\n\n\u003e When using IntelliJ IDEA, make sure to \"Sync All Maven Projects\" again to resolve any project errors that may appear due to missing dependencies on first startup.\n\n**Build/Install**\n\nOne of the following commands must be executed from the root directory of this project:\n```bash\n# Default\n$ mvn clean install -DskipTests\n\n# To create a \"fat jar\" for each module, run:\n$ mvn clean install -DskipTests -PfatJar\n```\n\nAfter the command successfully finishes, you can now use _Bigraph Framework_ in other Java projects.\nAll modules of _Bigraph Framework_ have been installed in the local Maven repository.\nTherefore, see [Maven configuration](#maven) on how to include the individual _Bigraph Framework_ dependencies.\n\n\u003e **Note:** All parts of Bigraph Framework are also deployed to the [Maven Central Repository](https://central.sonatype.com/).\n\n### Building the Documentation: User Manual\n\nSee [etc/Development-and-Deployment.md](./etc/Development-and-Deployment.md) for more details.\n\nBuilding the documentation builds also the project without running tests.\nAfter running the commands as described below from the root of this project, the generated user manual will be available\nat `documentation/v2-docusaurus/`:\n\n```shell\n$ mvn clean package -DskipTests\n$ cd ./documentation/v2-docusaurus/\n$ nvm use 20.18.1\n$ npm run start\n```\n\nThen, open the browser at `http://localhost:3000/software/bigraph-framework/`.\n\nThe manual is generated using [docusaurus](https://docusaurus.io/), which must be installed on the system\n(see [Development-and-Deployment.md](etc/Development-and-Deployment.md)).\n\n### Further Development and Deployment Instructions\n\nSee the document [etc/Development-and-Deployment.md](./etc/Development-and-Deployment.md) for more issues regarding the development and deployment of _Bigraph Framework_.\n\nTo deploy Bigraph Framework to the [Maven Central Repository](https://central.sonatype.com/):\n```bash\n$ mvn clean deploy -DskipTests -P release,central\n```\n\n## License\n\n**Bigraph Framework** is Open Source software released under the Apache 2.0 license.\n\n```text\nCopyright 2021-present Bigraph Toolkit Suite Developers.\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigraph-toolkit-suite%2Fbigraphs.bigraph-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbigraph-toolkit-suite%2Fbigraphs.bigraph-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigraph-toolkit-suite%2Fbigraphs.bigraph-framework/lists"}