Units/it

Alcune letture sulle unità di misura:
 * Sistema Internazionale di Misura SI
 * Sistema imperiale britannico
 * SI derived unit (in italiano si trovano nella stessa pagina del SI)
 * Grado d'arco - Unità angolari

Esempi
# -- alcuni esempi del sistema di traduzione di unità di FreeCAD -- FreeCAD.Units.parseQuantity tu('10 m') tu('3/8 in') tu('100 km/h') tu('100 km/h')/tu('m/s') tu('m^2*kg*s^-3*A^-2') # or tu('(m^2*kg)/(A^2*s^3)') tu('2*pi rad') # full circle tu('2*pi rad') / tu('gon') tu('1ft+(3+7/16)in') tu('1\'(3+7/16)"') # the ' we have to escape because of python tu('sin(pi)') b = Part.makeBox(tu('2in'),tu('2m')/100,10)
 * 1) creare un collegamento per gli esempi
 * 1) 10 meters in internal numbers
 * 1) doing math
 * 1) combined stuff
 * 1) transfer to other units
 * 1) derived units (Ohm)
 * 1) angles
 * 1) as gon
 * 1) more imperial
 * 1) or
 * 1) trigonometry
 * 1) Using translated units as parameters, this command will create a 50.8mm x 20mm x 10mm box

Unità di misura supportate
Queste sono le unità finora definite in FreeCAD. È facile aggiungere una nuova unità definita dall'utente. La definizione si trova in http://free-cad.svn.sourceforge.net/viewvc/free-cad/trunk/src/Base/UnitsApi.l?view=markup.

Lunghezza metrica "mm"   1.0;        // millimetro       (lunghezza standard interna) "m"    1000.0;     // metro "cm"   10.0;       // centimetro "dm"   100.0;      // decimetro "km"   1000000.0;  // kilometro

Lunghezza Imperiale "in" "\"" 25.4;       // inch "ft" "'"   304.8;      // foot "th"       0.0254;     // thou "yr"       914.4;      // yard

Massa metrica "kg"   1.0;        // kilogrammo       (massa standard interna) "g"    0.001;      // grammo "mg"   0.000001;   // milligrammo "t"    1000.0;     // tonnellata

Massa Imperiale "lb"   0.45359237; // pound "oz"   0.45359237; // ounce "st"   6.35029318; // Stone "cwt"  50.80234544;// hundredweights

Angolo "deg"  1.0;        // gradi         (angolo standard interno) "rad"  180/M_PI;   // radianti "gon"  360.0/400.0;// gon Tempo "s"    1.0;        // secondo         (tempo standard interno) "min"  60.0;       // minuto "h"    3600.0;     // ora

Altro del SI "A"    1.0;        // Ampere         (internal standard electric current) "K"    1.0;        // Kelvin         (internal standard thermodynamic temperature) "cd"   1.0;        // Candela        (internal standard luminous intensity) "mol"  1.0;        // Mole           (internal standard amount of substance) Volume metrico "µl"   1.0;        // microliter mm^3(volume standard derivato) "ml"   1000.0;     // milliliter cm^3 "l"    1000000.0;  // Liter      dm^3

Finalità e principi: proposta di una estensione del sistema di gestione delle unità
Nelle sezioni successive, sviluppando il concetto di sistema di unità, si propone un sistema di gestione delle unità di misura attivato nel corso dell'esecuzione di una istanza di FreeCAD. Definire tale nuovo concetto offre il vantaggio di lavorare più facilmente con tanti tipi di unità fisiche, quante si vuole, anche con quelle create dall'utente, senza aumentare la complessità di gestione delle unità, né per l'utente, né per gli sviluppatori di FreeCAD.

In breve, gli eventi di scalatura delle unità sono localizzati con precisione, e realizzati in modo globale.

Il raggiungimento di tale flessibilità è necessario specialmente quando si passa a lavorare con le proprietà dei materiali che possono avere unità molto diverse e quindi difficili da gestire manualmente una ad una.

Il ragionamento proposto permette di gestire le unità come descritto nella Guida per l'uso del Sistema Internazionale delle unità di misura (SI) e nel Sistema internazionale delle unità di misura (SI), entrambi documenti del NIST.

In questa proposta, la prima analisi nella sezione Riflessioni riguarda i possibili contesti per i quali è utile la gestione delle unità.

Nella sezione Organizzazione è presentato il modello di dati prescelto per realizzare la gestione delle unità, sulla base di 3 oggetti, la unità, il dizionario delle unità, e il sistema delle unità. Infine, è anche presentata una breve API di un quarto oggetto chiamato gestore delle unità.

Risultati
Grazie a questa estensione, si mira ad agevolare la scalatura della unità che può verificarsi tra i differenti settori di lavoro di una azienda. Ad esempio, i disegni tecnici possono essere realizzati nel sistema di unità standard, mentre la modellazione per elementi finiti può essere gestita in un sistema di unità più adatto per questo scopo.

Con questa estensione lo scambio di dati tra questi due tipi di attività diventa più facile.

Riflessioni
In questa sezione sono evidenziati i contesti (casi) di uso del sistema di gestione delle unità. Partendo da questi contesti, dopo siamo in grado di definire le loro specifiche tecniche.

Essenzialmente sono considerati 2 contesti, come esempio.

Contesto 1: apertura di un file di dati
Questo caso probabilmente è quello più frequente. Si riceve un file contenente ad esempio un modello geometrico, o descrivente un materiale con un bel po' di proprietà. Il modello geometrico è espresso in metri, oppure le proprietà del materiale sono espresse secondo il sistema internazionale di unità di misura.

Peccato ...

Sei un esperto di modellazione di elementi finiti (FE modelling), e di solito lavori con i millimetri per la lunghezza, megapascal per la pressione, tonnellate per la massa ...

In questo contesto, la gestione delle unità è necessaria per scalare i dati da un sistema di unità iniziale definito nel file di input a un diverso sistema di unità definito dall'utente.

Contesto 2: commutare il sistema di unità in fase di esecuzione
In questo caso, si può essere allo stesso tempo, la persona che realizza un disegno, e anche chi gestirà la modellazione per elementi finiti. Analogamente al caso precedente, i sistemi di unità di misura per questi due lavori non sono gli stessi, ed è necessario cambiare il sistema di unità iniziale in quello preferito durante l'esecuzione.

Logica di scalatura delle unità
Nella sezione Riflessioni sono stati presentati due contesti in merito a quando si utilizza la scalatura delle unità. Devono essere evidenziati alcuni aspetti di questi due contesti.

Coerenza di unità in tutta l'istanza in esecuzione in FreeCAD
Il sistema proposto si basa su un assunto primario: l'utente sta lavorando in un sistema di unità coerenti. Ad esempio, questo significa che, se l'utente esprime la lunghezza in millimetri, necessariamente le aree saranno espresse in termini di millimetri quadrati e non in metri quadrati. Questa è la Ipotesi numero uno.

Sistema di unità
In conseguenza della Ipotesi numero uno, è possibile e pertinente definire un sistema di unità. Un sistema di unità si applica a: Secondo la Guida per l'uso del Sistema Internazionale di unità di misura (SI) del NIST, ci sono 7 unità fisiche di base. Abbiamo scelto di formulare un sistema di unità in termini di questi 7 unità di base.
 * una istanza in esecuzione in FreeCAD su cui si sta lavorando
 * oppure si può anche applicare globalmente al contenuto di un file di input

Quando si lavora all'interno di un'istanza di FreeCAD, l'utente deve quindi definire il sistema di unità base con cui sta lavorando prima di decidere di passare a un altro sistema di unità, o prima di importare dati da un file di input.

Questo sistema di unità si applica fino a che l'utente non decide di cambiarlo. Se lo fà, tutti i dati con dimensioni vengono scalati.

Considerando l'Ipotesi numero uno, si presume che tutti i dati che l'utente inserirà manualmente in FreeCAD saranno coerenti con il sistema di unità prescelto.

Il vantaggio di lavorare con un sistema di unità definito a livello di un'istanza in esecuzione in FreeCAD, o a livello di file di dati (al posto delle singole unità che sono definite a livello di dati) consiste nella notevole semplificazione della gestione delle unità.

Ecco alcuni esempi di sistemi di unità.
 * metro, kilogrammo, secondo, ampere, Kelvin, mole, candela
 * millimetro, tonnellata, millisecondo, ampere, Kelvin, mole, candela
 * millimetro, kilogrammo, millisecondo, ampere, Kelvin, mole, candela

Unità di base e derivate
Le Unità derivate sono create mediante la combinazione delle unità di base. Ad esempio, un'accelerazione (m/s2) unisce contemporaneamente la lunghezza e il tempo. Un quadro interessante che presenta le relazioni tra le unità base e le unità derivate si può vedere in questo documento, anche esso del NIST.

Grazie alla definizione del sistema di unità, l'utente può lavorare con qualsiasi tipo di unità derivata, senza la necessità che gli sviluppatori di FreeCAD le prevedano prima.

Simboli delle unità base e delle derivate
Secondo il Sistema Internazionale delle unità di misura (SI), i simboli per specificare una unità sono ufficialmente approvati. Da questo possono essere evidenziate due conseguenze.
 * per un programma del computer non è facile lavorare con i simboli delle unità perché, per esempio, alcuni sono lettere greche. Quindi per un programma possono essere un po' difficili da elaborare
 * anche se alcune unità (e i suoi simboli) possono essere ampiamente (normalmente) utilizzate, esse possono non essere approvate ufficialmente, come ad esempio l'unità di tonnellata (si veda p32 del Sistema Internazionale di unità di misura (SI))

To overcome these limitations and remain flexible, the proposed system favors the use of unit magnitudes instead of unit symbols, which remain nonetheless available for an ergonomy reason.

Data model
The three core objects of the unit management system are presented, namely the unit, the unit dictionary and the unit system.

Unit
As a foreword, it is important to highlight that a unit object in itself only indicates a dimension like length, mass, time... It doesn't specify a magnitude like meter, millimeter, kilometer... This last information is specified through the unit system.

Dimension
Compulsory string indicating the dimension of the unit. The dimension of the 7 base units are indicated below (from Guide for the Use of the International System of Units (SI)).
 * LENGTH
 * MASS
 * TIME
 * ELECTRIC CURRENT
 * THERMODYNAMIC TEMPERATURE
 * AMOUNT OF SUBSTANCE
 * LUMINOUS INTENSITY

Dimension attribute allows identifying the unit. Two units cannot share the same dimension.

Signature
Compulsory integer array of size 7 (number of base units) that defines what the unit is. The signature of the 7 base units are:
 * LENGTH: [1,0,0,0,0,0,0]
 * MASS: [0,1,0,0,0,0,0]
 * TIME: [0,0,1,0,0,0,0]
 * ELECTRIC CURRENT: [0,0,0,1,0,0,0]
 * THERMODYNAMIC TEMPERATURE: [0,0,0,0,1,0,0]
 * AMOUNT OF SUBSTANCE: [0,0,0,0,0,1,0]
 * LUMINOUS INTENSITY: [0,0,0,0,0,0,1]

From these 7 units, we are then able to express all derived units defined in Guide for the Use of the International System of Units (SI) and create new ones as needed such as for instance:
 * MASS DENSITY: [-3,1,0,0,0,0,0]
 * AREA: [0,2,0,0,0,0,0]

Signature is the attribute thanks to which unit scaling can be achieved in a generic way.

Symbols
Array of [real, string] (meaning [magnitude, symbol]) that lists all symbols known by FreeCAD. Thanks to this array, the unit scaling API becomes more ergonomic because symbols and related magnitudes are linked.

This array can be extended as required.

For instance, the list of symbols of the LENGTH unit, and their related magnitudes is:

[1e+12,"Tm"],[1e+09,"Gm"],[1e+06,"Mm"], [1e+03,"km"],[1e+02,"hm"],[1e+01,"dam"], [1e+00,"m"],[1e-01,"dm"],[1e-02,"cm"], [1e-03,"mm"],[1e-06,"µm"],[1e-09,"nm"], [1e-12,"pm"],[1e-15,"fm"]

Standard symbols can be found on NIST website and p23 to 26 and p32 (metric ton or tonne) of The International System of Units (SI).

Unit dictionary
All the units available in FreeCAD, and new ones created by the user, should be stored in unit dictionary, which is an XML file (FreeCAD configuration file), so as to be retrieved when needed, i.e. when achieving unit scaling.

Units
Array of units, contained in the unit dictionary.

Unit system
A unit system is the object that allows the user defining the current unit magnitude of each base units with which she/he is working. For instance, knowing that the user is working with millimeter, tonne, and second, thanks to the use of a unit system, FreeCAD can know that energy is expressed in terms of milliJoule, force in terms of Newton, and stress in terms of MegaPascal. Hence a unit system is only defined by a name (for instance Standard unit system) and a magnitude table specifying for each of the 7 base units, what is its corresponding magnitude.

Name
String allowing to the user identifying what is the unit system.

Magnitudes
By specifying the magnitude of the 7 base units, a unit system is defined.

For instance [1e-03, 1e+03, 1, 1, 1, 1, 1], meaning millimeter, tonne, second, ampere, Kelvin, mole, candela

Unit management API
Only the logic of some methods is presented, in order to highlight some features. These methods could belong to an object called Unit manager.

isValid
The unit dictionary can be an XML file (FreeCAD configuration file). It contains a list of defined units. Such a dictionary is required for the proposed unit management system to work.

It must fulfills some conditions that should be checked before activating the unit management system. These conditions are:
 * check that all base units are defined
 * check that a dimension is not defined twice through the units
 * check that a symbol is not defined twice in all the existing symbols
 * check that the signatures of all units have all the same size
 * chacke that a standard symbol (for which magnitude is 1) is defined for all units

isCompatibleWithThisSignature
A unit dictionary defines a set of units and their known magnitudes. When managing a unit, it is relevant to check that its signature is compatible with the set of units registered in the unit dictionary, so as to process it. This check includes:
 * check that the input signature length is of the same size than the unit dictionary unit signatures

scaleUnitFromSymbolToSymbol
Knowing a value, an initial unit by its symbol, the target unit by its symbol, scale the value.

scaleUnitFromSymbolToUnitSystem
Knowing a value, an initial unit by its symbol, the target unit system, scale the value.

scaleUnitFromUnitSystemToSymbol
Knowing a value, an initial unit system, the target unit by its symbol, scale the value.

Motivations for such a management: example of application
Let's assume that we are going to setup a finite element model. To build our model, we need the mesh, material properties, and to define numerical parameters. Considering that they can be tens of material properties to manage, expressed with different units, sometimes not always very common, it is interesting for the user to only have to specify a global unit system, without caring much.

FreeCAD would then just do the job.

As FreeCAD developpers and FreeCAD users do not necessarily know all units that can be defined in the material property files, it is interesting to rely on a generic system.

Let's assume that in such a file we have a fair number of exotic material properties expressed with exotic units, and that we want to work in a specific unit system.

It is easy with the proposed extension to scale any of these properties by knowing their signatures, magnitudes, and the target unit system.

For each of the properties, the scaling is obtained by multiplying the initial property value with the factor $$\frac{initialMagnitude}{targetMagnitude}$$.

The targetMagnitude is then simply obtained with the operation $$\prod_{bu} targetMagnitude_{bu}^{signature_{bu}}$$, bu standing for base unit.

It becomes thus very easy to manage any number of properties with any kind of units with very few lines of Python.

Next actions

 * Implementing Quantity and Unit classes (mostly done)
 * Implementing InputField as User front end (in progress)
 * UnitsCalculator as test bed (in progress)
 * Quantity documentation (in progress)
 * UnitsCalculator documentation
 * Update Material framework to work only with Quantities
 * Test Cases