diff --git a/.gitignore b/.gitignore index cb7c7e942..201e3f030 100644 --- a/.gitignore +++ b/.gitignore @@ -34,6 +34,8 @@ docs/src/act.md docs/src/act_details.md docs/src/dd_details.md docs/src/tutorial.md +docs/src/deps.md +docs/src/deps.dot # Ignore all juptyer notebooks (you can still force them in with git add -f) *.ipynb diff --git a/Makefile b/Makefile index 41cd65dac..62c5a3be5 100644 --- a/Makefile +++ b/Makefile @@ -352,6 +352,64 @@ dev_deps_tree: AbstractTrees.print_tree(Pkg.project().dependencies["FUSE"]) ;\ ' +# @devs +dev_deps_dag: +# Generate a DOT file representing the dependency DAG of the FUSE package + @julia -e' ;\ + using Pkg ;\ + Pkg.add("AbstractTrees") ;\ + using Random ;\ + using AbstractTrees ;\ + using Printf ;\ + edges = Set{Tuple{String, String}}() ;\ + function random_color() ;\ + r = rand(0:255) ;\ + g = rand(0:255) ;\ + b = rand(0:255) ;\ + return @sprintf("#%02x%02x%02x", r, g, b) ;\ + end ;\ + function AbstractTrees.printnode(io::IO, uuid::Base.UUID) ;\ + dep = get(Pkg.dependencies(), uuid, nothing) ;\ + print(io, dep.name) ;\ + end ;\ + function AbstractTrees.children(uuid::Base.UUID) ;\ + dep = get(Pkg.dependencies(), uuid, nothing) ;\ + dev_deps = Dict([(key, value) for (key, value) in dep.dependencies if value !== nothing && isdir("../$$(get(Pkg.dependencies(), value, nothing).name)")]) ;\ + return sort!(collect(values(dev_deps)), by=x->get(Pkg.dependencies(), x, (name="",)).name) ;\ + end ;\ + function collect_edges(uuid::Base.UUID, edges::Set{Tuple{String, String}}) ;\ + dep = get(Pkg.dependencies(), uuid, nothing) ;\ + if dep !== nothing ;\ + for subdep in AbstractTrees.children(uuid) ;\ + subdep_info = get(Pkg.dependencies(), subdep, nothing) ;\ + if subdep_info !== nothing ;\ + push!(edges, (dep.name, subdep_info.name)) ;\ + collect_edges(subdep, edges) ;\ + end ;\ + end ;\ + end ;\ + end ;\ + project_dep = Pkg.project().dependencies["FUSE"] ;\ + if project_dep !== nothing ;\ + collect_edges(project_dep, edges) ;\ + end ;\ + open("docs/src/deps.dot", "w") do io ;\ + write(io, "digraph G {\n") ;\ + write(io, "rankdir=LR;\n");\ + write(io, "ranksep=0.4;\n");\ + write(io, "nodesep=0.1;\n");\ + write(io, "splines=true;\n");\ + write(io, "node [shape=ellipse, fontname=\"Helvetica\", fontsize=12, penwidth=3];\n");\ + write(io, "edge [penwidth=2];\n");\ + for (src, dst) in edges ;\ + color = random_color() ;\ + @printf(io, "\"%s\" -> \"%s\" [color=\"%s\"];\n", src, dst, color) ;\ + end ;\ + write(io, "}\n") ;\ + end ;\ + ' + dot -Tsvg docs/src/deps.dot -o docs/src/assets/deps.svg + # @devs develop: # Develop FUSE and related ProjectTorreyPines packages diff --git a/docs/make.jl b/docs/make.jl index ce6945fc8..3a624054e 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -163,6 +163,11 @@ include("$(@__DIR__)/src/act_docs.jl") # =================== # include("$(@__DIR__)/src/cases_docs.jl") +# ========================== # +# generate dependencies page # +# ========================== # +include("$(@__DIR__)/src/deps.jl") + # # ====================== # # # generate examples page # # # ====================== # @@ -193,7 +198,7 @@ makedocs(; "Actors" => ["List of actors" => "actors.md", "act parameters" => "act.md"], "Initialization" => ["Init routines" => "inits.md", "ini parameters" => "ini.md"], "Data Structure" => "dd.md", - "Development" => "develop.md", + "Ecosystem" => ["deps.md", "develop.md"], "Install" => ["Install FUSE" => "install.md", "on SAGA" => "install_saga.md", "on OMEGA" => "install_omega.md"], "License" => ["License" => "license.md", "Notice" => "notice.md"] ] diff --git a/docs/src/assets/deps.svg b/docs/src/assets/deps.svg new file mode 100644 index 000000000..09b676b41 --- /dev/null +++ b/docs/src/assets/deps.svg @@ -0,0 +1,511 @@ + + + + + + +G + + + +VacuumFields + +VacuumFields + + + +FusionMaterials + +FusionMaterials + + + +VacuumFields->FusionMaterials + + + + + +MXHEquilibrium + +MXHEquilibrium + + + +VacuumFields->MXHEquilibrium + + + + + +IMAS + +IMAS + + + +VacuumFields->IMAS + + + + + +MillerExtendedHarmonic + +MillerExtendedHarmonic + + + +VacuumFields->MillerExtendedHarmonic + + + + + +TEQUILA + +TEQUILA + + + +VacuumFields->TEQUILA + + + + + +FusionMaterials->IMAS + + + + + +EFIT + +EFIT + + + +MXHEquilibrium->EFIT + + + + + +CoordinateConventions + +CoordinateConventions + + + +MXHEquilibrium->CoordinateConventions + + + + + +MXHEquilibrium->MillerExtendedHarmonic + + + + + +MeshTools + +MeshTools + + + +MXHEquilibrium->MeshTools + + + + + +ThermalSystemModels + +ThermalSystemModels + + + +XSteam + +XSteam + + + +ThermalSystemModels->XSteam + + + + + +FUSE + +FUSE + + + +FUSE->VacuumFields + + + + + +FUSE->FusionMaterials + + + + + +FUSE->MXHEquilibrium + + + + + +FUSE->ThermalSystemModels + + + + + +Metaheuristics + +Metaheuristics + + + +FUSE->Metaheuristics + + + + + +QED + +QED + + + +FUSE->QED + + + + + +FUSE->IMAS + + + + + +TGLFNN + +TGLFNN + + + +FUSE->TGLFNN + + + + + +NEO + +NEO + + + +FUSE->NEO + + + + + +FuseUtils + +FuseUtils + + + +FUSE->FuseUtils + + + + + +TJLF + +TJLF + + + +FUSE->TJLF + + + + + +CHEASE + +CHEASE + + + +FUSE->CHEASE + + + + + +BoundaryPlasmaModels + +BoundaryPlasmaModels + + + +FUSE->BoundaryPlasmaModels + + + + + +SimulationParameters + +SimulationParameters + + + +FUSE->SimulationParameters + + + + + +RABBIT + +RABBIT + + + +FUSE->RABBIT + + + + + +FUSE->TEQUILA + + + + + +EPEDNN + +EPEDNN + + + +FUSE->EPEDNN + + + + + +BalanceOfPlantSurrogate + +BalanceOfPlantSurrogate + + + +FUSE->BalanceOfPlantSurrogate + + + + + +NNeutronics + +NNeutronics + + + +FUSE->NNeutronics + + + + + +FiniteElementHermite + +FiniteElementHermite + + + +QED->FiniteElementHermite + + + + + +IMAS->FuseUtils + + + + + +IMAS->CoordinateConventions + + + + + +IMAS->MillerExtendedHarmonic + + + + + +GraphRecipes + +GraphRecipes + + + +IMAS->GraphRecipes + + + + + +IMASdd + +IMASdd + + + +IMAS->IMASdd + + + + + +FuseExchangeProtocol + +FuseExchangeProtocol + + + +IMAS->FuseExchangeProtocol + + + + + +EFIT->IMASdd + + + + + +TGLFNN->IMAS + + + + + +NEO->IMAS + + + + + +CHEASE->MXHEquilibrium + + + + + +CHEASE->EFIT + + + + + +CHEASE->MillerExtendedHarmonic + + + + + +Fortran90Namelists + +Fortran90Namelists + + + +CHEASE->Fortran90Namelists + + + + + +BoundaryPlasmaModels->IMAS + + + + + +BoundaryPlasmaModels->FuseUtils + + + + + +BoundaryPlasmaModels->SimulationParameters + + + + + +ADAS + +ADAS + + + +BoundaryPlasmaModels->ADAS + + + + + +RABBIT->IMASdd + + + + + +TEQUILA->MXHEquilibrium + + + + + +TEQUILA->FiniteElementHermite + + + + + +TEQUILA->MillerExtendedHarmonic + + + + + diff --git a/docs/src/deps.jl b/docs/src/deps.jl new file mode 100644 index 000000000..698cbb289 --- /dev/null +++ b/docs/src/deps.jl @@ -0,0 +1,20 @@ +deps = "ADAS BalanceOfPlantSurrogate BoundaryPlasmaModels CHEASE CoordinateConventions EPEDNN FiniteElementHermite Fortran90Namelists FuseUtils FusionMaterials FuseExchangeProtocol IMAS IMASdd MXHEquilibrium MeshTools MillerExtendedHarmonic NEO NNeutronics QED RABBIT SimulationParameters TEQUILA TGLFNN TJLF VacuumFields XSteam ThermalSystemModels" + +txt = String[""" +# Dependencies + +The FUSE project is built upon multiple Julia packages, many of which reside in the [https://github.com/ProjectTorreyPines](https://github.com/ProjectTorreyPines) organization on GitHub. + +![FUSE dependencies](./assets/deps.svg) + +"""] +for dep in sort!(split(deps)) + if dep in ("Fortran90Namelists", ) + continue + end + push!(txt, "* [$dep](https://projecttorreypines.github.io/$dep.jl/dev/) [[repo](https://github.com/ProjectTorreyPines/$dep.jl)]") +end + +open("$(@__DIR__)/deps.md", "w") do io + return write(io, join(txt, "\n")) +end diff --git a/docs/src/develop.md b/docs/src/develop.md index 519e4a9b6..9fb2c4abd 100644 --- a/docs/src/develop.md +++ b/docs/src/develop.md @@ -1,20 +1,14 @@ # Development -The FUSE project is built upon multiple Julia packages, many of which reside in the [https://github.com/ProjectTorreyPines](https://github.com/ProjectTorreyPines) organization on GitHub. - -## Managing Pull Requests on GitHub: A Collaborative Approach - -### Use branches and pull requests +FUSE is a collaborative project that welcomes contributions. The `master` branch of ProjectTorreyPines repositories is write-protected. This means that even with write permissions to the repository, you'll not be able to push to `master` directly. Instead, we handle updates – be it new features or bug fixes – through branches and Pull Requests (PRs). +A crucial part of our PR process is code review. It is where your peers get to weigh in and ensure everything is up to standard before merging. When you create a PR, think about who on the team has the right expertise for the code you're working on, and assign them as reviewers. Their insights will not only help in maintaining code quality but also in catching any potential issues early. It is all about teamwork and making sure our code is the best it can be! + !!! note When working on a new feature that involves changes to FUSE and other ProjectTorreyPines repositories, you'll want to use the same branch name across these repositories. For example, if you're working on a branch named `my_new_feature` in both FUSE and IMAS, regression testing will be performed using the `my_new_feature` branches for FUSE and IMAS, along with the `master` branch of the other `ProjectTorreyPines` repositories. -### Code review - -A crucial part of our PR process is code review. It is where your peers get to weigh in and ensure everything is up to standard before merging. When you create a PR, think about who on the team has the right expertise for the code you're working on, and assign them as reviewers. Their insights will not only help in maintaining code quality but also in catching any potential issues early. It is all about teamwork and making sure our code is the best it can be! - ## How to add/modify entries in `dd` The `dd` data structure is defined under the [IMASdd.jl](https://github.com/ProjectTorreyPines/IMASdd.jl) package. See the documentation there to how add/modify entries in `dd`. diff --git a/docs/src/tutorial.jl b/docs/src/tutorial.jl index 50424c070..d6f0854fe 100644 --- a/docs/src/tutorial.jl +++ b/docs/src/tutorial.jl @@ -1,5 +1,7 @@ # # FUSE Introductory Tutorial +# Download this tutorial from the [FuseExamples repository](https://github.com/ProjectTorreyPines/FuseExamples/blob/master/tutorial.ipynb) + # Import the necessary packages using Plots # for plotting