Nonlinear Fit Demo — GX-TXT Documentation

Indice

Reference/demo

Questa pagina descrive un modulo dimostrativo. Per il normale catalogo degli strumenti vai a Moduli numerici; per le firme delle primitive vai a NUMERIC_API_v1.

1. Module overview

Plugin ID: demo.numeric.nonlinear_fit
Plugin version: 1.0.3
Plugin name in GX-TXT: Nonlinear fit integration demo
Group: Generic analysis / Numerical examples
Reference framework: GX-TXT 0.9.7.72 or later compatible release
License: GNU GPL v3 or later

This external plugin demonstrates nonlinear least-squares fitting through the public GX-TXT numerical architecture.

Its canonical teaching input comes from:

Library: GX-TXT Numerical Examples
Category: Mathematics
Generator: Nonlinear Fitting

The complete workflow is:

Session Generator
→ normal GX-TXT Session
→ generated nonlinear_fitting.csv
→ import CSV into the current Session as a canonical Dataset
→ select Dataset in the plugin
→ bind x and y
→ NUMERIC_API_v1 nonlinear fit
→ published Dataset demo.nonlinear.fit
→ rendered fit graph

The Session directory name is not part of the plugin contract.

2. Why a CSV import step is required in GX-TXT 0.9.7.72

The Nonlinear Fitting Session Generator creates scientific source files:

raw/nonlinear_fitting.csv
metadata/ground_truth.txt

It does not register nonlinear_fitting.csv as a canonical Dataset.

GX-TXT 0.9.7.72 standard_octave analysis modules require an already registered Dataset before their runtime can be generated. Therefore a pure external analysis plugin cannot create its own first Dataset before Run without a framework change.

For that reason version 1.0.3 uses the normal supported workflow:

Generated CSV
→ acq.generic_csv incremental import
→ canonical Dataset
→ analysis plugin

This is why the import step below is necessary.

Version 1.0.0 was worse: it additionally required the exact Dataset ID demo.nonlinear.source, but did not expose a normal GUI procedure for creating it. Version 1.0.3 removes that hard-coded ID requirement.

3. Required GX-TXT version and numerical service

The plugin was developed against:

GX-TXT 0.9.7.72

It depends on the bundled CORE numerical service:

math.numeric

and uses:

NUMERIC_API_v1

The numerical backend is GX-TXT’s normal standard_octave environment.

The plugin package does not modify GX-TXT CORE.

4. Create the canonical example Session

Start GX-TXT.
Press the top-bar button:
```
New Session
```
In the New Session window verify:
```
Session root:
Session name:
```
Press:
```
Generate Session...
```

In the generator tree choose:

GX-TXT Numerical Examples
└── Mathematics
    └── Nonlinear Fitting

Enter any valid Session name.
Press:
```
Generate Session
```

GX-TXT creates and opens the Session.

The suggested name nonlinear-fitting-example is only a suggestion. The plugin works with any valid Session name.

5. Generated scientific files

The generator creates:

raw/nonlinear_fitting.csv
metadata/ground_truth.txt

5.1 CSV structure

The CSV header is:

x,y

The generator creates 51 rows. The independent variable is:

x = i × 0.12

for i = 0 ... 50.

The observation model is:

y = A exp(-k x) + c + noise

5.2 Ground truth

The reference file contains:

A=4.2
k=0.65
c=0.35
noise=Gaussian sigma 0.03
seed=1973

The deterministic seed makes the example reproducible.

6. Import the generated CSV into the current Session

This is the important step that was not explained by plugin version 1.0.0.

Keep the generated Session open.

6.1 Select the generic CSV importer

Go to the Acquisition tab and choose:

Import module = acq.generic_csv

6.2 Use the multi-CSV table

In:

Multi-CSV canonical dataset import (v0.8.2)

activate:

Use batch table

Then press:

+ Add CSV

Select the file inside the current generated Session:

raw/nonlinear_fitting.csv

6.3 Dataset ID

GX-TXT proposes a Dataset ID from the filename. You may keep the proposed ID or choose another valid Dataset ID.

For example:

nonlinear_fitting

or:

demo.nonlinear.source

The plugin no longer requires either exact value.

6.4 Dataset contract

Use a normal flat-table contract accepted by the module:

table.generic

or:

timeseries.table

table.generic is the more natural choice because x is an arbitrary numerical coordinate rather than elapsed time.

6.5 Variable mapping

Use Variables if necessary and preserve the canonical variable names:

x

y

6.6 Import into the already open Session

Because the Session already exists, do not create a second Session.

Use:

Import enabled pending into current session

After successful import, the Dataset is registered in the current Session and becomes available to analysis modules.

7. Install the plugin

Package filename:

demo.numeric.nonlinear_fit_1.0.3.zip

Open the Modules tab.
Press:
```
Install plugin...
```
Select the ZIP package.

Confirm that the installed module appears as:

Nonlinear fit integration demo

under:

Generic analysis / Numerical examples

The package is managed by Plugin Install API v1 and can later be updated or uninstalled normally.

8. Enable the plugin

The Modules tab is the installed-plugin catalog and controls experiment membership.

Enable:

Nonlinear fit integration demo

Then open the Analysis tab.

GX-TXT creates the module’s analysis panel there.

9. Select the primary Dataset source

Version 1.0.3 uses the GX-TXT Analysis Source Map API v1. This is important: the Dataset selector and the variable-binding selectors now belong to the same framework-owned source map.

In the module’s Analysis panel locate:

Dataset sources (Analysis Source Map API v1)

The module declares one required source:

primary

Select the canonical Dataset created from raw/nonlinear_fitting.csv in section 6. For the standard example it will normally be named:

nonlinear_fitting

but any valid Dataset ID is accepted. The Dataset does not have to be named demo.nonlinear.source.

After selecting the Dataset, GX-TXT refreshes the binding choices from that Dataset.

10. Configure X and Y bindings

The module declares two required GX-TXT bindings. For the canonical generated example choose exactly:

X variable (choose primary.x for the generated example) = primary.x
Y variable (choose primary.y for the generated example) = primary.y

The primary. prefix is the Analysis Source Map source identity. The runtime removes that prefix only to obtain the selected source token, then resolves it through gxtxt_analysis_source_variable_meta(). The resolved stable variable_id values are what the plugin passes to NUMERIC_API_v1 and Table Stream API. The canonical names shown in the GUI (x and y) are preserved separately for human-readable reports.

If the binding comboboxes show only auto, the primary Dataset has not yet been selected. Select the Dataset in the Dataset sources section first; the choices should then include primary.x and primary.y.

11. Run the module

In the Analysis tab enable the module’s normal run selector:

Run / recalculate this module

Then execute the normal analysis Run workflow.

A successful run performs:

selected canonical Dataset
→ selected x/y variables
→ NUMERIC_API_v1 dataset_nonlinear_fit
→ parameter validation
→ demo.nonlinear.fit publication
→ fit_report.txt
→ fit_metrics.ini
→ render_cache.mat
→ 01_nonlinear_fit.png

No Tcl command is required.

12. Mathematical background

The fitted model is:

y(x) = A exp(-k x) + c

where:

A is the exponential amplitude;
k is the decay constant;
c is the asymptotic offset.

The module uses initial parameter values:

A = 4.0
k = 0.5
c = 0.2

and requests numerical optimizer tolerance:

1e-9

Because the generator adds Gaussian noise, the fitted parameters are not expected to equal the generator values exactly.

13. Expected numerical result

Reference parameters:

A = 4.2
k = 0.65
c = 0.35

Validation limits:

|A_fit - 4.2|  <= 0.10
|k_fit - 0.65| <= 0.05
|c_fit - 0.35| <= 0.08

These limits account for the deterministic observation noise and are separate from the optimizer convergence tolerance.

If the recovered parameters exceed these limits, the module fails explicitly.

14. Output Dataset

The plugin publishes:

Dataset ID: demo.nonlinear.fit
Contract: table.generic

Variables:

x
measured
fitted

The published Dataset records the selected input Dataset and selected source variable IDs as provenance.

x is the output coordinate, measured is the source observation, and fitted is the predicted value returned by NUMERIC_API_v1.

15. Reports

`fit_metrics.ini`

Contains:

source_dataset_id
x_variable
y_variable
derived_dataset_id
expected / recovered / error / tolerance for A, k, c
solver
converged
sse
rmse
r_squared
noise
seed

`fit_report.txt`

Human-readable summary of the same scientific result.

16. Plot

The plugin exposes the Graph Provider graph:

Graph ID: demo.nonlinear.fit.curve
Name: Generated observations and nonlinear fit
Artifact: 01_nonlinear_fit.png

It contains:

generated observations as markers;
fitted exponential curve as a line.

The plot uses normal GX-TXT graphics settings, standard legend handling, and atomic PNG export.

A correct graph should show a smooth exponential decay passing through the central trend of the noisy observations and approaching the fitted offset at large x.

render_cache.mat permits plot rerendering without repeating the numerical fit.

17. Reproducibility

The Session Generator uses:

seed=1973

with fixed reference values:

A=4.2
k=0.65
c=0.35

Therefore a newly generated Nonlinear Fitting example in GX-TXT 0.9.7.72 contains the same source observations.

The plugin does not read files from the installed Session Generator Library. It uses only the generated Session and the canonical Dataset imported from that Session.

18. Troubleshooting

18.1 The plugin shows no usable primary Dataset

The generated CSV has not yet been imported as a canonical Dataset.

Return to section 6 and use:

acq.generic_csv
→ Use batch table
→ + Add CSV
→ raw/nonlinear_fitting.csv
→ Import enabled pending into current session

18.2 Do I have to call my Session `nonlinear-fitting-example`?

No. The Session name is irrelevant.

18.3 Does the Dataset have to be called `demo.nonlinear.source`?

No. Version 1.0.3 accepts any compatible Dataset selected as the primary Analysis Source.

18.4 Which variables do I select?

For the canonical generated example:

X variable = primary.x
Y variable = primary.y

If only auto is available, select the primary Dataset first. GX-TXT then populates the binding selectors from the selected Dataset.

18.5 `metadata/ground_truth.txt is missing`

The currently open Session was not generated by the canonical Nonlinear Fitting Session Generator, or that metadata file was removed.

18.6 `NUMERIC_API_v1 is unavailable`

The required math.numeric public numerical service is unavailable or the framework installation is incompatible.

18.7 Fit outside reference tolerances

The numerical fit ran but the recovered parameters do not agree with the known deterministic example within the documented limits. Treat this as a real validation failure.

18.8 Plot not rendered

Verify that the graph is enabled in the module Analysis panel and that the GX-TXT graphics backend can render normal module plots.

19. Public GX-TXT APIs used

The plugin uses:

Standard Module API v1
Plugin Install API v1
Dataset / standard runtime selection
Table Stream API through public Octave helpers
NUMERIC_API_v1
Dataset Publication API v2 standard_octave binding
Graph Provider API v1
Plot Module API v1

It does not edit metadata/datasets.ini directly.

20. Package contents

plugin-package.ini
module.ini
README.md
MANUAL.md
CHANGELOG.md
TEST_RESULTS.md
runtime/
    demo_numeric_nonlinear_fit.m
    demo_numeric_nonlinear_fit_main.m
    demo_numeric_nonlinear_fit_render.m
    demo_numeric_nonlinear_fit_rerender.m
    demo_numeric_nonlinear_fit_rerender_main.m
tests/
    test_package.tcl

21. Complete practical procedure

For quick reference, the entire normal GUI procedure is:

New Session
→ Generate Session...
→ GX-TXT Numerical Examples
→ Mathematics
→ Nonlinear Fitting
→ Generate Session

Acquisition
→ Import module = acq.generic_csv
→ Use batch table
→ + Add CSV
→ choose raw/nonlinear_fitting.csv
→ use table.generic
→ preserve x,y variable names
→ Import enabled pending into current session

Modules
→ Install plugin...
→ demo.numeric.nonlinear_fit_1.0.3.zip
→ enable Nonlinear fit integration demo

Analysis
→ Dataset sources (Analysis Source Map API v1)
→ primary = imported nonlinear fitting Dataset
→ X variable = primary.x
→ Y variable = primary.y
→ Run / recalculate this module
→ execute normal analysis Run

Results
→ demo.nonlinear.fit
→ fit_report.txt / fit_metrics.ini
→ Generated observations and nonlinear fit graph

That is the supported version 1.0.3 workflow on GX-TXT 0.9.7.72.

Version 1.0.3 includes both integration fixes required by the real GUI workflow:

the earlier Analysis Source Map change makes primary.x and primary.y selectable from the Dataset;
version 1.0.3 additionally resolves those canonical binding tokens to the stable Dataset variable_id values required by NUMERIC_API_v1 and Table Stream API.

This second distinction matters because an imported Dataset may display canonical variables named x and y while internally using stable IDs such as v0001 and v0002.