Go to the first, previous, next, last section, table of contents.
Ce chapitre fournit une référence complète
pour toutes les fonctions FFTW séquentielles (i.e., un seul
processeur). Nous définissons en premier les types de données
sur lesquelles FFTW opère, et qui sont les nombres réels,
complexes et "halfcomplex" (voir la Section Types
de Données). Alors, en quatre sections, nous expliquons
l'interface de programme FFTW pour les transformées complexes
à une dimension (voir Section Référence
sur la Transformée une dimension), à multi
dimensions (voir Section Référence
sur la Transformée multi dimension), et transformée
réelle à une dimension (voir Section Référence
sur la Transformée Réelle une dimension), multi
dimension (voir Section Référence
sur la Transformée Réelle multi dimension). La
Section Référence pour
Sagesse (Wisdom) décrit le mécanisme wisdom
pour l'export et l'import de plans. Finallement, la Section Référence
sur l'Allocation Mémoire décrit comment changer
l'allocation de mémoire par défaut de FFTW. Pour les
transformées parallèles, consultez la Section FFTW
Parallèle.
Les routines dans le package FFTW utilisent trois types principaux de données. Les nombres Réels et Complexes doivent déjà être connus par les lecteurs. Nous utilisons aussi le terme halfcomplex pour décrire les tableaux complexes dans un format de paquet spécial utilisé par les transformées réelles à une dimension (prenant avantage de la symétrie hermitienne qui prévaut dans ces cas).
En ajoutant <fftw.h> ou <rfftw.h>,
vous aurez accès aux définitions suivantes :
typedef double fftw_real;
typedef struct {
fftw_real re, im;
} fftw_complex;
#define c_re(c) ((c).re)
#define c_im(c) ((c).im)
Toutes les opérations FFTW sont effectuées sur des
types de données fftw_real et fftw_complex.
Pour les nombres fftw_complex, les deux macros c_re
et c_im représentent respectivement les parts
réelles et imaginaires des nombres.
Un tableau réel est un tableau de nombres réels. Un tableau complexe est un tableau de nombres complexes. Un tableau à une dimension X de n nombres complexes est hermitien si la propriété suivante s'applique : pour tout 0 <= i < n, nous avons Xi = conj(Xn-i)}. Les tableaux Hermitiens sont appropriés à FFTW car la transformée de Fourier d'un tableau de réels est hermitienne.
Grâce à sa symétrie, un tableau hermitien peut
être stocké dans la moitié de la taille d'un
tableau de complexes. La transformée réelle FFTW à
une dimension stocke les tableaux hermitiens comme halfcomplex.
Un tableau halfcomplex de taille n est un tableau à une
dimension de n nombres fftw_real. Un tableau hermitien X
est stocké dans un tableau halfcomplex Y comme ce qui suit.
Pour tous les entiers i tel que 0 <= i <= n / 2, nous avons Yi
= Re(Xi). Pour tous les entiers i tel que 0 < i < n
/ 2, nous avons Yn-i = Im(Xi).
Nous illustrons maintenant le stockage halfcomplex pour n = 4 et n = 5, car le schéma dépend de la parité de n. Si n = 4. Dans ce cas, nous avons Y0 = Re(X0), Y1 = Re(X1), Y2 = Re(X2), et Y3 = Im(X1). Si maintenant n = 5. Dans ce cas, nous avons Y0 = Re(X0), Y1 = Re(X1), Y2 = Re(X2), Y3 = Im(X2), et Y4 = Im(X1).
Par défaut, le
type fftw_real équivaut au type C double.
Pour travailler en simple précision plutôt qu'en double,
ajoutez à #define le symbole FFTW_ENABLE_FLOAT
dans fftw.h et recompilez alors la bibliothèque.
Sur les systèmes Unix, vous pouvez faire le remplacement avec
configure --enable-float à la place, dès
l'installation (voir la Section Installation
et Personnalisation).
Dans la version 1 de
FFTW, les types de données étaient appelés
FFTW_REAL et FFTW_COMPLEX. Nous avons
changé vers les lettres capitales pour la cohérence
avec le reste des conventions FFTW. Les vieux noms sont encore
supportés mais leur utilisation est désaprouvée.
Les routines complexes Une dimension sont généralement
préfixées avec fftw_. Les programmes
utilisants FFTW doivent être liées avec -lfftw -lm
sur les systèmes Unix ou avec FFTW et les bibliothèques
mathématiques standard en général.
#include <fftw.h>
fftw_plan fftw_create_plan(int n, fftw_direction dir,
int flags);
fftw_plan fftw_create_plan_specific(int n, fftw_direction dir,
int flags,
fftw_complex *in, int istride,
fftw_complex *out, int ostride);
La fonction fftw_create_plan crée un plan qui est
une structure de donnée contenant toutes les informations dont
fftw a besoin de manière à calculer la
transformée 1D de Fourier. Vous pouvez créer autant de
plans que nécessaire mais un seul plan pour une taille de
tableau donnée est demandée (un plan peut être
réutilisé plusieurs fois).
fftw_create_plan retourne un plan valide ou NULL
si, pour une raison ou une autre, le plan n'a pas été
créé. Dans les installations par défaut, ceci ne
peut pas se produire, mais il est possible de configurer FFTW d'une
telle manière que quelques tailles d'entrée soient
prohibées et FFTW ne peut donc pas créer de plan.
La variante fftw_create_plan_specific prend comme
arguments additionnels les tableaux d'entrée/sortie
spécifiques et leur décalage. Pour les quatre dernier
arguments, vous donnez les tableaux et les décalages que vous
auriez finalement passé à fftw. Le plan
résultant sera optimisé pour ces tableaux et décalages
bien qu'il puisse être aussi bien utilisé sur d'autres
tableaux. Notez : les contenus des tableaux d'entrée et de
sortie sont détruit par le planificateur spécifique
(les contenus initiaux sont ignorés et les tableaux n'ont pas
besoin d'être initialisés).
n est la taille de la
transformée. Il peut être tout entier positif.
FFTW est meilleur dans le traitement de tailles de la forme 2a 3b 5c 7d 11e 13f, où e+f est soit 0 ou 1 et les autres exposants sont arbitraires. Les autres tailles sont calculées par le biais de routines générales plus lentes (qui gardent néanmoins une performance O(n lg n), même pour les tailles parmi les nombres premiers). (Il est possible de personaliser FFTW pour différentes tailles de tableaux. Consultez la Section Installation et Personnalisation, pour plus d'informations.) Les transformées dont les tailles ont une puissance de 2 sont spécialement rapides.
dir est le signe de
l'exposant dans la formule qui définit la transformée
de Fourier. Il peut être -1 ou +1. Les alias FFTW_FORWARD
et FFTW_BACKWARD sont fournis lorsque FFTW_FORWARD
est à -1.
flags
est un booléen OR (`|') de zéro ou plus
de la suite :
FFTW_MEASURE: ce
drapeau indique à FFTW de trouver le plan optimal en
calculant réellement plusieurs FFT et en mesurant
leur temps d'éxécution. En fonction de
l'installation, cela peut prendre un certain temps. (2)
FFTW_ESTIMATE: ne
fait pas tourner de FFT et fournit un plan "raisonable"
(pour un processeur RISC avec plusieurs registres). Si ni
FFTW_ESTIMATE, ni FFTW_MEASURE n'est
fourni, le défaut est FFTW_ESTIMATE.
FFTW_OUT_OF_PLACE:
produit un plan supposant que les tableaux d'entrée et de
sortie seront distincts (dit externe : c'est la cas par défaut).
FFTW_IN_PLACE:
produit un plan supposant que vous voulez que sortie soit dans
l'entrée. L'algorithme utilisé n'est pas
nécessairement interne : FFTW n'est capable de calculer des
transformées internes vraies que pour des petites valeurs de
n. Si FFTW n'est pas capable de calculer des transformées
internes, il allouera un tableau temporaire (à moins que
vous ne le fournissiez vous-même), calculera la transformée
en externe et recopiera le tableau dans l'entrée. Attention:
Cette option change la signification de certains paramètres
de fftw (voir la Section Calculer
la Transformée Une dimension). L'option interne est
principalement fournie pour les personnes qui veulent écrire
leur propre transformée de Fourier interne multi dimension,
utilisant FFTW comme une base. Par exemple, considérez une
transformée trois dimension n * n * n. Un
algorithme externe nécessitera un autre tableau (qui peut
être énorme). Néanmoins, FFTW peut calculer la
transformée interne pour chaque dimension en utilisant
seulement un tableau temporaire de la taille de n. De plus, si FFTW
arrive à calculer la transformée réellement en
interne, aucun tableau temporaire et aucune copie ne sont
nécessaires. Une FFTW distribuée `sait' comme
calculer les transformées internes des tailles 1, 2, 3, 4,
5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 32 et 64. Le mode par
défaut pour les opérations est FFTW_OUT_OF_PLACE.
FFTW_USE_WISDOM:
utilise wisdom s'il est disponible pour aider dans la
création du plan. (Voir Section Mots
de Sagesse.) Ceci peut grandement accélérer la
création des plans, spécialement avec l'option
FFTW_MEASURE. Les plans FFTW_ESTIMATE
peuvent aussi tirer avantage de wisdom pour produire
un plan plus optimal (basé sur les mesures passées)
que ce que les estimations heuristiques auraient pu normalement
générer. Lorsque l'option FFTW_MEASURE
est utilisée, un nouveau wisdom sera aussi
généré si la taille de la transformée
courante n'est pas complètement comprise par le wisdom
existant.
in, out, istride,
ostride (seulement pour fftw_create_plan_specific):
voir les arguments correspondants dans la description de fftw.
(Voir Section Calculer une
Transformée Une dimension.) En particulier, les
paramètres out et ostride ont la
même signification spéciale pour les transformées
FFTW_IN_PLACE qu'ils en ont pour fftw.
Nous recommandons l'utilisation de planificateurs spécifiques, même dans les cas où vous allez transformer des tableaux différents de ceux passés dans le planificateur spécifique, car ils possèdent les avantages suivants :
Les plan résultants seront optimisés pour vos tableaux et décalages spécifiques. Ceci ne fera peut être pas une différence significative mais cela ne fait pas de mal. (Le planificateur ordinaire fait son plan en fonction des décalages temporaires du tableau qu'il alloue).
Moins de stockage intermédiaire
n'est nécessaire pendant le processus de planification.(Le
planificateur ordinaire utilise O(N) stockage
temporaire, où N est la dimension maximum
lorsqu'il crée le plan).
Pour les transformées multi dimension, les nouveaux paramètres deviennent accessibles pour l'optimisaation par le planificateur. (Les tableaux multi dimension pouvant être très larges, nous préférons éviter d'en allouer un pour l'expérimentation avec un planificateur ordinaire. Ceci nous empèche de faire certaines optimisations qui pourraient mener à des améliorations dramatiques dans certains cas).
D'un autre coté, notez que le planificateur spécifique
détruit le contenu des tableaux in et out.
#include <fftw.h>
void fftw(fftw_plan plan, int howmany,
fftw_complex *in, int istride, int idist,
fftw_complex *out, int ostride, int odist);
void fftw_one(fftw_plan plan, fftw_complex *in,
fftw_complex *out);
La fonction fftw calcule la transformée de
Fourier à une dimension, utilisant un plan créé
par fftw_create_plan (Voir Section Création
de plan pour les Transformées à Une dimension). La
fonction fftw_one fournit une interface simplifiée
pour le cas commun d'un simple tableau avec un décalage de 1.
plan est le plan créé
par fftw_create_plan (voir Section Création
de plan pour Transformée Une dimension).
howmany est le nombre
de transformées que fftw va calculer. Il est
plus rapide de dire à FFTW de calculer plusieurs
transformées, plutôt que simplement appeler fftw
plusieurs fois.
in, istride
et idist décrivent le(s) tableau(x) entrée.
Il y a howmany tableaux d'entrée; Le premier est
pointé par in, le second par in + idist,
et ainsi de suite, jusqu'à in + (howmany - 1) * idist.
Chaque tableau d'entrée consiste en des nombres complexes
(voir Section Types de Données),
qui ne sont pas néccessairement contigus dans la mémoire.
Spécifiquement, in[0] est le premier élément
du premier tableau, in[istride] est le second élément
du premier tableau et ainsi de suite. En général, le
i-ième élément du j-ième
tableau d'entrée sera en position in[i * istride + j *
idist].
out, ostride
et odist décrivent le(s) tableau(x) de sortie.
Le format est le même que pour le tableau d'entrée.
Transformée interne : Si le plan
spécifie une transformée interne ostride
et odist sont toujours ignorés. Si out
est NULL, il est ignoré. Sinon, out
est interprété comme un pointeur vers un tableau de n
nombres complexes que FFTW va utiliser comme espace temporaire pour
effectuer le calcul interne. out est utilisé
comme espace de travail et son contenu est détruit. Dans ce
cas, out doit être un tableau ordinaire dont les
éléments sont contigus dans la mémoire (pas de
décalage).
La fonction fftw_one transforme un tableau d'entrée
simple, contigu en un tableau de sortie contigu. Par définition,
l'appel
fftw_one(plan, in, out)
est équivalent à
fftw(plan, 1, in, 1, 1, out, 1, 1)
#include <fftw.h> void fftw_destroy_plan(fftw_plan plan);
La fonction fftw_destroy_plan libère le plan plan
et désalloue toute la mémoire qui y est associée.
Après destruction, le plan n'est plus valide.
Dans cette section, nous définissons précisément ce que FFTW calcule. Please faite attention au fait que différents auteurs et packages logiciels peuvent employer des conventions différentes de FFTW.
La transformée directe d'un tableau de complexes X de taille n calcule un tableau Y, où
La transformée inverse calcule
FFTW calcule une transformée non normalisée, qui est représentée par l'équation IFFT(FFT(X)) = n X. En d'autres termes, appliquer une transformée puis son inverse multipliera l'entrée par n.
Une transformée FFTW_FORWARD correspond à
un signe de -1 sur l'exposant de la DFT. Notez aussi que nous
utilisons la sortie standard "interne" ordonnant les
k-ièmes sorties correspondant aux fréquences k/n (ou
k/T, où T est la période totale d'échantillonnage).
Pour ceux qui aiment penser en terme de fréquences positives
ou négatives, ceci signifie que les fréquences
positives sont stockées dans la première moitié
de la sortie et les fréquences négatives sont stockées
dans l'ordre inverse sur la seconde moitié de la sortie. (La
fréquence -k/n est la même que la fréquence
(n-k)/n.)
Les routines complexes multi dimension sont généralement
préfixées avec fftwnd_-lfftw -lm
#include <fftw.h>
fftwnd_plan fftwnd_create_plan(int rank, const int *n,
fftw_direction dir, int flags);
fftwnd_plan fftw2d_create_plan(int nx, int ny,
fftw_direction dir, int flags);
fftwnd_plan fftw3d_create_plan(int nx, int ny, int nz,
fftw_direction dir, int flags);
fftwnd_plan fftwnd_create_plan_specific(int rank, const int *n,
fftw_direction dir,
int flags,
fftw_complex *in, int istride,
fftw_complex *out, int ostride);
fftwnd_plan fftw2d_create_plan_specific(int nx, int ny,
fftw_direction dir,
int flags,
fftw_complex *in, int istride,
fftw_complex *out, int ostride);
fftwnd_plan fftw3d_create_plan_specific(int nx, int ny, int nz,
fftw_direction dir, int flags,
fftw_complex *in, int istride,
fftw_complex *out, int ostride);
La fonction fftwnd_create_plan crée un plan qui
est une structure de donnée contenant toutes les informations
dont fftwnd a besoins de manière à
calculer une transformée de Fourier multi dimension. Vous
pouvez créer autant de plans que vous en avez besoin mais seul
un plan pour une taille de tableau donné est nécessaire
(un plan peut être réutilisé plusieurs fois). Les
fonctions fftw2d_create_plan et fftw3d_create_plan
sont des interfaces optionelles, alternatives à
fftwnd_create_plan pour deux et trois dimensions,
respectivement.
fftwnd_create_plan retourne un plan valide ou NULL
si, quelqu'en soit la raison, le plan n'a pas été créé.
Ceci peut se produire si la mémoire est débordée
ou si les arguments sont invalides d'une certaine manière
(e.g. si rank < 0).
La variante create_plan_specific prend comme
arguments additionnels les tableaux d'entrée/sortie
spécifiques et leur décalage. Pour les quatre dernier
arguments, vous donnez les tableaux et les décalages que vous
auriez finalement passé à fftwnd. Le plan
résultant sera optimisé pour ces tableaux et décalages
bien qu'il puisse être aussi bien utilisé sur d'autres
tableaux. Notez : les contenus des tableaux d'entrée et de
sortie sont détruit par le planificateur spécifique
(les contenus initiaux sont ignorés et les tableaux n'ont pas
besoin d'être initialisés). Voir Section Discussion
sur les Plans Spécifiques, pour une discussion sur les
plans spécifiques.
rank donne la
dimension des tableaux devant être transformés. Il peut
être tout entier non négatif.
n
est un pointeur d'entiers rank, donnant la taille de
chaque dimension du tableau devant être transformé. Ces
tailles, qui doivent être des entiers positifs, correspondent
aux tableaux dans l'ordre des lignes i.e. n[0] est la
taille de la dimension dont les indices varient les plus lentement
et ainsi de suite. (Voir la Section Format
des Tableaux Multi dimension pour plus d'informations sur
l'ordre par ligne.) Consultez la Section Création
de Plan pour les Transformées Une dimension pour plus
d'informations sur les tailles optimales des tableaux.
nx et ny
dans fftw2d_create_plan sont des entiers positifs
spécifiant les dimensions du rang 2 des tableaux devant être
transformés. i.e. ils spécifient que la transformée
opèrera sur des tableaux nx x ny dans l'ordre
des lignes, où nx est le nombre de lignes et ny
est le nombre de colonnes.
nx, ny
et nz dans fftw3d_create_plan sont des
entiers positifs spécifiant les dimensions du rang 3 des
tableaux devant être transformés. i.e. Ils spécifient
que la transformée opèrera sur des tableaux nx x
ny x nz dans l'ordre des lignes.
dir est le signe de
l'exposant dans la formule qui définit la transformée
de Fourier. Il peut être -1 ou +1. Les alias FFTW_FORWARD
et FFTW_BACKWARD sont fournis, où FFTW_FORWARD
signifie -1.
flags
est un booléen OR (`|') de zéros ou plus
selon la suite :
FFTW_MEASURE: ce
drapeau indique à FFTW de trouver le plan optimal en
calculant réellement plusieurs FFT et en mesurant
leur temps d'exécution.
FFTW_ESTIMATE: ne
fait pas tourner de FFT et fournit un plan "raisonable"
(pour un processeur RISC avec plusieurs registres). Si ni
FFTW_ESTIMATE, ni FFTW_MEASURE n'est
fourni, le défaut est FFTW_ESTIMATE.
FFTW_OUT_OF_PLACE:
produit un plan supposant que les tableaux d'entrée et de
sortie seront distincts (dit externe : c'est le cas par défaut).
FFTW_IN_PLACE:
produit un plan supposant que vous voulez effectuer la transformée
en interne. (Contrairement à la transformée une
dimension, il la réalise "réellement" (3)
en interne.) Notez que si vous voulez réaliser des
transformées internes, vous devez utiliser un plan
créé avec cette option. Le mode par défaut des
opérations est FFTW_OUT_OF_PLACE.
FFTW_USE_WISDOM:
utilise wisdom s'il est disponible pour aider la
création du plan. (Voir Section Mots
de Sagesse.) Ceci peut grandement accélérer la
création des plans, spécialement avec l'option
FFTW_MEASURE. Les plans FFTW_ESTIMATE
peuvent aussi tirer avantage de wisdom pour produire
un plan plus optimal (basé sur les mesures passées)
que ceux générés par les estimations
heuristiques. Lorsque l'option FFTW_MEASURE est
utilisée, un nouveau wisdom sera aussi généré
si la taille de la transformée courante n'est complètement
comprise par le wisdom existant. Notez que le même
wisdom est partagé entre les transformées
une et multi dimensions.
in, out, istride,
ostride (seulement pour la variante
_create_plan_specific) : voir les arguments
correspondants dans la description de fftwnd. (Voir la
Section Calculer la Transformée
Multi dimension).
#include <fftw.h>
void fftwnd(fftwnd_plan plan, int howmany,
fftw_complex *in, int istride, int idist,
fftw_complex *out, int ostride, int odist);
void fftwnd_one(fftwnd_plan p, fftw_complex *in,
fftw_complex *out);
La fonction fftwnd calcule un ou plusieurs Transformées
de Fourier multi dimension, utilisant un plan créé par
fftwnd_create_plan (voir Section Création
de Plan pour Transformée Multi dimension). (Notez que le
plan détermine le rang et les dimensions du plan devant être
transformé). La fonction fftwnd_one fournit une
interface simplifiée pour les cas communs de tableaux d'entrée
simple avec un décalage de 1.
plan est le plan créé
par fftwd_create_plan (voir Section Création
de Plan pour les Transformées Multi dimension). Dans le
cas de transformées à deux ou trois dimensions, il
peut aussi avoir été créé par
fftw2d_create_plan ou fftw3d_create_plan,
respectivement.
howmany est le nombre
de transformées que fftwnd va calculer.
in, istride
and idist décrivent le(s) tableau(x) d'entrée.
Il y a howmany tableaux d'entrée; Le premier est
pointé par in, le second par in + idist,
et ainsi de suite, jusqu'à in + (howmany - 1) * idist.
Chaque tableau d'entrée multi dimension consiste en des
nombres complexes (voir Section Types
de Données), stockés dans l'ordre des lignes(voir
la Section Format des Tableaux Multi
dimension), qui ne sont pas néccessairement contigus dans
la mémoire. Spécifiquement, in[0] est le
premier élément du premier tableau, in[istride]
est le second élément du premier tableau et ainsi de
suite. En général, le i-ième
élément du j-ième tableau d'entrée
sera en position in[i * istride + j * idist]. Notez
que, ici, i réfère à un index dans
le format des lignes pour les tableaux multi dimension, plutôt
qu'un index dans une dimension particulière.
Transformée interne :
Pour les plan créés avec l'option FFTW_IN_PLACE,
la transformée est calculée en interne --la sortie
est déplacée dans le tableau in,
utilisant les même décalages, et ainsi de suite, comme
si l'entrée était utilisée.
out, ostride
and odist décrivent le(s) tableau(x) de sortie.
Le format est le même que pour le tableau d'entrée.
Transformée interne : ces paramètres
sont ignorés pour les plans crées avec l'option
FFTW_IN_PLACE.
La fonction fftwnd_one transforme un tableau d'entrée
simple, contigu en un tableau de sortie contigu. Par définition,
l'appel
fftwnd_one(plan, in, out)
est équivalent à
fftwnd(plan, 1, in, 1, 1, out, 1, 1)
#include <fftw.h> void fftwnd_destroy_plan(fftwnd_plan plan);
La fonction fftwnd_destroy_plan libère le plan
plan et désalloue toute la mémoire qui y
est associée. Après destruction, le plan n'est plus
valide.
La convention suivie pour les transformées multi dimension est analogue à celle de la transformée une dimension. En particulier, la transformée directe possède un exposant au signe négatif et ni les transformées directes, ni les inverses ne sont normalisées. Calculer la transformée inverse de la directe multipliera le tableau par le produit de ses dimensions. La sortie est dans l'ordre et l'élément zéro de la sortie est l'amplitude de la composante continue. Les Dieux ont interdit l'utilisation de HTML pour afficher les formules mathématiques. Please consultez la version TeX ou Postscript de ce manuel pour la définition correcte de la transformée de Fourier à n dimension que FFTW utilise. Pour complément, nous incluons un bitmap de la sortie TeX ci-dessous :
Les routines réelles une dimension sont généralement
préfixées avec rfftw_. (4)
Les programmes utilisant RFFTW doivent être linké avec
-lrfftw -lfftw -lm sur les systèmes Unix ou avec
RFFTW, FFTW, et les bibliothèques mathématiques
standard en général.
#include <rfftw.h>
rfftw_plan rfftw_create_plan(int n, fftw_direction dir, int flags);
rfftw_plan rfftw_create_plan_specific(int n, fftw_direction dir,
int flags, fftw_real *in, int istride,
fftw_real *out, int ostride);
La fonction rfftw_create_plan crée un plan qui
est une structure de donnée contenant toutes les informations
dont fftw a besoin de manière à calculer
la transformée 1D de Fourier. Vous pouvez créer autant
de plans que nécessaire mais un seul plan pour une taille de
tableau donnée est demandée (un plan peut être
réutilisé plusieurs fois).
rfftw_create_planNULL si, pour une raison ou une autre, le plan
n'a pas été créé. Dans les installations
par défaut, ceci ne peut pas se produire, mais il est possible
de configurer RFFTW d'une telle manière que quelques tailles
d'entrées soient prohibées et RFFTW ne peut donc pas
créer de plan.
La variante rfftw_create_plan_specific prend comme
arguments additionnels les tableaux d'entrée/sortie spécifique
et leur décalage. Pour les quatre dernier arguments, vous
donnez les tableaux et les décalages que vous auriez
finalement passé à rfftw. Le plan
résultant sera optimisé pour ces tableaux et décalages
bien qu'il puisse être aussi bien utilisé sur d'autres
tableaux. Notez : les contenus des tableaux d'entrée et de
sortie sont détruit par le planificateur spécifique
(les contenus initiaux sont ignorés et les tableaux n'ont pas
besoin d'être initialisés). Voir la Section Discussion
sur les Plans Spécifiques, pour une information sur les
plans spécifiques.
n est la taille de la
transformée. Il peut être tout entier positif.
RFFTW est meilleur dans le traitement de tailles de la forme 2a 3b 5c 7d 11e 13f, où e+f est soit 0 ou 1 et les autres exposants sont arbitraires. Les autres tailles sont calculées par le biais de routines générales plus lentes (qui gardent néanmoins une performance à O(n2) pour les tailles des nombres premiers). (Il est possible de personaliser RFFTW pour différentes tailles de tableaux. Consultez la Section Installation et Personnalisation, pour plus d'informations.) Les transformées dont les tailles ont une puissance de 2 sont spécialement rapides.
dir est la direction de la transformée, qu'elle
soit FFTW_REAL_TO_COMPLEX or FFTW_COMPLEX_TO_REAL,
correspondant à FFTW_FORWARD ou FFTW_BACKWARD,
respectivement.
flags
est un booléen OR (`|') de zéro ou plus
de la suite :
FFTW_MEASURE : ce
drapeau indique à RFFTW de trouver le plan optimal en
calculant réellement plusieurs FFT et en mesurant
leur temps d'éxécution. En fonction de
l'installation, cela peut prendre un certain temps.
FFTW_ESTIMATE : ne
fait pas tourner de FFT et fournit un plan "raisonable"
(pour un processeur RISC avec plusieurs registres). Si ni
FFTW_ESTIMATE, ni FFTW_MEASURE n'est
fourni le défaut est FFTW_ESTIMATE.
FFTW_OUT_OF_PLACE :
produit un plan supposant que les tableaux d'entrée et de
sortie seront distincts (dit externe : c'est la cas par défaut).
FFTW_IN_PLACE rfftw (voir la Section Calculer
la Transformée Réelle Une dimension). Le mode par
défaut est FFTW_OUT_OF_PLACE
FFTW_USE_WISDOM :
utilise wisdom s'il est disponible pour aider dans la
création du plan. (Voir Section Mots
de Sagesse.) Ceci peut grandement accélérer la
création des plans, spécialement avec l'option
FFTW_MEASURE. Les plans FFTW_ESTIMATE
peuvent aussi tirer avantage de wisdom pour produire
un plan plus optimal (basé sur les mesures passées)
que ce que les estimations heuristiques auraient pu normalement
générer. Lorsque l'option FFTW_MEASURE
est utilisée, un nouveau wisdom sera aussi
généré si la taille de la transformée
courante n'est complètement comprise par le wisdom
existant.
in, out, istride,
ostride (seulement pour rfftw_create_plan_specific):
voir les arguments correspondants dans la description de rfftw.
(Voir Section Calculer la Transformée
Réelle Une dimension). En particulier, les paramètres
out et ostride ont la même
signification spéciale pour les transformées
FFTW_IN_PLACE qu'ils en ont pour rfftw.
#include <rfftw.h>
void rfftw(rfftw_plan plan, int howmany,
fftw_real *in, int istride, int idist,
fftw_real *out, int ostride, int odist);
void rfftw_one(rfftw_plan plan, fftw_real *in, fftw_real *out);
La fonction rfftw calcule la transformée de
Fourier à une dimension, utilisant un plan créé
par rfftw_create_plan (Voir Section Création
de Plan pour la Transformée Réelle Une dimension).
La fonction rfftw_one fournit une interface simplifiée
pour le cas commun d'un simple tableau avec un décalage de 1.
Important: Lorsqu'une transformée
FFTW_COMPLEX_TO_REAL appelée est externe, le
tableau d'entrée est écrasé par des données
temporaires. Le tableau d'entrée n'est pas modifié pour
les transformées FFTW_REAL_TO_COMPLEX.
plan est le plan créé
par rfftw_create_plan (voir Section Création
de Plan pour les Transformées Réelles Une dimension).
howmany est le nombre
de transformées que rfftw va calculer. Il est
plus rapide de dire à RFFTW de calculer plusieurs
transformées, plutôt que simplement appeler rfftw
plusieurs fois.
in, istride
and idist décrivent le(s) tableau(x) d'entrée.
Il y a deux cas. Si le plan définit une
transformée FFTW_REAL_TO_COMPLEX,in est un
tableau de réels. Sinon, pour les transformées
FFTW_COMPLEX_TO_REAL, in est un tableau de
halfcomplex dont le contenu va être détruit.
out, ostride
et odist décrit le(s) tableau(x) de sortie. Le
format est le même que pour le tableau d'entrée.
Transformée interne : Si
le plan spécifie une transformée interne
ostride et odist sont toujours ignorées.
Si out est NULL, out est
ignoré aussi. Sinon, out est interprété
comme un pointeur vers un tableau de n nombres complexe que FFTW va
utiliser comme espace temporaire pour effectuer le calcul interne.
out est utilisé comme espace de travail et son
contenu est détruit. Dans ce cas, out doit être
un tableau ordinaire dont les éléments sont contigus
dans la mémoire (pas de décalage).
La fonction rfftw_one transforme un tableau d'entrée
simple, contigu en un tableau de sortie contigu. Par définition,
l'appel
rfftw_one(plan, in, out)
est équivalent à
rfftw(plan, 1, in, 1, 1, out, 1, 1)
#include <rfftw.h> void rfftw_destroy_plan(rfftw_plan plan);
La fonction rfftw_destroy_plan libère le plan
plan et désalloue toute la mémoire qui y
est associée. Après destruction, le plan n'est plus
valide.
Dans cette section, nous définissons précisément ce que calcule RFFTW.
La transformée réelle
vers complexe (FFTW_REAL_TO_COMPLEX) d'un tableau de
réels X de taille n calcule un tableau hermitien Y, où
(Le fait que Y soit un tableau hermitien n'est pas évident, bien que le prouver soit facile). Le tableau hermitien Y est stocké dans un ordre halfcomplex (voir Section Types de Données). Actuellement, RFFTW ne fournit aucun moyen de calculer une transformée réelle vers complexe avec un signe positif pour l'exposant.
La transformée complexe vers
réelle (FFTW_COMPLEX_TO_REAL) d'un tableau
hermitien X de taille n calcule un tableau de réels Y, où
(Le fait que Y soit un tableau de réels n'est pas évident, bien que le prouver soit facile). Le tableau hermitien X d'entrée est stocké dans un ordre halfcomplex (voir Section Types de Données). Actuellement, RFFTW ne fournit aucun moyen de calculer une transformée complexe vers réel avec un signe négatif pour l'exposant.
Comme FFTW, RFFTW calcule une transformée non normalisée. En d'autres termes, appliquer la transformée réel vers complexe (directe) et ensuite complexe vers réel (inverse) multipliera l'entrée par n.
Les routines complexes multi dimension sont généralement
préfixées avec rfftwnd_. Les programmes
utilisant RFFTWND doivent être linkés avec -l sur les systèmes Unix ou avec
FFTW, RFFTW et les bibliothèques mathématiques standard
en général.
rfftw
-lfftw -lm
#include <rfftw.h>
rfftwnd_plan rfftwnd_create_plan(int rank, const int *n,
fftw_direction dir, int flags);
rfftwnd_plan rfftw2d_create_plan(int nx, int ny,
fftw_direction dir, int flags);
rfftwnd_plan rfftw3d_create_plan(int nx, int ny, int nz,
fftw_direction dir, int flags);
La fonction rfftwnd_create_planra besoins de
manière à calculer une transformée de Fourier
réelle multi dimension. Vous pouvez créer autant de
plans que vous en avez besoin mais seul un plan pour une taille de
tableau donné est nécessaire (un plan peut être
réutilisé plusieurs fois). La fonction
fftwnd r et fftw2d_create_planr
sont des interfaces optionelles, alternatives à
fftw3d_create_planr pour deux et trois
dimensions, respectivement.
fftwnd_create_plan
rfftwnd_create_plan retourne un plan valide ou NULL
si, quelqu'en soit la raison, le plan n'a pas été créé.
Ceci peut se produire si la mémoire est débordée
ou si les arguments sont invalides d'une certaine manière
(e.g. si rank < 0).
rank est la dimension
des tableaux devant être transformés. Ils peuvent être
tout entier non négatif.
n est un pointeur
d'entiers rank, donnant la taille de chaque dimension
du tableau devant être transformé. Notez que ces
pointeurs ont toujours la dimension des tableaux réels;
les tableaux de complexes ont des dimensions différentes
(voir Section Dimensions des Tableaux
pour la Transformée Réelle Multi dimension). Ces
tailles, qui doivent être des entiers positifs, correspondent
aux dimensions des tableaux dans l'ordre des lignes --i.e. n[0]
est la taille de la dimension dont les indices varient les plus
lentement, et ainsi de suite. (Voir Section Format
des Tableaux Multi dimension, pour plus d'informations.)
Voir Section Création de Plan pour les Transformées Réelles Une dimension, pour plus d'informations concernant les tailles de tableaux optimales.
nx et ny
dans rfftw2d_create_plan sont des entiers positifs
spécifiant les dimensions du rang 2 des tableaux devant être
transformés. i.e. ils spécifient que la transformée
opèrera sur des tableaux nx x ny dans l'ordre
des lignes, où nx est le nombre de lignes et ny
est le nombre de colonnes.
nx, ny
et nz dans rfftw3d_create_plan sont des
entiers positifs spécifiant les dimensions du rang 3 des
tableaux devant être transformés. i.e. ils spécifient
que la transformée opèrera sur des tableaux nx x
ny x nz dans l'ordre des lignes.
dir est la direction
de la transformée désirée, soit
FFTW_REAL_TO_COMPLEX ou FFTW_COMPLEX_TO_REAL,
correspondant à FFTW_FORWARD ou FFTW_BACKWARD,
respectivement.
flags
est un booléen OR (`|') de zéros ou plus
selon ce qui suit :
FFTW_MEASURE: ce
drapeau indique à FFTW de trouver le plan optimal en
calculant réellement plusieurs FFT et en mesurant
leur temps d'exécution.
FFTW_ESTIMATE: ne
fait pas tourner de FFT et fournit un plan "raisonable"
(pour un processeur RISC avec plusieurs registres). Si ni
FFTW_ESTIMATE, ni FFTW_MEASURE n'est
fourni le défaut est FFTW_ESTIMATE.
FFTW_OUT_OF_PLACE:
produit un plan supposant que les tableaux d'entrée et de
sortie seront distincts (dit externe : c'est la cas par défaut).
FFTW_IN_PLACE:
produit un plan supposant que vous voulez effectuer la transformée
en interne. (Contrairement à la transformée une
dimension, il la réalise "réellement" en
interne.) Notez que si vous voulez réaliser des transformées
internes, vous devez utiliser un plan créé
avec cette option. L'utilisation de cette option a d'importantes
implications pour la taille du tableau d'entrée/sortie (voir
Section Calculer la Transformée
Réelle Multi dimension). Le mode par défaut des
opérations est FFTW_OUT_OF_PLACE.
FFTW_USE_WISDOM: utilise
wisdom s'il est disponible pour aider la création
du plan. (Voir Section Mots de
Sagesse.) Ceci peut grandement accélérer la
création des plans, spécialement avec l'option
FFTW_MEASURE. Les plans FFTW_ESTIMATE
peuvent aussi tirer avantage de wisdom pour produire
un plan plus optimal (basé sur les mesures passées)
que ce que les estimations heuristiques auraient pu normalement
générer. Lorsque l'option FFTW_MEASURE
est utilisée, un nouveau wisdom sera aussi
généré si la taille de la transformée
courante n'est complètement comprise par le wisdom
existant. Notez que le même wisdom est partagé
entre les transformées une et multi dimensions.
#include <rfftw.h>
void rfftwnd_real_to_complex(rfftwnd_plan plan, int howmany,
fftw_real *in, int istride, int idist,
fftw_complex *out, int ostride, int odist);
void rfftwnd_complex_to_real(rfftwnd_plan plan, int howmany,
fftw_complex *in, int istride, int idist,
fftw_real *out, int ostride, int odist);
void rfftwnd_one_real_to_complex(rfftwnd_plan p, fftw_real *in,
fftw_complex *out);
void rfftwnd_one_complex_to_real(rfftwnd_plan p, fftw_complex *in,
fftw_real *out);
Ces fonctions calculent la Transformée de Fourier réelle
multi dimension, utilisant un plan créé par
rfftwnd_create_plan (voir Section Création
de Plan pour les Transformées Réelles Multi dimension).
(Notez que le plan détermine le rang et les dimensions du
tableau devant être transformé). La fonction
`rfftwnd_one_' fournit une interface
simplifiée pour le cas commun d'un simple tableau avec un
décalage de 1.
Important: Lorsqu'une transformée
FFTW_COMPLEX_TO_REALrank > 1FFTW_REAL_TO_COMPLEXFFTW_COMPLEX_TO_REAL avec un rank == 1.
plan est le plan créé
par rfftwnd_create_plan. (voir la Section Création
de Plan pour les Transformées Réelles Multi
dimension). Dans le cas des transformées deux ou trois
dimensions, ils peuvent être aussi créés
rfftw2d_create_plan ou rfftw3d_create_plan,
respectivement. Les plans FFTW_REAL_TO_COMPLEX doivent
être utilisés avec les fonctions `real_to_complex'
et les plans FFTW_COMPLEX_TO_REAL doivent être
utilisés avec les fonctions `complex_to_real'
. Ce serait une erreur de mélanger la direction du plan et la
fonction transformée.
howmany est le nombre
de transformées à calculer.
in,
istride and idist décrivent le(s)
tableau(x) d'entrée. Il y a howmany tableaux
d'entrée; Le premier est pointé par in,
le second par in + idist, et ainsi de suite, jusqu'à
in + (howmany - 1) * idist. Chaque tableau d'entrée
est stocké dans l'ordre des lignes (voir Section Format
des Tableaux Multi dimension), et n'est pas nécessairement
contigu en mémoire. Spécifiquement, in[0]
est le premier élément du premier tableau, in[istride]
est le second élément du premier tableau et ainsi de
suite. En général, le i-ième
élément du j-ième tableau d'entrée
sera en position in[i * istride + j * idist]. Notez
que, ici, i réfère à un index dans
le format des lignes pour les tableaux multi dimension, plutôt
qu'un index dans une dimension particulière. Les dimensions
des tableaux sont différentes pour les données
complexes et réelles et sont détaillées
ci-dessous (voir Section Dimensions
des Tableaux pour les Transformées Réelles Multi
dimension).
Transformée
interne : Pour les plan créés
avec l'option FFTW_IN_PLACE, la transformée est
calculée en interne --la sortie est déplacée
dans le tableau in.
La signification des paramètres stride et dist
dans ce cas est subtile est est détaillé ci-dessous
(voir Section Décalages dans
RFFTWND Interne).
out, ostride
et odist décrivent le(s) tableau(x) de sortie.
Le format est le même que pour le tableau d'entrée.
Voir ci-dessous pour le détail sur les dimensions des
tableaux de sortie pour les données réelles et
complexes.
Transformée interne : Ces
paramètres sont ignorés pour les plans créés
avec l'option FFTW_IN_PLACE.
La fonction rfftwnd_one transforme un tableau
d'entrée simple, contigu en un tableau de sortie contigu. Par
définition, l'appel
rfftwnd_one_...(plan, in, out)
est équivalent à
rfftwnd_...(plan, 1, in, 1, 1, out, 1, 1)
La sortie d'une transformée multi dimension de données
réelles contient des symétries qui rendent en principe,
la moitié des sorties redondantes (voir Section Ce
Que calcule Réellement RFFTWND). En pratique, il n'est pas
possible de réaliser entièrement ces économies
dans un format efficace et compréhensible. Au lieu de cela, la
sortie de la transformée de rfftwnd est légèrement
au dessus de la moitié de la transformée complexe
correspondante. Nous ne "compressons" les données en
aucune manière, mais nous les stockons dans un tableau
ordinaire de valeurs fftw_complex. En fait, cette donnée
est simplement une sous section de ce que serait le tableau pour la
transformée complexe correspondante.
Spécifiquement, pour une transformée réelle
de dimensions n1 x n2 x ... x nd,
les données complexes sont un tableau de n1 x n2
x ... x (nd/2+1) de valeurs fftw_complex dans
l'ordre des lignes (la division arrondie en dessous). Ceci étant,
nous ne stockons que la partie basse (plus un élément)
de la dernière dimension de la donnée provenant de la
transformée complexe ordinaire. (Nous aurions pu prendre la
moitié de toutes les autres dimensions à la place mais
l'implémentation est plus simple si la dernière
dimension contigue est utilisée).
Les données complexes étant plus larges que les
données réelles, quelques complications sont soulevées
pour les transformées internes. Dans ce cas, la dimension
finale de la donnée réelle doit être remplie avec
des valeurs additionnelles pour s'accomoder de la taille des données
complexe --deux si la dernière dimension est paire et une si
elle est impaire. Ceci étant, la dernière dimension des
données réelles doit contenir physiquement 2 * (nd/2+1)
fftw_real valeurs (exactement suffisamment pour contenir
des données complexes). Cette taille physique de tableau ne
doit pas, néanmoins, changer la taille du tableau logique
--seules nd valeurs sont réellement stockées
dans la dernière dimension et nd est la dernière
dimension passée à rfftwnd_create_plan.
Le fait que les types de données d'entrée et de
sortie soient différents pour rfftwnd complique la
signification des paramètres stride et dist
des transformées interne --sont-ils dans l'unité des
éléments de fftw_real ou ceux de
fftw_complex. Lors de la lecture de l'entrée, ils
sont interprétés dans l'unité du type de donnée
de l'entrée. Lors de l'écriture de la sortie, istride
et idist sont traduits dans "l'unité"du
type de donnée de sortie par l'une des deux manières
correspondant aux deux situations les plus communes dans lesquelles
les paramètres stride et dist sont
utiles. Ci-dessous, nous nous référons à ces
paramètres "traduits" comme ostride_t
et odist_t. (Notez que ceux-ci sont calculés en
interne par rfftwnd; les paramètres réels ostride
et odist sont ignorés pour les transformées
internes).
En premier, il y a le cas où vous transformez un nombre de
tableaux contigus situés les uns après les autres dans
la mémoire. Dans cette situation, istride est 1
et idist est le produit des dimensions physiques du
tableau. ostride_t et odist_t sont alors
choisis de telle manière que les tableaux de sortie soient
contigus et soient placés devant les tableaux d'entrée.
ostride_t est donc 1. Pour une transformée
réelle-vers-complexe, odist_t est idist/2;
pour une transformée complexe-vers-réel, odist_t
est idist*2.
Le second cas se produit lorsque vous avez un tableau dans lequel
chaque élément a nc composants (e.g. une
structure avec nc champs numériques), et que vous
voulez transformer tous les composants à la fois. Ici istride
est nc et idist est 1. Dans ce
cas, il est naturel de vouloir que la sortie ait nc
composants consécutifs, maintenant du type des données
de sortie; c'est exactement ce que fait rfftwnd. Spécifiquement,
il utilise un ostride_t égal à istride,
et un odist_t à 1. (Les lecteurs
rusés réaliseront qu'il faut un buffer supplémentaire
pour effectuer une telle transformée; c'est traité
automatiquement par rfftwnd.)
La règle générale est comme suit. ostride_t
égale istride. Si idist est 1
et idist est plus petit que istride, alors
odist_t est 1. Sinon, pour les transformées
réelle-vers-complexe odist_t est idist/2
et pour une transformée complexe-vers-réel odist_t
est idist*2.
#include <rfftw.h> void rfftwnd_destroy_plan(rfftwnd_plan plan);
La fonction rfftwnd_destroy_plan libère le plan
plan et libère toute la mémoire qui y est
associée. Après la destruction, un plan n'est plus
valide.
Les conventions que nous suivons pour les transformées réelles multi dimension sont analogues à celles des transformées complexes multi dimension. En particulier, la transformée directe a un signe négatif dans l'exposant et ni la transformée directe, ni l'inverse ne sont normalisées. Calculer la transformée inverse de la transformée directe multipliera le tableau par le produit de ses dimensions. (ce qui signifie, les dimensions logiques des données réelles). La transformée directe est réelle-vers-complexe et la transformée inverse est complexe-vers-réelle.
Les Dieux nous ont interdit le HTML pour afficher les formules mathématiques. Please voyez les versions TeX ou Postscript de ce manuel pour les définitions correctes des transformées de Fourier réelles à n-dimension qu'utilise RFFTW. Pour être complets, nous incluons un bitmap de la sortie TeX ci-dessous :
#include <fftw.h> void fftw_export_wisdom(void (*emitter)(char c, void *), void *data); void fftw_export_wisdom_to_file(FILE *output_file); char *fftw_export_wisdom_to_string(void);
Ces fonctions vous permettent d'exporter tous les wisdom
actuellement accumulés dans une forme qui peut être plus
tard importés et restaurés, même pendant un
calcul séparé du programme. (Voir la Section Mots
de Sagesse). Le stock actuel de wisdom n'est pas
affecté par l'appel d'une de ces routines.
fftw_export_wisdom exporte wisdom vers
tout support de sortie, comme spécifié par la fonction
de rappel emitter. emitter est une fonction
ressemblant à putc qui écrit le caractère
c sur une sortie; son second paramètre est le
pointeur data passé à fftw_export_wisdom.
Pour le confort, les deux routines "wrapper" sont fournies
:
fftw_export_wisdom_to_file écrit wisdom
dans la position actuelle vers output_file, qui doit
être ouvert avec la permission d'écriture. Après
la sortie, le fichier reste ouvert et positionné à la
fin des données wisdom.
fftw_export_wisdom_to_string retourne un pointeur
vers une chaine terminée par un NULL contenant
les données wisdom. Cette chaine est dynamique et
c'est la responsabilité de l'appelant de la désallouer
avec fftw_free lorsqu'elle n'a plus d'utilité.
Toutes ces routines exportent wisdom dans le même format, qui n'est pas documenté ici excepté pour dire qu'il est en texte ressemblant au LISP ASCII insensible aux espaces blancs.
#include <fftw.h> fftw_status fftw_import_wisdom(int (*get_input)(void *), void *data); fftw_status fftw_import_wisdom_from_file(FILE *input_file); fftw_status fftw_import_wisdom_from_string(const char *input_string);
Ces fonctions importent wisdom dans un programme à
partir de données stockées par les fonctions
fftw_export_wisdom ci-dessous. (Voir Section Mots
de Sagesse). Le wisdom importé est un
supplément plutôt qu'un remplacement de tous les wisdom
déjà accumulés par le programme tournant
(excepté lorsqu'il y a un conflit avec wisdom,
auquel cas le wisdom existant est remplacé).
fftw_import_wisdom importe wisdom à
partir de tout média d'entrée, comme spécifié
dans la fonction de rappel get_input. get_input
est une fonction ressemblant à getc qui retourne
le caractère suivant de l'entrée; son paramètre
est le pointeur data passé à
fftw_import_wisdom. Si la fin de la donnée
d'entrée est trouvée (ce qui ne doit jamais survenir
avec des données valides), il doit retourner soit un NULL
(ASCII 0) ou EOF (comme défini dans <stdio.h>).
Pour le confort, les deux routines "wrapper" sont fournies
:
fftw_import_wisdom_from_file lit wisdom
à partir de la position actuelle dans input_file,
qui doit être ouvert avec la permission de lecture. A la
sortie, le fichier reste ouvert et est positionné à la
fin des données wisdom.
fftw_import_wisdom_from_string lit wisdom
à partir d'une chaine, terminée par un NULL,
input_string.
La valeur de retour des ces routines est FFTW_SUCCESS
si wisdom a été lu avec succès et FFTW_FAILURE
sinon. Notez que, dans toutes ces fonctions, toute donnée du
flux d'entrée venant après la fin des données
wisdom est simplement ignorée (elle n'est
simplement pas lue si la donnée wisdom est bien
formatée).
#include <fftw.h> void fftw_forget_wisdom(void);
Appeler fftw_forget_wisdom met de coté tous les
wisdom et la mémoire associée est libérée.
(Un nouveau wisdom peut par conséquent être
encore rassemblé).
#include <fftw.h> void *(*fftw_malloc_hook) (size_t n); void (*fftw_free_hook) (void *p);
Lorsqu'il a besoin d'allouer ou de libérer de la mémoire,
FFTW appelle normalement malloc et free. Si
malloc échoue, FFTW écrit des messages
d'erreur et s'arrête. Ce comportement peut être
indésirable dans certaines applications. Donc, des fonctions
spéciales de traitement de la mémoire peuvent être
nécessaire dans certains environnements. Par conséquent,
FFTW fournit les moyens par lesquels vous pouvez installer votre
propre allocateur de mémoire et prend toutes les actions de
corrections d'erreur que vous trouvez approprié. Les variables
fftw_malloc_hook et fftw_free_hook sont des
pointeurs vers des fonctions et ils sont normalement à NULL.
Si vous positionnez ces variables pour pointer vers d'autres
fonctions, alors FFTW utilisera vos routines à la place de
malloc et free. fftw_malloc_hook
qui devront pointer vers un clone de malloc et
fftw_free_hook doit pointer vers un clone de free.
Les utilisateurs écrivant des programmes multi threads
doivent se sentir concernés par la sécurité
des threads des bibliothèques qu'ils utilisent --ceci
étant, il faut que ce soit sans danger d'appeler des routines
en parallèle à partir de multiples threads. FFTW peut
être utilisé dans un tel environnement mais il faut
faire attention car certaines parties de FFTW utilisent des variales
globales privées pour partager les données entre les
appels. En particulier, la fonction de création de plan
partage les tables trigonométriques et accumule wisdom.
(Les utilisateurs doivent noter que ces commentaires s'appliquent
seulement aux programmes utilisant la mémoire partagée
des threads. Le parallélisme utilisant MPI ou les processus
forks impliquent un espace d'adresse séparé et des
variables globales pour chaque process et n'est pas susceptible aux
problèmes de cette sorte).
La restriction centrale de FFTW est qu'il n'est pas sans risque de
créer des plans multiples en parallèle. Vous devez soit
créer tous vos plans à partir d'un simple thread, soit
utiliser un sémaphore, mutex, ou autre mécanisme pour
s'assurer que différents threads ne tentent pas de créer
des plans en même temps. La même restriction peut aussi
s'appliquer pour les destructions de plan et l'import de wisdom.
Une fois créé, un plan peut être utilisé
sans danger dans tout thread.
Les routines réelles des transformées dans FFTW
(fftw_one, etc) sont re-entrant et sans danger pour les
threads, il est donc fin de les appeler simultanément pour des
threads multiples. D'autres questions se lèvent néanmoins
--est-il sans danger d'utiliser le même plan pour des
transformées multiples en parallèle? (Il serait
dangeureux si, par exemple, le plan était modifié d'une
certaine manière par la transformée). Nous répondons
à cette question en définissant un drapeau de plan
additionnel, FFTW_THREADSAFE. Lorsqu'il est inclu dans
les drapeaux, pour toute routine de création de plan,
FFTW_THREADSAFE garantit que le plan résultant
sera à lecture seule et sans danger pour toutes les
utilisations en parallèle par des threads multiples.
Go to the first, previous, next, last section, table of contents.