QMCPACK / QMCPACK/qmcpack

Problems with the <include> tag (document and implement safe and consistent behavior)

Open
#5,532 1 comment 0 reactions 0 assignees View on GitHub
documentation
Dominant language
C++
Stars
403
Forks
154
Avg merge
1d 13h
Merged PRs (30d)
90

Description

**Describe the bug**
the
```

```
results in input semantics different from what "including" the href'd file into the input would be and makes the idea of valid and easily described xml input worse.

**To Reproduce**
Here's how it actually works:
I must be a child of the inputfile's root node, It can be used to reference an XML file, this is then parsed as described below at the point in the QMCMain state graph at that point in the node by node child traversal of the main input root XML node. It can include anything as long as libxml2 can parse the document.
It then runs `QMCMain::processPWH` on the root node of the included document.
``` xml

```

This root node can be anything, the parsing of include file doesn't care or even examine this node in anyway.
Any particle set, hamiltonian, wavefunction gets pushed to its pool, simulationcell overwrites particlepool's simulationcell and estimators node overwrites the global EstimatorManagerInput. every other child XML node in the included file's root just gets pushed into the QMCMain::qmc_action_ vector. Recall the qmc_action_ vector gets iterated over after the initial parse and if it contains a node that isn't qmc, optimize, loop, cmc, debug it just ignores it silently.

For the pools the defined element gets put in the map, but if the name i.e. key matches one already present it gets silently dropped, it does not replace the ParticleSet or whatever (unintuitive behavior of std::map). For the simulationcell it will get overwritten as will the global estimators will as well.

So it really matters where the include tag is in the main input file.

One thing the include file can't be is I would recognize as valid input i.e. at least if you were trying to get the pools from the included file. You would get the qmc sections.
``` xml

...

...

```
but the pool elements in qmcsystem would end up in qmc_action_ and be ignored.

**Expected behavior**
Consistent behavior that encourages best practice input format. What system you end up simulating and what sections are run needs to be clear and not the result of behavior wrt tag sequence that drops some included sections, ignores others, and overwrites others still.

Why it matters, the labs are full of use of this tag. Our tutorials encourage users to use a potentially very confusing and broken way to specify input.

**System:**
Any

**Additional context**
This must have seemed like a clever hack delivering convenient functionality for a few lines of code. This is an example of a feature that we should only consider keeping by breaking existing user input.

Contributor guide

Open the contributing guide

Research direction

Start by tracing the handling into QMCMain::processPWH and follow how included nodes enter qmc_action_. Review the libxml2 parsing boundary and the handling of particle sets, simulation cells, estimators, and duplicate names. Done means the include behavior is safe and consistent, with section ordering, ignored nodes, overwrites, and dropped definitions clearly resolved.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
backend
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.