# Reuse a parameterised subcircuit from an included library

Define the cell pin order and a named parameter, reference that parameter inside the cell, then set it on the intended X instance. Keep the library beside the main deck and inspect instance-specific output.

## Compatibility

2.9.0 release target; bounded Windows RC CLI evidence

Published guidance with release-applicability limits. Confirm package applicability before following this guide.

**KB-DOC-002 · supported path**: Use a named parameter that the subcircuit actually consumes, then verify the instance response. An instance argument does not override an unrelated literal component value.

[Download Parameterised RC cells (ZIP)](/_functions/kbExample?name=rc-hierarchy.zip)

Includes: rc_cell.cir, rc_hierarchy.cir, README.txt.

## Save the reusable cell as rc_cell.cir

The public pins are A then Z. RVAL has a default of 50 and is actually used by the R1 value expression. Node 0 remains the circuit reference. .ENDS RC_CELL closes the definition; the main deck owns the run and final .END.

```text
* Reusable RC cell: pin order is input, output
.SUBCKT RC_CELL A Z RVAL=50
R1 A Z RVAL
C1 Z 0 0.2p
.ENDS RC_CELL
```

## Save the main deck as rc_hierarchy.cir

Put both files in the same writable folder. The X1 and X2 pin order matches A,Z. X1 uses RVAL=50 by default; X2 sets RVAL=100. With the shared 0.2 pF capacitance their time constants are 10 ps and 20 ps.

The requested I(R1.X1) selects R1 inside instance X1. The checked CSV labels that expanded trace I(R1|X1). Preserve the actual exported header rather than assuming a dot remains in the label. Nested references require the complete hierarchy path.

```text
* Two RC instances; the second overrides the cell resistor
.INCLUDE "rc_cell.cir"
.PARAM DRIVE=1m
V1 IN 0 PWL(0 0 10p 0 20p DRIVE 100p DRIVE)
X1 IN OUT50 RC_CELL
X2 IN OUT100 RC_CELL RVAL=100
.OPTION ANALYSIS=VOLTAGE INTEGRATION=BDF
.TRAN 0.25p 100p
.PRINT V(OUT50) V(OUT100) I(R1.X1)
.END
```

## Run and compare the instances

1. Run from the project folder and inspect the current job status and output file.
2. Check V(OUT50), V(OUT100) and the instance-specific R1 current. The checked run has 401 finite samples over 0–100 ps.
3. Compare the two responses with the RC reference using tau=10 ps and tau=20 ps. The higher-resistance cell charges more slowly; it should not produce an identical output trace.

```text
josim-pro-cli -o rc_hierarchy.csv rc_hierarchy.cir
```

## A named argument must be used by the cell

On the checked runtime, adding R1=100 to an X instance did not change a literal R1 A Z 50 line. Both cell outputs remained identical. The older syntax example is therefore tracked for clarification under KB-DOC-002.

Use the explicit RVAL pattern shown above: declare its default, use RVAL as the element value, then supply RVAL=100 on the selected instance. This route changed the response as expected in the check. Do not infer that naming a component in an instance argument edits every literal value with that name.

## Recover an include or mapping problem

If the library is missing, inspect the .INCLUDE path relative to the saved project and restore the complete file or correct the reference. The checked missing_cell.cir reference was rejected without CSV; correcting it to rc_cell.cir restored the expected response.

If a cell parses but behaves unexpectedly, compare the .SUBCKT pin list, X-instance pin order, selected cell name, parameter declaration and the expression that consumes the parameter. Keep separate output names while comparing the corrected runs.

## Sources and verification details

Recorded inputs/builds only. Complete walkthrough and final-package acceptance remain separate.

- VAL-014: JoSIM-Pro 2.9.0 installed Windows review CLI. Complete linear RC circuit, included parameterised cell, include recovery, fixed-step refinement, nine scalar forms and measurement failure/recovery Handwritten RC examples and their declared analytic criteria only. No Josephson-device, adaptive/noisy, GUI, other-platform or final-release qualification. CLI loaded-library path was not observed.


- josim-pro:docs/manual_source/sections/syntax.tex: Parameter definition, subcircuits, includes and hierarchical output references
- josim-pro:lib/src/input.cpp: Named subcircuit defaults and declaration parsing; bounded source review
- josim-pro:docs/manual_source/sections/usage.tex: CLI input/output and versioned execution contract
- validation:josim-authoring-windows-20261103: VAL-014: exact RC examples, independent reference checks and recovery

- The documented RC files match the checked input content. All new outputs were written to fresh paths.
- Final distributed 2.9 package, other platforms and GUI workflows remain pending. Example-specific analytic allowances are not universal solver tolerances.
- KB-DOC-002 retains the literal-component override documentation ambiguity. The checked guide uses a parameter explicitly consumed by the cell.
- 4 November targeted UTF-8 path delta review: current binding/input changes preserve this guide's ASCII named-output or subcircuit/default claims. Retained execution predates these changes; Unicode input/path and final-package execution are not qualified. Evidence: validation/source-review-python-paths-20261104.json.

## Related guides

- [Write and run a complete JoSIM circuit netlist](/knowledge-base/josim-netlist-basics)
- [A JoSIM®-Pro netlist cannot find an included file](/knowledge-base/josim-missing-include)
- [Choose and refine simulation and output time steps](/knowledge-base/josim-transient-timestep)
- [Check a JoSIM workspace before running simulations](/knowledge-base/josim-workspace-diagnostics)
- [Find declarations, references and source locations](/knowledge-base/josim-editor-navigation)
- [Use completion, linked snippets and live diagnostics](/knowledge-base/josim-editor-completion)