fix: parameter substitution for all card types (#983)

Co-authored-by: Mohamed Koubaa <[email protected]>
Co-authored-by: pyansys-ci-bot <[email protected]>

Author: 3 people

agents/parameters.md

@@ -276,10 +276,10 @@ def test_local_parameter_isolation():
     deck = Deck()
     deck.import_file("top.k")  # Has global param
     deck = deck.expand(recurse=True, cwd=test_dir)
-    
+
     # Global param should be accessible
     assert deck.parameters.get("global_param") == expected_value
-    
+
     # Local param from include should NOT be accessible
     with pytest.raises(KeyError):
         deck.parameters.get("local_param")
@@ -296,15 +296,135 @@ When implementing parameter-related features:
 - [ ] Test visibility: Verify child scopes can see parent params
 - [ ] Add logging: Use `logger.debug()` for parameter operations
 
+## Parameter Substitution in Card Types
+
+All card types now support LS-DYNA parameter substitution (`&parameter` and `-&parameter` syntax). This feature allows keywords to reference parameters defined via `*PARAMETER` or `*PARAMETER_LOCAL` keywords.
+
+### Supported Card Types
+
+**Card** (standard single-line cards):
+- Used for most keyword cards with fixed fields
+- Full parameter support via `load_dataline()`
+- Example: `*SECTION_SHELL` with `&thickness` parameter
+
+**SeriesCard** (arrays/lists):
+- Used for curve data, material properties arrays, etc.
+- Parameters supported in bounded and unbounded modes
+- Implementation: Passes `parameter_set` through to `load_dataline()`
+- Example: `*DEFINE_CURVE` with parametric Y-values
+
+**TableCard** (tabular data):
+- Used for node coordinates, element connectivity, etc.
+- Parameters detected automatically via `_has_parameters()`
+- Smart path selection: Uses fast pandas path when no parameters, falls back to `load_dataline()` when parameters detected
+- Implementation: `_load_lines_with_parameters()` processes line-by-line
+- Example: `*NODE` with parametric coordinates
+
+**TableCardGroup** (multiple interleaved tables):
+- Used for keywords with multiple cards per row
+- Inherits parameter support from TableCard
+- Parameters work across all sub-cards in the group
+
+### Parameter Name Constraints
+
+LS-DYNA parameter names must fit within field widths. For a 10-character field:
+- `&dens` fits (5 chars)
+- `&density` may be truncated (8 chars)
+
+Always verify parameter names fit within the field widths defined in your keyword schema.
+
+### Example Usage
+
+```python
+from ansys.dyna.core.lib.deck import Deck
+
+deck_text = """*KEYWORD
+*PARAMETER
+R_dens   7850.0
+I_nid    1000
+*DEFINE_CURVE
+     &nid
+       0.0       0.0
+     &dens     100.0
+*NODE
+    &nid     &dens       0.0       0.0
+*END"""
+
+deck = Deck()
+deck.loads(deck_text)
+
+# All keywords parse successfully with substituted values
+curve = deck.keywords[0]
+assert curve.lcid == 1000  # From I_nid parameter
+
+node = deck.keywords[1]
+assert node.nodes.table["nid"][0] == 1000
+assert node.nodes.table["x"][0] == 7850.0
+```
+
+### Implementation Details
+
+**SeriesCard** (`src/ansys/dyna/core/lib/series_card.py`):
+- `read()` accepts `parameter_set` and passes to load methods
+- `_read_line()` passes `parameter_set` to `load_dataline()`
+- Works in both bounded and unbounded modes
+
+**TableCard** (`src/ansys/dyna/core/lib/table_card.py`):
+- `_has_parameters()` detects `&` in data lines
+- `_load_lines_with_parameters()` uses `load_dataline()` for each row
+- `_load_lines()` chooses appropriate path based on parameter detection
+- No performance impact when parameters not present
+
+**TableCardGroup** (`src/ansys/dyna/core/lib/table_card_group.py`):
+- Passes `parameter_set` to child `TableCard` instances
+- No special handling needed (inherits from TableCard)
+
+### Testing
+
+See `tests/test_parameter_substitution.py` for comprehensive test coverage including:
+- Bounded and unbounded modes for all card types
+- Negative parameters (`-&param`)
+- Type conversion and validation
+- Error handling for missing/mismatched parameters
+- Mixed parameters and literal values
+- Regression testing for non-parameter cases
+
+### Error Handling
+
+The parameter substitution system provides clear error messages:
+
+- **Missing parameter**: `KeyError` with parameter name
+- **Type mismatch**: `TypeError` explaining the conversion failure
+- **No parameter set**: `ValueError` when `&` found but no `parameter_set` provided
+
+## Implementation Checklist (Extended)
+
+When implementing parameter-related features:
+
+- [ ] Consider scope: Is this global or local?
+- [ ] Check context: Which deck should receive the parameter?
+- [ ] Verify timing: Is parameter defined before use?
+- [ ] Test isolation: Verify parent/sibling isolation for local params
+- [ ] Test visibility: Verify child scopes can see parent params
+- [ ] Add logging: Use `logger.debug()` for parameter operations
+- [ ] Card type support: Ensure parameter_set is passed through card read chains
+- [ ] Field width constraints: Verify parameter names fit in field widths
+
 ## Key Files
 
 - `src/ansys/dyna/core/lib/parameters.py`: ParameterSet class and ParameterHandler
 - `src/ansys/dyna/core/lib/deck.py`: Deck expansion and include processing
 - `src/ansys/dyna/core/lib/deck_loader.py`: Keyword loading and parameter substitution
 - `src/ansys/dyna/core/lib/import_handler.py`: ImportContext and ImportHandler base
+- `src/ansys/dyna/core/lib/kwd_line_formatter.py`: `load_dataline()` with parameter substitution
+- `src/ansys/dyna/core/lib/card.py`: Standard card parameter support
+- `src/ansys/dyna/core/lib/series_card.py`: SeriesCard parameter support
+- `src/ansys/dyna/core/lib/table_card.py`: TableCard parameter support
+- `src/ansys/dyna/core/lib/table_card_group.py`: TableCardGroup parameter support
+- `tests/test_parameter_substitution.py`: Comprehensive parameter substitution tests
 
 ## Related Documentation
 
 - [Codegen Guide](codegen.md): Auto-generated keyword classes
 - [Linked Keywords](linked_keywords.md): Keyword relationships and properties
-- GitHub Issue #641: PARAMETER_LOCAL scoping implementation
+- GitHub Issue #641: Parameter substitution for all card types

doc/.vale.ini

@@ -17,7 +17,7 @@ SkippedScopes = script, style, pre, figure
 WordTemplate = \b(?:%s)\b
 
 # Ignore autogenerated files and internal development notes
-IgnoredFiles = **/todo.md, source/_autosummary/airbag.rst, source/_autosummary/ale.rst, source/_autosummary/battery.rst, source/_autosummary/boundary.rst, source/_autosummary/case.rst, source/_autosummary/cese.rst, source/_autosummary/change.rst, source/_autosummary/chemistry.rst, source/_autosummary/component.rst, source/_autosummary/constrained.rst, source/_autosummary/contact.rst, source/_autosummary/control.rst, source/_autosummary/controller.rst, source/_autosummary/cosim.rst, source/_autosummary/damping.rst, source/_autosummary/database.rst, source/_autosummary/define.rst, source/_autosummary/deformable.rst, source/_autosummary/delete.rst, source/_autosummary/dualcese.rst, source/_autosummary/ef.rst, source/_autosummary/element.rst, source/_autosummary/em.rst, source/_autosummary/eos.rst, source/_autosummary/fatigue.rst, source/_autosummary/frequency.rst, source/_autosummary/icfd.rst, source/_autosummary/iga.rst, source/_autosummary/include.rst, source/_autosummary/index.rst, source/_autosummary/initial.rst, source/_autosummary/integration.rst, source/_autosummary/interface.rst, source/_autosummary/keyword.rst, source/_autosummary/load.rst, source/_autosummary/lso.rst, source/_autosummary/mat.rst, source/_autosummary/mesh.rst, source/_autosummary/module.rst, source/_autosummary/node.rst, source/_autosummary/other.rst, source/_autosummary/parameter.rst, source/_autosummary/part.rst, source/_autosummary/particle.rst, source/_autosummary/perturbation.rst, source/_autosummary/rail.rst, source/_autosummary/rigid.rst, source/_autosummary/rigidwall.rst, source/_autosummary/rve.rst, source/_autosummary/section.rst, source/_autosummary/sensor.rst, source/_autosummary/set.rst
+IgnoredFiles = **/todo.md, AGENTS.md, agents/**, source/_autosummary/airbag.rst, source/_autosummary/ale.rst, source/_autosummary/battery.rst, source/_autosummary/boundary.rst, source/_autosummary/case.rst, source/_autosummary/cese.rst, source/_autosummary/change.rst, source/_autosummary/chemistry.rst, source/_autosummary/component.rst, source/_autosummary/constrained.rst, source/_autosummary/contact.rst, source/_autosummary/control.rst, source/_autosummary/controller.rst, source/_autosummary/cosim.rst, source/_autosummary/damping.rst, source/_autosummary/database.rst, source/_autosummary/define.rst, source/_autosummary/deformable.rst, source/_autosummary/delete.rst, source/_autosummary/dualcese.rst, source/_autosummary/ef.rst, source/_autosummary/element.rst, source/_autosummary/em.rst, source/_autosummary/eos.rst, source/_autosummary/fatigue.rst, source/_autosummary/frequency.rst, source/_autosummary/icfd.rst, source/_autosummary/iga.rst, source/_autosummary/include.rst, source/_autosummary/index.rst, source/_autosummary/initial.rst, source/_autosummary/integration.rst, source/_autosummary/interface.rst, source/_autosummary/keyword.rst, source/_autosummary/load.rst, source/_autosummary/lso.rst, source/_autosummary/mat.rst, source/_autosummary/mesh.rst, source/_autosummary/module.rst, source/_autosummary/node.rst, source/_autosummary/other.rst, source/_autosummary/parameter.rst, source/_autosummary/part.rst, source/_autosummary/particle.rst, source/_autosummary/perturbation.rst, source/_autosummary/rail.rst, source/_autosummary/rigid.rst, source/_autosummary/rigidwall.rst, source/_autosummary/rve.rst, source/_autosummary/section.rst, source/_autosummary/sensor.rst, source/_autosummary/set.rst
 
 # List of Packages to be used for our guidelines
 Packages = Google

doc/changelog/983.fixed.md

@@ -0,0 +1 @@
+Parameter substitution for all card types

src/ansys/dyna/core/lib/series_card.py

@@ -259,11 +259,11 @@ def _check_null(self, value) -> bool:
             return self._empty_struture(value)
         return self._check_null_by_type(value, self._type)
 
-    def _read_line(self, size, line):
+    def _read_line(self, size, line, parameter_set: ParameterSet = None):
         num_fields = self._num_fields()
         width = self._get_width()
         read_format = [(i * width * num_fields, width, self._type) for i in range(size)]
-        values = load_dataline(read_format, line)
+        values = load_dataline(read_format, line, parameter_set)
         if len(values) == 0:
             raise ValueError(f"Failed to read any values from line: {line}")
         last_real_index = -1
@@ -276,19 +276,19 @@ def _read_line(self, size, line):
         values = values[: last_real_index + 1]
         return values
 
-    def _load_bounded_from_buffer(self, buf: typing.TextIO) -> None:
+    def _load_bounded_from_buffer(self, buf: typing.TextIO, parameter_set: ParameterSet = None) -> None:
         num_lines = self._num_rows()
         for index in range(num_lines):
             line, exit_loop = read_line(buf)
             if exit_loop:
                 break
             start, end = self._get_card_range(index)
             size = end - start
-            values = self._read_line(size, line)
+            values = self._read_line(size, line, parameter_set)
             for j, value in zip(range(start, end), values):
                 self[j] = value
 
-    def _load_unbounded_from_buffer(self, buf: typing.TextIO) -> None:
+    def _load_unbounded_from_buffer(self, buf: typing.TextIO, parameter_set: ParameterSet = None) -> None:
         width = self._get_width()
         self._initialize_data(0)
         while True:
@@ -305,16 +305,15 @@ def _load_unbounded_from_buffer(self, buf: typing.TextIO) -> None:
                 print("Trailing spaces, TODO - write a test!")
                 line = line + " " * trailing_spaces
             max_amount = min(size, self._get_fields_per_card())
-            values = self._read_line(max_amount, line)
+            values = self._read_line(max_amount, line, parameter_set)
             self.extend(values)
 
     def read(self, buf: typing.TextIO, parameter_set: ParameterSet = None) -> bool:
-        # parameter sets are ignored for series cards
         if self.bounded:
-            self._load_bounded_from_buffer(buf)
+            self._load_bounded_from_buffer(buf, parameter_set)
             return False
         else:
-            self._load_unbounded_from_buffer(buf)
+            self._load_unbounded_from_buffer(buf, parameter_set)
             return True
 
     def _get_lines(self, format: typing.Optional[format_type], comment: bool) -> typing.List[str]:

src/ansys/dyna/core/lib/table_card.py

@@ -218,11 +218,9 @@ def _get_fields(self) -> typing.List[Field]:
         return fields
 
     def _load_bounded_from_buffer(self, buf: typing.TextIO, parameter_set: ParameterSet) -> None:
-        read_options = self._get_read_options()
-        read_options["nrows"] = self._num_rows()
-        df = pd.read_fwf(buf, **read_options)
-        self._table = df
-        self._initialized = True
+        # For bounded cards, read all lines and use same logic as unbounded
+        data_lines = buffer_to_lines(buf, self._num_rows())
+        self._load_lines(data_lines, parameter_set)
 
     def _load_unbounded_from_buffer(self, buf: typing.TextIO, parameter_set: ParameterSet) -> None:
         data_lines = buffer_to_lines(buf)
@@ -237,14 +235,44 @@ def read(self, buf: typing.TextIO, parameter_set: ParameterSet = None) -> None:
             self._initialized = True
             self._load_unbounded_from_buffer(buf, parameter_set)
 
-    def _load_lines(self, data_lines: typing.List[str], parameter_set: ParameterSet) -> None:
+    def _has_parameters(self, data_lines: typing.List[str]) -> bool:
+        """Check if any data lines contain parameter references."""
+        return any("&" in line for line in data_lines)
+
+    def _load_lines_with_parameters(self, data_lines: typing.List[str], parameter_set: ParameterSet) -> None:
+        """Load lines using load_dataline for parameter support.
+
+        This method processes each line individually using load_dataline(),
+        which handles parameter substitution. It's used when parameters are
+        detected in the data.
+        """
+        from ansys.dyna.core.lib.kwd_line_formatter import load_dataline
+
         fields = self._get_fields()
-        buffer = io.StringIO()
-        [(buffer.write(line), buffer.write("\n")) for line in data_lines]
-        buffer.seek(0)
-        self._table = self._read_buffer_as_dataframe(buffer, fields, parameter_set)
+        format_spec = [(f.offset, f.width, f.type) for f in fields]
+
+        rows = []
+        for line in data_lines:
+            values = load_dataline(format_spec, line, parameter_set)
+            row_dict = {field.name: value for field, value in zip(fields, values)}
+            rows.append(row_dict)
+
+        self._table = pd.DataFrame(rows)
         self._initialized = True
 
+    def _load_lines(self, data_lines: typing.List[str], parameter_set: ParameterSet) -> None:
+        # Use parameter-aware loading if parameters are present
+        if parameter_set is not None and self._has_parameters(data_lines):
+            self._load_lines_with_parameters(data_lines, parameter_set)
+        else:
+            # Use fast pandas path when no parameters present
+            fields = self._get_fields()
+            buffer = io.StringIO()
+            [(buffer.write(line), buffer.write("\n")) for line in data_lines]
+            buffer.seek(0)
+            self._table = self._read_buffer_as_dataframe(buffer, fields, parameter_set)
+            self._initialized = True
+
     def write(
         self,
         format: typing.Optional[format_type] = None,