Refactor Axial Expansion

[albeanth]

What is the change?

This PR does a fairly large refactor of the axial expansion functionality in ARMI. A new directory is structure is created to enable better traceability with testing and general maintainability.

Original:

armi/reactor/converters/
|-- axialExpansionChanger.py

and unit tests:

armi/reactor/converters/tests
|-- test_axialExpansionChanger.py

New:

armi/reactor/converters/axialExpansion
|
|-- assemblyAxialLinkage.py
|-- axialExpansionChanger.py
|-- expansionData.py

and unit tests

armi/reactor/converters/axialExpansion/tests
|
|-- test_assemblyAxialLinkage.py
|-- test_axialExpansionChanger.py
|-- test_expansionData.py

Notes:

1. though there are a lot of diffs in the "Files Changed" tab, no new functionality is added.
2. the original testing file had lots of "integration" tests within it. Those are kept and smaller accompanying unit tests are added here.
3. to reviewers: if you want me to try and interactive rebase this or split it up into multiple PRs, let me know.

This does include the changes from PR #1427.

Why is the change being made?

1. The original axialExpansionChanger.py file was responsible for too many things. It was ready to be split up to improve maintainability.
2. The original test_axialExpansionChanger.py was likewise too big and doing too much. It has now been split up and is easier to maintain.

---

Checklist

• This PR has only one purpose or idea.
• Tests have been added/updated to verify that the new/changed code works.

• The code style follows good practices.
• The commit message(s) follow good practices.

• The release notes (location doc/release/0.X.rst) are up-to-date with any important changes.
• The documentation is still up-to-date in the doc folder.
• The dependencies are still up-to-date in pyproject.toml.

[john-science]

1. I think this needs a release note. It's a non-trivial re-write.
2. How much does the Axial Expansion API change? (For people writing code downstream, does this change the API at all?)

[albeanth]

1. I think this needs a release note. It's a non-trivial re-write.

Yes. I will add one once we get further into the review.

2. How much does the Axial Expansion API change? (For people writing code downstream, does this change the API at all?)

The API actually should not have changed at all actually. At least not to that I can remember off the top of my head. I am going to run this on the slough of internal tests though to confirm.

[albeanth]

The API actually should not have changed at all actually. At least not to that I can remember off the top of my head. I am going to run this on the slough of internal tests though to confirm.

The API for unit testing did change. And the refactor changed some imports downstream. So there is an another (minor) downstream PR.

[albeanth]

@john-science @keckler giving a bump on this.

just started doing QA work for the axial expansion changer and it would be really nice to push this through. the improved unit testing and accompanying refactor will help keep things clean imo.

happy to chat offline too.

[john-science]

Put something on my calendar for this, @albeanth

[albeanth]

Put something on my calendar for this, @albeanth

I'll put something on your calendar for next week. Some of the downstream testing is freaking out. I have no idea why and don't have enough time to figure it out this week unfortunately...

[albeanth]

@john-science / @keckler / @opotowsky also, if you guys merge this PR while I'm out this week, make sure it is coordinated with other downstream PRs. Otherwise we'll end up with Christmas in July.

[john-science]

Suggested change

	"""Particles! Expand axially!."""
	"""The top-level axial expansion module, and a small set of assembly expansion utilities."""

[john-science]

Suggested change

	a : :py:class:`Assembly <armi.reactor.assemblies.Assembly>`
	reference to original assembly; is directly modified/changed during expansion.
	linkedBlocks : dict
	keys --> :py:class:`Block <armi.reactor.blocks.Block>`
	values --> list of axially linked blocks; index 0 = lower linked block; index 1: upper linked block.
	see also: self._getLinkedBlocks()
	linkedComponents : dict
	keys --> :py:class:`Component <armi.reactor.components.component.Component>`
	values --> list of axially linked components; index 0 = lower linked component; index 1: upper linked component.
	see also: self._getLinkedComponents
	a : :py:class:`Assembly <armi.reactor.assemblies.Assembly>`
	reference to original assembly; is directly modified/changed during expansion.
	linkedBlocks : dict
	keys --> :py:class:`Block <armi.reactor.blocks.Block>`
	values --> list of axially linked blocks; index 0 = lower linked block; index 1: upper linked block.
	see also: self._getLinkedBlocks()
	linkedComponents : dict
	keys --> :py:class:`Component <armi.reactor.components.component.Component>`
	values --> list of axially linked components; index 0 = lower linked component; index 1: upper linked component.
	see also: self._getLinkedComponents

[john-science]

At your discretion, but for whatever reason, I found this hard to read with all the whitespace.

[john-science]

What about NullComponent?

[john-science]

Do we have a unit test that covers the warnings and errors in this method?

(The primary cause of code coverage being low in ARMI right now is people adding a near infinite number of warnings, but not testing them. In the future, I am wondering if all need warnings and exceptions should be covered by tests. Though I haven't made that rule yet, obviously.)

[albeanth]

These should have testing, yes. I made a concerted effort a year or two ago to make sure that each of these had coverage and that axial expansion had 100% testing coverage. It should be the same...!

[john-science]

Out of curiosity, do you think anyone but you will ever want to see these debug lines?

My concern is that they look like something you added because they were useful to you developing axial expansion?

[john-science]

It appears to me (tell me if I'm wrong!) that axial expansion only works on a pin-type (assembly-type) reactor.

Assuming that's true, I think this might be something more like:

Axially expand or contract assemblies or an entire core of assemblies.

But more so, I wonder if there is another high-level place or two we should call out that this feature only works on assemblies. Thoughts?

[john-science]

For some reason, this name seems too short to me. Maybe add "Block"?

buildDummySodiumBlock

Thoughts?

[jakehader]

I'm not sure if it's documented somewhere, but maybe explaining the significance of a DUMMY name would be valuable as a test with the flag system. Essentially you might want a test that demonstrates this method is returning the expected thing if not already checked by itself in a test just in case this flag gets broken later by accident.

[john-science]

Just trying to fix the RST / Sphinx formatting.

[jakehader]

@albeanth - I'm curious if you've tried different ways to use the axial expansion code in an unintended way, like calling methods out of order or with different, unexpected block types or geometries. Essentially, I'm wondering if there are sufficient checks on the Assembly design (e.g., hex, Cartesian, RZ, etc.) to guard against excepted behavior. If so, would you be able to point out some of those unit tests or if not, could you add some? For example, what about an assembly with custom ISO topics as the materials? What about homogeneous blocks with no components?