{"id":28990455,"url":"https://github.com/4d-star/gridfire","last_synced_at":"2025-06-25T00:11:21.600Z","repository":{"id":300373551,"uuid":"1006010827","full_name":"4D-STAR/GridFire","owner":"4D-STAR","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-21T09:39:29.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-21T10:35:14.303Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/4D-STAR.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-06-21T09:37:30.000Z","updated_at":"2025-06-21T09:39:32.000Z","dependencies_parsed_at":"2025-06-21T10:46:37.933Z","dependency_job_id":null,"html_url":"https://github.com/4D-STAR/GridFire","commit_stats":null,"previous_names":["4d-star/gridfire"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/4D-STAR/GridFire","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4D-STAR%2FGridFire","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4D-STAR%2FGridFire/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4D-STAR%2FGridFire/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4D-STAR%2FGridFire/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/4D-STAR","download_url":"https://codeload.github.com/4D-STAR/GridFire/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4D-STAR%2FGridFire/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261777776,"owners_count":23208130,"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":[],"created_at":"2025-06-25T00:11:18.991Z","updated_at":"2025-06-25T00:11:21.093Z","avatar_url":"https://github.com/4D-STAR.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo/GridFire.png\" width=\"300\" alt=\"OPAT Core Libraries Logo\"\u003e\n\u003c/p\u003e\n\n\n---\n\nGridFire is a C++ library designed to preform general nuclear network evolution using the reaclib library. It is a\npart of the larger SERiF project which is itself a part of the 4D-STAR collaboration. \n\n\u003e Note that GridFire is still very early in development and is not ready for scientific use. The API is not stable and\n\u003e the reults are not yet validated. We are actively working on improving the library and once it is tested and validated\n\u003e we will release a stable version.\n\n## Design\n\nGridFire uses a \"graph-first\" design to represent the nuclear network. Specifically, internally the network is\nrepresented as a directed hypergraph where nodes are nuclides and edges are reactions. This design allows for very straightforward\nand efficient evolution of the network topology. \n\n## Current Features\n- **Reaclib Support**: GridFire uses reaclib coefficients statically compiled into the binary to evaluate reation rates. We bundle a script which can be used to generate the header files where these are stored. \n- **Auto Differentiation**: GridFire uses [CppAD](https://github.com/coin-or/CppAD) to generate analytic Jacobians for stiff network evaluation.\n- **Dynamic Network Topology**: GridFire supports dynamic network topology, allowing for the addition and removal of nuclides and reactions during runtime.\n- **Dynamic Stiff Detection**: GridFire uses a heuristic stiff detection algorithm to determine the stiffness of the network at runtime.\n\n## Planned Features\n### High Priority\n- **Reverse Reactions**: Currently, GridFire only supports forward reactions. Very soon we will add support for reverse reactions.\n- **Weak Reactions**: GridFire will eventually support weak reactions, allowing for a more complete nuclear network evolution.\n- **Python Bindings**: We plan to add Python bindings to GridFire, allowing for easy integration with Python-based workflows.\n\n### Low Priority\n- **GPU and Multi-Core Support**: We plan to add support for GPU and multi-core execution, allowing for faster network evolution.\n- **Topology Optimization**: We plan to add support for topology optimization, allowing for more efficient network evolution.\n- **Real-Time Network Visualization**: We plan to add support for real-time network visualization, allowing for better understanding of the network evolution.\n\n## Building\nGridFire uses meson as its build system. The minimum required version is 1.5.0. To build GridFire, you will need to have the following dependencies installed:\n\n- C++ compiler supporting at least C++20 (though we test against C++23, and it is **strongly** recommended to use C++23)\n- [Meson](https://mesonbuild.com/) build system (`apt install meson` or `brew install meson` or `pip install \"meson\u003e=1.5.0\"`)\n- [Ninja](https://ninja-build.org/) build system (`apt install ninja-build` or `brew install ninja` or `pip install ninja`)\n- (_optional to have preinstalled_) [Boost](https://www.boost.org/) libraries (`apt install libboost-all-dev` or `brew install boost`)\n\nBoost is labeled as optional because if GridFire cannot find boost during installation it will ask the user if they want\nto install it, and then it will take care of that insallation. \n\nOnce at least the C++ compiler, meson, and ninja are installed, you can build GridFire by running the following commands in the root directory of the repository:\n\n```bash\nmeson setup build --buildtype=release\nmeson compile -C build\nmeson install -C build\n```\n\nRunning the first command will create a `build` directory in the root of the repository, which will contain all the\nbuild files. The second command will compile the library and the third command will install it to your system.\nWhen installing GridFire it will generate a `pkg-config` file which can be used to link against the library in other\nprojects.\n\n### Linking Against GridFire\nThe easiest way, by far, to link against GridFire is to use `pkg-config`. This will automatically handle all the\nlibrary and include flags for you. Further, the `pkg-config` file will also include the required information on\nthe libcomposition library so that you do not need to also manually link against it.\n\n```bash\ng++ -o main.cpp $(pkg-config --cflags --libs gridfire)\n```\n\n### Meson Wrap Installed Dependencies\nAside from Boost, GridFire dependes on a few other libraries which are not required to be installed on the system, but\nare instead downloaded and built as part of the GridFire build process. These are:\n- [CppAD](https://github.com/coin-or/CppAD): Used for automatic differentiation.\n- [libcomposition](https://github.com/4d-star/libcomposition): Used for composition of networks.\n- [libconfig](https://github.com/4d-star/libconfig): Used for configuration management.\n- [libconstants](https://github.com/4d-star/libconstants): Used for physical constants.\n- [liblogging](https://github.com/4d-star/liblogging): Used for logging.\n\nThese will all be downloaded and build automatically by meson when you run the `meson setup` and `meson compile` commands.\n\n## Usage\n\n\u003e All code in GridFire is within the `gridfire` namespace. This means that you will need to use `gridfire::` prefix when\n\u003e using any of the classes or functions in GridFire.\n\n\u003e All code in lib* libraries is within the `fourdst::` namespace or subnamespaces of this (`fourdst::composition`,\n`fourdst::config`, etc...). This means that you will need to use `fourdst::` prefix when using any of the classes or\n\u003e functions in these libraries.\n\nGridFire is designed to primarily interface with `fourdst::composition::Composition` objects (provided by libcomposition).\nThe idea is that you create a composition object which tracks some set of species and either their mass fractions or number\nfractions. You then initialize a network from this composition object. \n\nWhen evaluating the network you pass the current state of the composition object, the temperature, the density, and the \ncurrent energy of the system (along with some other parmeters such as the maximum time and the initial time step). Any\nnetwork implemented in GridFire will then use this information to evolve the network and return a `gridfire::NetOut` object\nwhich contains the updated state of the composition object, the new energy of the system, and the number of steps the\nsolver took to reach the final state.\n\nThere are a few networks currently implemented in GridFire.\n\n| Network Name               | Description                                                                                                                                                                             | Network Format Enum |\n|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------|\n| `gridfire::GraphNetwork`   | A general nuclear network which uses a directed hypergraph to represent the network topology. This is the main network implemented in GridFire and is the one you will most likely use. | `REACLIB`         |\n| `gridfire::StaticGraphNetwork` |  A less general version of `gridfire::GraphNetwork` which uses a static graph to represent the network topology. That is to say that new species cannot be added or removed after instatiation of the network. | `REACLIB_STATIC`  |\n| `gridfire::Approx8Network` | A specialized network for the approximate 8 species network used in stellar nucleosynthesis. This is a reimplimentation of the network developed by Frank Timmes' for MESA              | `APPROX8`          |\n| `gridfire::Network`        | A virtual base class for all networks in GridFire. This is not meant to be used directly; rather, all networks in GridFire should subclass `gridfire::Network` and implement the required `evaluate` method. | `DEFAULT`         |\n\nRegardless of the network you chose, the interface is the same. You will need to create a `gridfire::NetIn` object\nwhich contains the initial state of the network, including the composition, temperature, density, energy, initial time\nstep, and maximum time. You will then pass this object to the `evaluate` method of the network you chose. The `evaluate`\nmethod will return a `gridfire::NetOut` object which contains the updated state of the network.\n\nA simple example of how to use `gridfire::GraphNetwork` is shown below (note that `composition.h` is a header file\nprovided by libcomposition, which means your compiler must be able to find its header and library files. The pkg-config\nfile generated during the installation of GridFire will take care of this for you, so you can use `pkg-config` to\ncompile this example):\n\n```c++\n#include \u003cgridfire/netgraph.h\u003e\n#include \u003cfourdst/composition/composition.h\u003e\n\n#include \u003ciostream\u003e\n#include \u003cvector\u003e\n#include \u003cstring\u003e\n\nint main() {\n    const std::vector\u003cdouble\u003e comp = {0.708, 2.94e-5, 0.276, 0.003, 0.0011, 9.62e-3, 1.62e-3, 5.16e-4};\n    const std::vector\u003cstd::string\u003e symbols = {\"H-1\", \"He-3\", \"He-4\", \"C-12\", \"N-14\", \"O-16\", \"Ne-20\", \"Mg-24\"};\n\n    fourdst::composition::Composition composition;\n    \n    // true puts this in mass fraction mode. false would mean you must provide number fractions instead.\n    composition.registerSymbol(symbols, true); \n    \n    composition.setMassFraction(symbols, comp);\n    composition.finalize(true);\n\n    gridfire::NetIn netIn;\n    netIn.composition = composition;\n    netIn.temperature = 1e7; // In Kelvin\n    netIn.density = 1e2;     // In g/cm^3\n    netIn.energy = 0.0;      // Initial energy in erg\n\n    netIn.tMax = 3.15e17;    // In seconds\n    netIn.dt0 = 1e12;        // Initial time step in seconds\n\n    gridfire::GraphNetwork network(composition);\n    network.exportToDot(\"Network.dot\");\n    gridfire::NetOut netOut;\n    netOut = network.evaluate(netIn);\n    std::cout \u003c\u003c netOut \u003c\u003c std::endl;    \n}\n\n```\nSave that file to `main.cpp` and compile it with the following command:\n```bash\ng++ main.cpp $(pkg-config --cflags --libs gridfire) -o main\n./main\n```\n\nUsing a different network is as simple as changing the type of the `network` variable to the desired network type. For\nexample, if you wanted to use the `gridfire::Approx8Network`, you would change the line\n`gridfire::GraphNetwork network(composition);` to `gridfire::Approx8Network network(composition);`. The rest of the code\nwould remain the same.\n\nFor more details on how to use the composition library please refer to the libcomposition documentation.\n\n## Funding\nGridFire is a part of the 4D-STAR collaboration.\n\n4D-STAR is funded by European Research Council (ERC) under the Horizon Europe programme (Synergy Grant agreement No.\n101071505: 4D-STAR)\nWork for this project is funded by the European Union. Views and opinions expressed are however those of the author(s)\nonly and do not necessarily reflect those of the European Union or the European Research.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4d-star%2Fgridfire","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F4d-star%2Fgridfire","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4d-star%2Fgridfire/lists"}