Projects, Experiments e Sessions

Versione verificata

1. I tre livelli in una frase

2. Project: il contenitore organizzativo persistente

Un Project è una entità persistente sopra gli Experiments. Ha un project_id stabile indipendente dal nome modificabile e può contenere metadata come nome, descrizione, tags, autore, data di creazione e aggiornamento.

Il registry autorevole dei Projects è user-local e segue la configurazione XDG/home del framework. La dev-031 mantiene anche uno storage stabile del Project con un piccolo project.ini e una directory Sessions/.

3. Experiment: identità scientifica e notebook

L'Experiment rappresenta lo studio/esperimento descritto nella Session. Il Manifest Format 2 conserva campi come:

name
date
operator
tags
notes
objective
procedure
observations

La dev-031 assegna inoltre un experiment_id stabile. Il Project membership usa questo ID, non il nome visibile e non il path della Session.

Informazioni specifiche degli strumenti appartengono agli Instrument Module instances; le variabili scientifiche appartengono ai Dataset/Variable Schema. L'Experiment rimane il livello descrittivo del lavoro.

4. Session: il record operativo e portabile

La Session conserva configurazione, Dataset, source files, note, script registrati, output Analysis, plots, Viewer state e provenance. Il suo metadata/manifest.ini contiene sia la sezione [experiment] sia il collegamento persistente al Project.

[project_link]
api_version=1
experiment_id=experiment-...
project_id=project-...
legacy_project=

Il path della Session viene registrato anche nel Project membership per consentire la navigazione. Non sostituisce però experiment_id.

5. Perché il Session path non è l'identità dell'Experiment

Una Session può essere spostata. Quando una Session collegata a un Project viene riaperta, GX-TXT può aggiornare il “last known Session path” nel membership index usando l'experiment_id stabile.

Questo permette di distinguere:

• identità: l'Experiment continua ad essere lo stesso;
• localizzazione: la directory dalla quale quella Session è stata aperta può cambiare.

6. Creare una nuova Session dentro un Project

Nella dev-031 la creazione di una nuova Session può ricevere direttamente un projectId. In questo caso la Session viene creata sotto lo storage stabile del Project:

<Session/Project root>/
└── <project_id>/
    ├── project.ini
    └── Sessions/
        └── <session_name>/
            ├── metadata/
            ├── analysis/
            ├── raw/
            └── ...

GX-TXT genera contestualmente un nuovo experiment_id, imposta il project_id nel manifest e registra l'Experiment nel membership del Project.

7. Associare una Session esistente a un Project

È un'operazione diversa dalla creazione “dentro” il Project. Quando la Session esiste già, Associate current Session... crea/aggiorna il collegamento logico fra l'Experiment corrente e il Project scelto.

La directory esistente non viene spostata e i dati non vengono copiati. Il membership registra il path corrente per consentire di riaprire la Session dal Project.

8. GUI corrente: Experiment e Projects

8.1 Nella scheda Experiment

La riga Project espone:

• Associate current Session... — sceglie un Project persistente e collega l'Experiment corrente;
• New... — crea un nuovo Project; con una Session aperta lo associa anche all'Experiment corrente;
• Edit... — modifica metadata del Project selezionato;
• Experiments... — mostra gli Experiments appartenenti al Project e permette di aprire la Session registrata;
• Detach Session — rimuove la membership senza cancellare dati.

8.2 Nel tab Projects

Il tab Projects è una proiezione dello stesso backend persistente. Mostra la lista dei Projects, metadata del Project selezionato, gli Experiments associati e consente di navigare alle Session quando il path registrato è disponibile.

9. Detach è non distruttivo

Detach Session rimuove il collegamento fra l'experiment_id e il Project. Non cancella:

• la Session;
• RAW source;
• Dataset;
• analisi e risultati;
• plots o Viewer state;
• script o provenance.

La GUI chiede esplicitamente conferma specificando che nessun dato scientifico verrà eliminato.

10. Modificare il nome del Project non ne cambia l'identità

Il nome è metadata editabile. La membership usa project_id. Rinominare un Project non richiede di rinominare gli Experiments né le Session e non cambia le identità scientifiche.

Analogamente, la lista degli Experiments usa experiment_id come autorità; nome e Session path servono alla presentazione e alla navigazione.

11. Legacy Project text

I manifest storici potevano contenere soltanto experiment.project come testo libero. La dev-031 non interpreta automaticamente quel testo come una identità Project persistente.

Quando l'utente associa esplicitamente l'Experiment a un Project moderno, il vecchio testo può essere conservato in legacy_project. In questo modo una semplice coincidenza di nomi non crea una membership non richiesta.

12. Registry Project e manifest Session devono restare allineati

La relazione è registrata in due punti con ruoli diversi:

Il salvataggio e l'apertura della Session sincronizzano il collegamento attraverso le API di Project. Non è necessario modificare manualmente nessuno dei due file.

13. Esempio: progetto con più Experiments

Project: Catalytic mesh reactor
project_id = project-...

├── Experiment A
│   experiment_id = experiment-A...
│   Session = CFD_simple_mesh
│   Datasets = mesh + pressure + velocity
│
├── Experiment B
│   experiment_id = experiment-B...
│   Session = CFD_SEM_reference
│   Datasets = detailed geometry + CFD results
│
└── Experiment C
    experiment_id = experiment-C...
    Session = laboratory_measurements
    Datasets = chromatography + UV + pH + temperature

Le tre Session possono essere navigate dallo stesso Project senza mescolare i loro Dataset registry o la loro provenance.

14. Project, Dataset e risorse Session: cosa appartiene a cosa

15. Cosa succede con Portable Session

Una Session esportata mantiene le proprie identità scientifiche e il link Project presente nel manifest. Il package portabile conserva il record Session; il Project registry user-local non viene trasformato in un secondo contenitore dati dentro ogni archivio.

Dopo la relocazione, aprire la Session permette al framework di aggiornare le informazioni di navigazione legate all'experiment_id quando il relativo Project è disponibile.

16. Regole pratiche

• Usa il Project per raggruppare lavori correlati, non per duplicare Dataset.
• Considera project_id e experiment_id le identità persistenti; nomi e path possono cambiare.
• Se vuoi che una nuova Session viva fisicamente sotto un Project, sceglilo al momento della creazione.
• Se la Session esiste già, associa l'Experiment: non serve spostarla.
• Usa Detach per rimuovere l'organizzazione, non per cancellare risultati.
• Non modificare manualmente projects.ini o [project_link] durante il normale uso.

17. Guide collegate

• Introduzione a GX-TXT — architettura generale.
• Session Explorer e risorse — contenuto operativo della Session.
• Dataset e Variable ID — identità dei dati dentro la Session.
• Octave & Python Script Workspaces — script Session-owned.