Background
There have been several requests to extend KOMODO to support hexagonal geometry. After investigating possible implementation approaches, I have concluded that the current KOMODO architecture makes this difficult to achieve cleanly.
KOMODO was originally developed when I had less software engineering experience, and many design choices were made incrementally while solving immediate implementation problems. As a result, the current architecture is not flexible enough for major geometry extensions, especially support for hexagonal geometry.
Because of this, I would like to propose a major codebase refactoring. This refactoring would likely touch many parts of the codebase and may require significant architectural changes. I have attempted this work before, but the effort was tedious and difficult to complete within the available time. With current development tools, including LLM-assisted refactoring, this task may now be more manageable, although it will still require careful design, testing, and review.
The following are the main refactoring targets currently under consideration. Note that the list below is not final, and I welcome suggestions for additional refactoring targets or alternative architectural designs.
1. Architectural changes
This is the main goal of the refactoring. The current architecture relies heavily on global data stored in mod_data.f90. Many variables are not grouped into derived types, and global data are commonly imported using use statements at the routine or function level.
A better approach would be to group related data and procedures into derived types. For example, after variable renaming, we could introduce a generic base type:
type :: base
! General variables
real(dp), allocatable :: flux(:,:) ! Current scalar flux
real(dp), allocatable :: flux_time(:,:) ! Previous time-step flux
real(dp), allocatable :: flux_iter(:,:) ! Previous iteration flux by group
real(dp), allocatable :: exsrc(:,:) ! External source
...
end type
I would prefer a structure-of-arrays (SoA) approach rather than an array-of-structures (AoS) approach. I previously tested an AoS design, and it degraded KOMODO performance.
Once a generic base type is available, geometry-specific types could extend it. For example, rectangular geometry could be represented as:
type, extends(base) :: rectangle
integer :: nx, ny, nz ! Number of assemblies in x, y, and z directions
integer :: nxx, nyy, nzz ! Number of nodes in x, y, and z directions
integer, allocatable :: ix(:), iy(:), iz(:) ! Node-to-mesh indices
...
end type
This would make it easier to introduce a future hexagonal type without forcing the entire codebase to assume rectangular geometry.
This design would also reduce the number of globally imported variables. Instead of importing long lists of data and procedures, modules and routines could operate on a small number of well-defined objects. Where appropriate, use statements could also be moved to the module level instead of being repeated inside many routines.
The exact implementation may differ from the example above, but the main idea is to reorganize the code around clearer data ownership and geometry-specific abstractions.
2. Variable renaming
Many current variable names are difficult to understand. For example, f0 represents the scalar flux, where 0 refers to the zeroth moment. While this may be meaningful to the original developer, it is not very readable for new contributors.
Renaming variables would significantly improve code readability and maintainability. For example:
could become:
Similarly, integer flags could be replaced by named constants or enumerations where possible. For example:
could become:
if (bmode == ACTIVE) then
This would make the code easier to understand and reduce the chance of errors caused by unclear magic numbers.
3. Solving the linear system for the full space-energy problem
In the current implementation, the linear system is solved separately for each energy group. This limits the acceleration methods that can be used. In particular, it prevents the use of the Wielandt shift method to accelerate outer iterations.
The current use of fission extrapolation together with nodal updates in CMFD can also cause numerical instability in some cases.
One possible refactoring target is to reformulate the solver so that the full space-energy system can be solved at once. This may allow more robust acceleration methods and improve numerical stability.
In addition, it may be useful to introduce preconditioning, such as ILU, especially for transient simulations.
4. Thermal-hydraulic module refactoring
The current thermal-hydraulic solver solves a plane at a time instead of solving a channel at a time. This is not ideal for parallelism.
A possible improvement is to refactor the TH solver so that each channel can be solved independently. This may improve parallel performance and make the TH module easier to maintain.
I am also considering fully separating the TH module from the main neutronics solver to improve modularity and reusability.
Expected benefits
This refactoring is expected to provide the following benefits:
- Easier implementation of hexagonal geometry
- Better separation between generic solver logic and geometry-specific logic
- Improved readability and maintainability
- Reduced reliance on global variables
- Better support for future numerical methods
- Improved modularity of the TH solver
- Easier onboarding for future contributors
Development freeze during refactoring
Because this refactoring may touch most parts of the codebase, merging unrelated pull requests during the process could create significant conflicts and make the refactoring harder to complete safely.
For that reason, once the refactoring starts, I propose a temporary development freeze on major feature PRs and large structural changes. During this period, new feature development should either be paused or coordinated carefully with the refactoring branch.
Notes
This issue is intended as an initial design discussion. The actual implementation may evolve as the codebase is reviewed in more detail.
Background
There have been several requests to extend KOMODO to support hexagonal geometry. After investigating possible implementation approaches, I have concluded that the current KOMODO architecture makes this difficult to achieve cleanly.
KOMODO was originally developed when I had less software engineering experience, and many design choices were made incrementally while solving immediate implementation problems. As a result, the current architecture is not flexible enough for major geometry extensions, especially support for hexagonal geometry.
Because of this, I would like to propose a major codebase refactoring. This refactoring would likely touch many parts of the codebase and may require significant architectural changes. I have attempted this work before, but the effort was tedious and difficult to complete within the available time. With current development tools, including LLM-assisted refactoring, this task may now be more manageable, although it will still require careful design, testing, and review.
The following are the main refactoring targets currently under consideration. Note that the list below is not final, and I welcome suggestions for additional refactoring targets or alternative architectural designs.
1. Architectural changes
This is the main goal of the refactoring. The current architecture relies heavily on global data stored in
mod_data.f90. Many variables are not grouped into derived types, and global data are commonly imported usingusestatements at the routine or function level.A better approach would be to group related data and procedures into derived types. For example, after variable renaming, we could introduce a generic base type:
I would prefer a structure-of-arrays (SoA) approach rather than an array-of-structures (AoS) approach. I previously tested an AoS design, and it degraded KOMODO performance.
Once a generic
basetype is available, geometry-specific types could extend it. For example, rectangular geometry could be represented as:This would make it easier to introduce a future
hexagonaltype without forcing the entire codebase to assume rectangular geometry.This design would also reduce the number of globally imported variables. Instead of importing long lists of data and procedures, modules and routines could operate on a small number of well-defined objects. Where appropriate,
usestatements could also be moved to the module level instead of being repeated inside many routines.The exact implementation may differ from the example above, but the main idea is to reorganize the code around clearer data ownership and geometry-specific abstractions.
2. Variable renaming
Many current variable names are difficult to understand. For example,
f0represents the scalar flux, where0refers to the zeroth moment. While this may be meaningful to the original developer, it is not very readable for new contributors.Renaming variables would significantly improve code readability and maintainability. For example:
could become:
Similarly, integer flags could be replaced by named constants or enumerations where possible. For example:
could become:
This would make the code easier to understand and reduce the chance of errors caused by unclear magic numbers.
3. Solving the linear system for the full space-energy problem
In the current implementation, the linear system is solved separately for each energy group. This limits the acceleration methods that can be used. In particular, it prevents the use of the Wielandt shift method to accelerate outer iterations.
The current use of fission extrapolation together with nodal updates in CMFD can also cause numerical instability in some cases.
One possible refactoring target is to reformulate the solver so that the full space-energy system can be solved at once. This may allow more robust acceleration methods and improve numerical stability.
In addition, it may be useful to introduce preconditioning, such as ILU, especially for transient simulations.
4. Thermal-hydraulic module refactoring
The current thermal-hydraulic solver solves a plane at a time instead of solving a channel at a time. This is not ideal for parallelism.
A possible improvement is to refactor the TH solver so that each channel can be solved independently. This may improve parallel performance and make the TH module easier to maintain.
I am also considering fully separating the TH module from the main neutronics solver to improve modularity and reusability.
Expected benefits
This refactoring is expected to provide the following benefits:
Development freeze during refactoring
Because this refactoring may touch most parts of the codebase, merging unrelated pull requests during the process could create significant conflicts and make the refactoring harder to complete safely.
For that reason, once the refactoring starts, I propose a temporary development freeze on major feature PRs and large structural changes. During this period, new feature development should either be paused or coordinated carefully with the refactoring branch.
Notes
This issue is intended as an initial design discussion. The actual implementation may evolve as the codebase is reviewed in more detail.