Implementazione dello script Lua per il risolutore elettrico di Newton in OghmaNano.Implementazione dello script Lua per il risolutore elettrico di Newton in OghmaNano.

1. Introduzione1. Introduzione

OghmaNano include un’interfaccia di scripting Lua integrata che consente di modificare il risolutore numerico interno durante l’esecuzione. Ciò permette di ottenere un controllo avanzato, ad esempio attivando o disattivando equazioni, modificando il risolutore di Newton 3D, bloccando parametri fisici selezionati durante le transizioni o le scansioni J–V, oppure implementando strategie iterative personalizzate.OghmaNano include un’interfaccia di scripting Lua integrata che consente di modificare il risolutore numerico interno durante l’esecuzione. Ciò permette di ottenere un controllo avanzato, ad esempio attivando o disattivando equazioni, modificando il risolutore di Newton 3D, bloccando parametri fisici selezionati durante le transizioni o le scansioni J–V, oppure implementando strategie iterative personalizzate.

Questo approccio si distingue dall’uso di script esterni. Linguaggi come Python funzionano modificando sim.json e avviando il risolutore, il che li rende particolarmente adatti per l’esecuzione di analisi parametriche, l’elaborazione di batch e le operazioni di post-elaborazione.Questo approccio si distingue dall’uso di script esterni. Linguaggi come Python funzionano modificando sim.json e avviando il risolutore, il che li rende particolarmente adatti per l’esecuzione di analisi parametriche, l’elaborazione di batch e le operazioni di post-elaborazione.

Al contrario, Lua opera all’interno del risolutore, consentendo un intervento diretto nel flusso di lavoro numerico senza dover modificare il codice C sottostante.Al contrario, Lua opera all’interno del risolutore, consentendo un intervento diretto nel flusso di lavoro numerico senza dover modificare il codice C sottostante.

2. Cos'è Lua?2. Cos'è Lua?

Lua è un linguaggio di scripting leggero e ad alte prestazioni, progettato per essere integrato all’interno di applicazioni più ampie. È ampiamente utilizzato in settori quali motori di gioco e software scientifico, dove è necessario modificare il comportamento interno senza dover ricompilare il codice principale. Rispetto a Python, Lua ha un ingombro molto minore e richiede meno risorse in fase di esecuzione, il che lo rende più adatto all’esecuzione all’interno di cicli in cui le prestazioni sono fondamentali. Rispetto a C, è significativamente più facile da scrivere e modificare, pur offrendo un controllo preciso sul comportamento del programma. Queste caratteristiche rendono Lua particolarmente adatto a OghmaNano, dove viene utilizzato per influenzare direttamente il risolutore numerico durante l’esecuzione.Lua è un linguaggio di scripting leggero e ad alte prestazioni, progettato per essere integrato all’interno di applicazioni più ampie. È ampiamente utilizzato in settori quali motori di gioco e software scientifico, dove è necessario modificare il comportamento interno senza dover ricompilare il codice principale. Rispetto a Python, Lua ha un ingombro molto minore e richiede meno risorse in fase di esecuzione, il che lo rende più adatto all’esecuzione all’interno di cicli in cui le prestazioni sono fondamentali. Rispetto a C, è significativamente più facile da scrivere e modificare, pur offrendo un controllo preciso sul comportamento del programma. Queste caratteristiche rendono Lua particolarmente adatto a OghmaNano, dove viene utilizzato per influenzare direttamente il risolutore numerico durante l’esecuzione.

Per darvi un’idea di come funziona Lua, nel caso non abbiate mai programmato in questo linguaggio, ecco un esempio di implementazione dell’algoritmo classico del bubble sort.Per darvi un’idea di come funziona Lua, nel caso non abbiate mai programmato in questo linguaggio, ecco un esempio di implementazione dell’algoritmo classico del bubble sort.

a = {5, 3, 8, 1, 2}
n = #a
for i = 1, n do
  for j = 1, n - i do
    if a[j] > a[j+1] then
      a[j], a[j+1] = a[j+1], a[j]
    end
  end
end

2. Come accedere all’editor di script Lua2. Come accedere all’editor di script Lua

L’editor di script Lua è accessibile dalla barra multifunzione principale, come illustrato in ??. Cliccare sulla piccola freccia a discesa accanto al controllo del risolutore per equazioni di deriva-diffusione per aprire il menu, mostrato in ??. Quindi, cliccare su «Modifica microcodice» per aprire l’editor Lua, mostrato in ??.L’editor di script Lua è accessibile dalla barra multifunzione principale, come illustrato in ??. Cliccare sulla piccola freccia a discesa accanto al controllo del risolutore per equazioni di deriva-diffusione per aprire il menu, mostrato in ??. Quindi, cliccare su «Modifica microcodice» per aprire l’editor Lua, mostrato in ??.

Premere Ctrl+S per salvare lo script oppure utilizzare il pulsante di salvataggio nella barra degli strumenti dell’editor. Per attivare il microcodice, è necessario premere il pulsante di attivazione, come mostrato in ??.Premere Ctrl+S per salvare lo script oppure utilizzare il pulsante di salvataggio nella barra degli strumenti dell’editor. Per attivare il microcodice, è necessario premere il pulsante di attivazione, come mostrato in ??.

3. Un esempio semplice: celle solari a perovskite con ioni immobilizzati.3. Un esempio semplice: celle solari a perovskite con ioni immobilizzati.

Un esempio semplice di utilizzo dello scripting Lua si trova nella simulazione di dispositivi a base di perovskite, dove potrebbe essere necessario bloccare gli ioni mobili durante una scansione della curva corrente-tensione (J–V). Le perovskiti contengono ioni mobili che si spostano relativamente lentamente. In fase sperimentale, un dispositivo viene spesso mantenuto inizialmente a una polarizzazione negativa, in modo che gli ioni si dispongano in una particolare configurazione, e quindi viene eseguita una scansione J–V molto rapida prima che abbiano il tempo di reagire in modo significativo.Un esempio semplice di utilizzo dello scripting Lua si trova nella simulazione di dispositivi a base di perovskite, dove potrebbe essere necessario bloccare gli ioni mobili durante una scansione della curva corrente-tensione (J–V). Le perovskiti contengono ioni mobili che si spostano relativamente lentamente. In fase sperimentale, un dispositivo viene spesso mantenuto inizialmente a una polarizzazione negativa, in modo che gli ioni si dispongano in una particolare configurazione, e quindi viene eseguita una scansione J–V molto rapida prima che abbiano il tempo di reagire in modo significativo.

In OghmaNano, quando viene attivato il modello degli ioni di perovskite, il risolutore elettrico consente normalmente agli ioni di stabilizzarsi a ogni passo di tensione. Questo equivale a una scansione della curva corrente-tensione (J–V) molto lenta o quasi in stato stazionario. Questo può essere utile in alcuni casi, ma non riproduce gli esperimenti in cui la tensione viene variata molto più rapidamente. Per simulare questo tipo di misurazione, è possibile utilizzare lo script Lua riportato di seguito per bloccare gli ioni all'inizio del ciclo elettrico principale. La simulazione può comunque raggiungere la tensione iniziale richiesta nel modo consueto, consentendo agli ioni di muoversi durante la fase di preparazione, ma una volta avviato il ciclo principale, l'equazione degli ioni viene disattivata.In OghmaNano, quando viene attivato il modello degli ioni di perovskite, il risolutore elettrico consente normalmente agli ioni di stabilizzarsi a ogni passo di tensione. Questo equivale a una scansione della curva corrente-tensione (J–V) molto lenta o quasi in stato stazionario. Questo può essere utile in alcuni casi, ma non riproduce gli esperimenti in cui la tensione viene variata molto più rapidamente. Per simulare questo tipo di misurazione, è possibile utilizzare lo script Lua riportato di seguito per bloccare gli ioni all'inizio del ciclo elettrico principale. La simulazione può comunque raggiungere la tensione iniziale richiesta nel modo consueto, consentendo agli ioni di muoversi durante la fase di preparazione, ma una volta avviato il ciclo principale, l'equazione degli ioni viene disattivata.

-- Initialise solver
a = dd_solver()
a.verbose = false              -- Suppress solver output

-- Apply logic only in the main electrical loop
if (a.problem_type & ELEC_PROB_MAIN_LOOP) ~= 0 then
    a.solve_nion = false       -- Disable ion equation (freeze ions)
    print("ion solver off")
else
    print("ion solver on")     -- Keep ions active during initialisation
end

a:run()                        -- Execute solver step

In questo esempio, viene innanzitutto creato l’oggetto solver e viene ridotta la quantità di informazioni di diagnostica generate. Lo script verifica quindi se la fase corrente del solver corrisponde al ciclo elettrico principale. In caso affermativo, l’equazione relativa agli ioni mobili viene disattivata impostando il valore di solve_nion=false, e quindi il solver viene eseguito utilizzando l’insieme di equazioni modificato. Un esempio di simulazione che utilizza questo approccio è disponibile tra gli esempi inclusi nel modello, nella sezione intitolata «Perovskite cells/Perovskite solar cell - frozen ions (MAPI)».In questo esempio, viene innanzitutto creato l’oggetto solver e viene ridotta la quantità di informazioni di diagnostica generate. Lo script verifica quindi se la fase corrente del solver corrisponde al ciclo elettrico principale. In caso affermativo, l’equazione relativa agli ioni mobili viene disattivata impostando il valore di solve_nion=false, e quindi il solver viene eseguito utilizzando l’insieme di equazioni modificato. Un esempio di simulazione che utilizza questo approccio è disponibile tra gli esempi inclusi nel modello, nella sezione intitolata «Perovskite cells/Perovskite solar cell - frozen ions (MAPI)».

5. Esempio: scansione ADI (Alternating-Direction Implicit).5. Esempio: scansione ADI (Alternating-Direction Implicit).

Un esempio più avanzato di scripting Lua è l’implementazione di una strategia a direzione alternata per risolvere problemi tridimensionali complessi. Questo approccio è strettamente legato al metodo implicito a direzione alternata (ADI), in cui un problema multidimensionale viene scomposto in una sequenza di problemi a dimensione inferiore.Un esempio più avanzato di scripting Lua è l’implementazione di una strategia a direzione alternata per risolvere problemi tridimensionali complessi. Questo approccio è strettamente legato al metodo implicito a direzione alternata (ADI), in cui un problema multidimensionale viene scomposto in una sequenza di problemi a dimensione inferiore.

In OghmaNano, questa idea può essere implementata direttamente a livello del risolutore, abilitando e disabilitando selettivamente gli accoppiamenti direzionali. Invece di risolvere l’intero sistema 3D accoppiato in un’unica operazione, il dominio viene analizzato alternando le direzioni. Questo può migliorare significativamente la stabilità e la convergenza per problemi complessi di trasporto-diffusione in 3D.In OghmaNano, questa idea può essere implementata direttamente a livello del risolutore, abilitando e disabilitando selettivamente gli accoppiamenti direzionali. Invece di risolvere l’intero sistema 3D accoppiato in un’unica operazione, il dominio viene analizzato alternando le direzioni. Questo può migliorare significativamente la stabilità e la convergenza per problemi complessi di trasporto-diffusione in 3D.

La strategia adottata consiste nel suddividere il problema tridimensionale in passaggi direzionali. Nel primo passaggio, il risolutore opera su sezioni lungo l’asse x, risolvendo l’intero problema lungo gli assi y e z e rimuovendo le interdipendenze lungo l’asse x. Nel secondo passaggio, il risolutore passa alle sezioni lungo l’asse z ed esegue l’operazione complementare. L’errore totale viene accumulato e utilizzato per definire un criterio di convergenza personalizzato.La strategia adottata consiste nel suddividere il problema tridimensionale in passaggi direzionali. Nel primo passaggio, il risolutore opera su sezioni lungo l’asse x, risolvendo l’intero problema lungo gli assi y e z e rimuovendo le interdipendenze lungo l’asse x. Nel secondo passaggio, il risolutore passa alle sezioni lungo l’asse z ed esegue l’operazione complementare. L’errore totale viene accumulato e utilizzato per definire un criterio di convergenza personalizzato.

L’esempio riportato di seguito illustra come sia possibile creare una scansione di questo tipo, basata sul modello ADI, utilizzando Lua:L’esempio riportato di seguito illustra come sia possibile creare una scansione di questo tipo, basata sul modello ADI, utilizzando Lua:

-- Initialise solver and control variables
a = dd_solver()
cont = true
count = 0

-- Main ADI-style iteration loop
while cont == true do

-- ===== X-slice pass =====
a.set_newton_state("x")      -- Use/store Newton state for x-pass
tot_error = 0.0

a.step_z = -1                -- Full domain in z
a.step_x = 1                 -- Slice-by-slice in x
a.step_y = -1                -- Full domain in y

a.solve_pos_x = false        -- Disable x-direction Poisson coupling
a.solve_pos_y = true
a.solve_pos_z = true

a.solve_je_x = 0             -- Disable x-direction electron current
a.solve_jh_x = 0             -- Disable x-direction hole current
a.solve_je_y = true
a.solve_jh_y = true
a.solve_je_z = true
a.solve_jh_z = true

a.solve_srh_e = true         -- Keep SRH recombination active
a.solve_srh_h = true

a.solve_nion = 0             -- Disable ions
a.solve_singlet = false      -- Disable excited-state physics

error = a:run()              -- Execute x-slice solve
tot_error = tot_error + error


-- ===== Z-slice pass =====
a.set_newton_state("z")      -- Switch to z-pass Newton state

a.step_z = 1                 -- Slice-by-slice in z
a.step_x = -1                -- Full domain in x
a.step_y = -1                -- Full domain in y

a.solve_pos_x = true
a.solve_pos_y = true
a.solve_pos_z = false        -- Disable z-direction Poisson coupling

a.solve_je_y = true
a.solve_jh_y = true
a.solve_je_x = true
a.solve_jh_x = true
a.solve_je_z = false         -- Disable z-direction transport
a.solve_jh_z = false

a.solve_srh_e = true
a.solve_srh_h = true
a.solve_nion = false
a.solve_singlet = false

error = a:run()              -- Execute z-slice solve
tot_error = tot_error + error


-- ===== Convergence logic =====
if (error < 1e-3) then       -- Local convergence check
    if (count > 2) then      -- Ensure minimum iterations
        cont = false
    end
end

print("count", count, "tot error:", error)

count = count + 1

if (tot_error < 1e-7) then   -- Global convergence criterion
    cont = false
end

if (count > 10) then         -- Safety iteration limit
    cont = false
end

end

In questa implementazione, vengono eseguite due passate direzionali all’interno di ogni iterazione. Nella prima passata, vengono disattivati i termini relativi al trasporto di Poisson e delle cariche nella direzione x, risolvendo di fatto il sistema a segmenti lungo l’asse x. Nella seconda passata, vengono disattivati i corrispondenti termini nella direzione z, ottenendo così una passata complementare.In questa implementazione, vengono eseguite due passate direzionali all’interno di ogni iterazione. Nella prima passata, vengono disattivati i termini relativi al trasporto di Poisson e delle cariche nella direzione x, risolvendo di fatto il sistema a segmenti lungo l’asse x. Nella seconda passata, vengono disattivati i corrispondenti termini nella direzione z, ottenendo così una passata complementare.

Per ogni direzione di calcolo vengono mantenuti stati di Newton separati, come indicato in set_newton_state(), il che consente al risolutore di conservare variabili interne indipendenti, quali il potenziale elettrostatico, le densità di portatori e i livelli di occupazione delle trappole.Per ogni direzione di calcolo vengono mantenuti stati di Newton separati, come indicato in set_newton_state(), il che consente al risolutore di conservare variabili interne indipendenti, quali il potenziale elettrostatico, le densità di portatori e i livelli di occupazione delle trappole.

La convergenza è controllata esplicitamente nello script Lua. Il ciclo termina quando una delle seguenti condizioni viene soddisfatta: l’errore e il numero di iterazioni per ogni passaggio superano una determinata soglia, l’errore accumulato scende al di sotto di una tolleranza specificata oppure viene raggiunto il numero massimo di iterazioni.La convergenza è controllata esplicitamente nello script Lua. Il ciclo termina quando una delle seguenti condizioni viene soddisfatta: l’errore e il numero di iterazioni per ogni passaggio superano una determinata soglia, l’errore accumulato scende al di sotto di una tolleranza specificata oppure viene raggiunto il numero massimo di iterazioni.

Questo esempio illustra come lo scripting Lua possa essere utilizzato per creare flussi di lavoro di risoluzione completamente personalizzati. Invece di affidarsi a uno schema numerico predefinito, l’utente può definire direttamente come viene scomposto il sistema multidimensionale, come vengono gestiti gli stati intermedi e come viene valutata la convergenza. Questo è particolarmente utile per simulazioni 3D complesse, in cui approcci completamente accoppiati potrebbero risultare instabili o inefficienti dal punto di vista computazionale.Questo esempio illustra come lo scripting Lua possa essere utilizzato per creare flussi di lavoro di risoluzione completamente personalizzati. Invece di affidarsi a uno schema numerico predefinito, l’utente può definire direttamente come viene scomposto il sistema multidimensionale, come vengono gestiti gli stati intermedi e come viene valutata la convergenza. Questo è particolarmente utile per simulazioni 3D complesse, in cui approcci completamente accoppiati potrebbero risultare instabili o inefficienti dal punto di vista computazionale.

3. L’oggetto dd_solver()3. L’oggetto dd_solver()

Il punto di accesso per il controllo tramite Lua del risolutore elettrico è l’oggetto dd_solver(). Questo consente di accedere direttamente al risolutore interno basato sui modelli di deriva-diffusione/Newton, permettendo di modificare sia l’insieme di equazioni sia la strategia di risoluzione durante l’esecuzione del programma.Il punto di accesso per il controllo tramite Lua del risolutore elettrico è l’oggetto dd_solver(). Questo consente di accedere direttamente al risolutore interno basato sui modelli di deriva-diffusione/Newton, permettendo di modificare sia l’insieme di equazioni sia la strategia di risoluzione durante l’esecuzione del programma.

In termini pratici, l’oggetto «solver» consente di eseguire tre operazioni fondamentali:In termini pratici, l’oggetto «solver» consente di eseguire tre operazioni fondamentali:

1. Verificare il contesto attuale del risolutore (ad esempio, il tipo di problema o la polarizzazione applicata).Verificare il contesto attuale del risolutore (ad esempio, il tipo di problema o la polarizzazione applicata).
2. È possibile abilitare o disabilitare singole equazioni e i relativi accoppiamenti direzionali.È possibile abilitare o disabilitare singole equazioni e i relativi accoppiamenti direzionali.
3. Eseguire un passo del risolutore e recuperare una metrica relativa alla convergenza o all’errore.Eseguire un passo del risolutore e recuperare una metrica relativa alla convergenza o all’errore.

I campi più utilizzati sono riassunti nella tabella ??.I campi più utilizzati sono riassunti nella tabella ??.

Oltre all’accesso ai campi, il risolutore mette a disposizione un numero limitato di metodi fondamentali:Oltre all’accesso ai campi, il risolutore mette a disposizione un numero limitato di metodi fondamentali:

8. Riepilogo8. Riepilogo

L’uso di script Lua in OghmaNano consente di controllare direttamente il risolutore interno per la diffusione e la deriva, offrendo all’utente la possibilità di modificare il sistema matematico in fase di esecuzione. A differenza degli approcci basati su script esterni, che operano sui file di input, Lua agisce all’interno del ciclo del risolutore e può quindi modificare le equazioni, gli accoppiamenti direzionali e il comportamento di convergenza in modo incrementale. Questa funzionalità è particolarmente utile in situazioni in cui la formulazione standard completamente accoppiata non è fisicamente appropriata o numericamente efficiente. Alcuni esempi includono il blocco dei gradi di libertà più lenti, come gli ioni mobili, o la scomposizione di problemi 3D complessi in passaggi direzionali utilizzando strategie di tipo ADI.L’uso di script Lua in OghmaNano consente di controllare direttamente il risolutore interno per la diffusione e la deriva, offrendo all’utente la possibilità di modificare il sistema matematico in fase di esecuzione. A differenza degli approcci basati su script esterni, che operano sui file di input, Lua agisce all’interno del ciclo del risolutore e può quindi modificare le equazioni, gli accoppiamenti direzionali e il comportamento di convergenza in modo incrementale. Questa funzionalità è particolarmente utile in situazioni in cui la formulazione standard completamente accoppiata non è fisicamente appropriata o numericamente efficiente. Alcuni esempi includono il blocco dei gradi di libertà più lenti, come gli ioni mobili, o la scomposizione di problemi 3D complessi in passaggi direzionali utilizzando strategie di tipo ADI.

Gli esempi presentati in questo documento illustrano due casi d’uso fondamentali. Il primo dimostra un intervento minimo, in cui l’equazione ionica viene disattivata solo nel circuito elettrico principale, al fine di riprodurre le condizioni sperimentali di scansione rapida. Il secondo mostra come Lua possa essere utilizzato per creare un flusso di lavoro personalizzato per la risoluzione dei problemi, alternando tra sezioni direzionali e applicando criteri di convergenza definiti dall’utente.Gli esempi presentati in questo documento illustrano due casi d’uso fondamentali. Il primo dimostra un intervento minimo, in cui l’equazione ionica viene disattivata solo nel circuito elettrico principale, al fine di riprodurre le condizioni sperimentali di scansione rapida. Il secondo mostra come Lua possa essere utilizzato per creare un flusso di lavoro personalizzato per la risoluzione dei problemi, alternando tra sezioni direzionali e applicando criteri di convergenza definiti dall’utente.

In termini più generali, Lua dovrebbe essere considerata un framework per lo sviluppo di metodi numerici all’interno di OghmaNano. Consente all’utente di superare le configurazioni fisse dei risolutori e, invece, di definire strategie di soluzione personalizzate, in linea sia con le caratteristiche fisiche del problema sia con le proprietà numeriche del sistema da risolvere.In termini più generali, Lua dovrebbe essere considerata un framework per lo sviluppo di metodi numerici all’interno di OghmaNano. Consente all’utente di superare le configurazioni fisse dei risolutori e, invece, di definire strategie di soluzione personalizzate, in linea sia con le caratteristiche fisiche del problema sia con le proprietà numeriche del sistema da risolvere.