Units/it: Difference between revisions

From FreeCAD Documentation
m (minor)
(Updating to match new version of source page)
Line 1: Line 1:
Here some reading about units:
== Le unità di misura ==
*[http://en.wikipedia.org/wiki/International_System_of_Units SI system]
*[http://en.wikipedia.org/wiki/Imperial_units Imperial units]
*[http://en.wikipedia.org/wiki/SI_derived_unit SI derived units]
*[http://en.wikipedia.org/wiki/Degree_%28angle%29 angle units]


== Examples ==
Alcune letture sulle unità di misura:
*[http://it.wikipedia.org/wiki/Sistema_internazionale_di_unit%C3%A0_di_misura Sistema Internazionale di Misura SI]
*[http://it.wikipedia.org/wiki/Sistema_imperiale_britannico Sistema imperiale britannico]
*[http://en.wikipedia.org/wiki/SI_derived_unit SI derived unit] (in italiano si trovano nella stessa pagina del SI)
*[http://it.wikipedia.org/wiki/Grado_d%27arco Grado d'arco - Unità angolari]


# -- some examples of the FreeCAD unit translation system --
___TOC___
# make a shortcut for the examples

tu = FreeCAD.Units.parseQuantity
== Esempi ==

# -- alcuni esempi del sistema di traduzione di unità di FreeCAD --
# creare un collegamento per gli esempi
FreeCAD.Units.parseQuantity
# 10 meters in internal numbers
# 10 meters in internal numbers
Line 32: Line 28:
tu('2*pi rad') / tu('gon')
tu('2*pi rad') / tu('gon')
# more imperial
# more imperial
tu('1ft+(3+7/16)in')
tu('1ft (3+7/16)in')
# or
# or
tu('1\'(3+7/16)"') # the ' we have to escape because of python
tu('1\' (3+7/16)"') # the ' we have to escape because of python
# trigonometry
# trigonometry
tu('sin(pi)')
tu('sin(pi)')
Line 40: Line 36:
b = Part.makeBox(tu('2in'),tu('2m')/100,10)
b = Part.makeBox(tu('2in'),tu('2m')/100,10)


== Supported units ==
== Unità di misura supportate ==
Here the defined units in FreeCAD so far. It's easy to add a new user defined unit. The definition is here[http://free-cad.svn.sourceforge.net/viewvc/free-cad/trunk/src/Base/UnitsApi.l?view=markup].


Metric length
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.
"mm" 1.0; // millimeter (internal standard length)
"m" 1000.0; // meter
"cm" 10.0; // centimeter
"dm" 100.0; // decimeter
"km" 1000000.0; // kilometer


Imperial lenth
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
"in" "\"" 25.4; // inch
"ft" "'" 304.8; // foot
"ft" "'" 304.8; // foot
"th" 0.0254; // thou
"th" 0.0254; // thou
"yr" 914.4; // yard
"yr" 914.4; // yard

Massa metrica
Metric mass
"kg" 1.0; // kilogrammo (massa standard interna)
"g" 0.001; // grammo
"kg" 1.0; // kilogram (internal standard mass)
"mg" 0.000001; // milligrammo
"g" 0.001; // gram
"t" 1000.0; // tonnellata
"mg" 0.000001; // milligram
"t" 1000.0; // ton
Massa Imperiale

Imperial mass
"lb" 0.45359237; // pound
"lb" 0.45359237; // pound
"oz" 0.45359237; // ounce
"oz" 0.45359237; // ounce
"st" 6.35029318; // Stone
"st" 6.35029318; // Stone
"cwt" 50.80234544;// hundredweights
"cwt" 50.80234544;// hundredweights

Angolo
Angle
"deg" 1.0; // gradi (angolo standard interno)
"rad" 180/M_PI; // radianti
"deg" 1.0; // degree (internal standard angle)
"gon" 360.0/400.0;// gon
"rad" 180/M_PI; // radian
"gon" 360.0/400.0;// gon
Tempo
"s" 1.0; // secondo (tempo standard interno)
Time
"min" 60.0; // minuto
"h" 3600.0; // ora
"s" 1.0; // second (internal standard time)
"min" 60.0; // minute
Altro del SI
"h" 3600.0; // hour

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


== Purpose and principles: proposal of an extension of the unit management system ==
== Finalità e principi: proposta di una estensione del sistema di gestione delle unità ==


An extension unit management system is proposed in the following sections, developping the concept of ''unit system'', activated during a running FreeCAD instance.
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.
The interest in defining such a new concept is to work more easily with as many type of '''physical''' units as one wants (even user-created ones), without increasing the complexity of unit management for the user, nor for FreeCAD developpers.


In short, event of unit scaling are localized precisely, and carried out in a generic fashion.
In breve, gli eventi di scalatura delle unità sono localizzati con precisione, e realizzati in modo globale.


Achieving such a flexibility is most notably required when one starts to deal with material properties that can have very different units, difficult to manage one by one manually.
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 [http://physics.nist.gov/cuu/pdf/sp811.pdf Guida per l'uso del Sistema Internazionale delle unità di misura (SI)] e nel [http://physics.nist.gov/Pubs/SP330/sp330.pdf Sistema internazionale delle unità di misura (SI)], entrambi documenti del NIST.
The reasoning proposed allows handling the units such as described in the [http://physics.nist.gov/cuu/pdf/sp811.pdf Guide for the Use of the International System of Units (SI)] and [http://physics.nist.gov/Pubs/SP330/sp330.pdf The International System of Units (SI)] both from NIST.


In this proposal, one first recall in [[Units#Brainstorming|Brainstorming]] section what are the possible contexts for which unit management is required.
In questa proposta, la prima analisi nella sezione [[Units/it#Riflessioni|Riflessioni]] riguarda i possibili contesti per i quali è utile la gestione delle unità.


In [[Units#Organizing|Organizing]] section, we present the data model retained to achieve unit management, based on 3 objects, the ''unit'', the ''unit dictionary'', and the ''unit system''.
Nella sezione [[Units/it#Organizzazione|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à''.
Finally, a short API of a 4th object called the ''unit manager'' is presented as well.


== Risultati ==
== Outcome ==
Thanks to this extension, one aims to ease unit scaling that can occurs between different business tasks. For instance, technical drawings can be done in standard unit system, while FE modelling can be managed in an unit system more suited for it.


The exchange of data between these two kind of activities become easier with this extension.
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.


== Brainstorming ==
Con questa estensione lo scambio di dati tra questi due tipi di attività diventa più facile.
In this section are highlighted the contexts of use of such an unit management system.
From these contexts, we are then able to defined its technical specifications.


Essentially 2 contexts are given as example.
== Riflessioni ==


=== Context 1: opening a data file ===
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.
This case is probably the most frequent case.
You receive a file containing for instance a geometrical model, or describing a material with quite a lot of properties. The geometrical model is expressed in meters, or the material properties according the international unit system.


Too bad...
Essenzialmente sono considerati 2 contesti, come esempio.


You are an expert FE modelling, and you usually work with millimeter for length, MegaPascal for stress, tonne for mass...
=== Contesto 1: apertura di un file di dati ===


In this context, unit management is required to scale data from an initial unit system defined in the input file to a user-defined target unit system.
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.


=== Context 2: switching the unit system at runtime ===
Peccato ...
In this case, you can be at the same time the guy that carries out a drawing, and the guy that will manage the FE modelling. Similarly to the previous case, the unit systems for these 2 tasks are not the same, and you need to switch the initial unit system at runtime to your favorite one.


== Organizing ==
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 ...


=== Logic of unit scaling ===
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.
In the [[Units#Brainstorming|Brainstorming]] section have been presented 2 contexts when using unit scaling.
Some items should be highlighted from these two contexts.


==== Unit coherence throughout the FreeCAD running instance ====
=== Contesto 2: commutare il sistema di unità in fase di esecuzione ===
The system proposed is based on a primary assumption: the user is working in a coherent unit system.
For instance, this means that if the user expresses length in millimeters, necessarily areras will be expressed in terms of squared millimeters, not squared meters.
This is '''hypothesis one'''.


==== Unit system ====
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.
Because of ''hypothesis one'', it is possible and relevant to define an unit system.

An unit system applies to:
== Organizzazione ==
* a running FreeCAD instance into which you are working

* or it may also apply globally to the content of an input file
=== Logica di scalatura delle unità ===
According [http://physics.nist.gov/cuu/pdf/sp811.pdf Guide for the Use of the International System of Units (SI)] from NIST, they are 7 physical base units.

We chose to express a unit system in terms of these 7 base units.
Nella sezione [[Units/it#Riflessioni|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:
* una istanza in esecuzione in FreeCAD su cui si sta lavorando
* oppure si può anche applicare globalmente al contenuto di un file di input
Secondo la [http://physics.nist.gov/cuu/pdf/sp811.pdf 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.


When working within an instance of FreeCAD, the user has thus to define first the unit system according to which she/he is working before she/he decides to switch to another unit system, or before importing data from an input file.
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.


This unit system will apply till the user decides to change it. If she/he does, all data with dimensions will be scaled.
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.


Considering ''hypothesis one'', all data that the user will input manually in FreeCAD are assumed to be coherent with the chosen unit system.
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.


The benefit to work with a ''unit system'' defined at a FreeCAD running instance level, or at data file level (instead of ''unit'' which are defined at the data level) is then that unit management is considerably simplified.
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à.


Here are some examples of unit systems.
Ecco alcuni esempi di sistemi di unità.
* metro, kilogrammo, secondo, ampere, Kelvin, mole, candela
* meter, kilogram, second, ampere, Kelvin, mole, candela
* millimetro, tonnellata, millisecondo, ampere, Kelvin, mole, candela
* millimeter, tonne, millisecond, ampere, Kelvin, mole, candela
* millimetro, kilogrammo, millisecondo, ampere, Kelvin, mole, candela
* millimeter, kilogramme, millisecond, ampere, Kelvin, mole, candela
*...
*...


==== Unità di base e derivate ====
==== Base and derived units ====
Derived units are created by combination of base units. For instance, an acceleration (m/s) combines at the same time length and time. An interesting picture presenting the relationships between base and derived units can be seen [http://physics.nist.gov/cuu/pdf/SIDiagramColorAnnot.pdf here] also from NIST.


Thanks to the definition of ''unit system'', it is possible for the user to work with any kind of derived units, without the need for FreeCAD developpers to foresee them in advance.
Le Unità derivate sono create mediante la combinazione delle unità di base. Ad esempio, un'accelerazione (m/s<sup>2</sup>) 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 [http://physics.nist.gov/cuu/pdf/SIDiagramColorAnnot.pdf questo documento], anche esso del NIST.


==== Base and derived unit symbols ====
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.
According to [http://physics.nist.gov/Pubs/SP330/sp330.pdf The International System of Units (SI)], the symbols to specify a units are officially approved. Two consequences can be highlighted from this.
* it is not easy for a computer program to work with unit symbols because some are greek letters for instance. Hence they can be a bit difficult to process by a program
* while some units and their symbols can be used widely, they may be not approved officially, like for instance ''tonne'' unit (see p32 of [http://physics.nist.gov/Pubs/SP330/sp330.pdf The International System of Units (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.
==== Simboli delle unità base e delle derivate ====


=== Data model ===
Secondo il [http://physics.nist.gov/Pubs/SP330/sp330.pdf Sistema Internazionale delle unità di misura (SI)], i simboli per specificare una unità sono ufficialmente approvati. Da questo possono essere evidenziate due conseguenze.
The three core objects of the unit management system are presented, namely the ''unit'', the ''unit dictionary'' and the ''unit system''.
* 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 [http://physics.nist.gov/Pubs/SP330/sp330.pdf Sistema Internazionale di unità di misura (SI)])


==== Unit ====
Per superare queste limitazioni e rimanere flessibili, il sistema proposto privilegia l'impiego di unità di grandezze (magnitudini) invece dei simboli di unità, che rimangono comunque disponibili per motivi di ergonomia.
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.


=== Modello dei dati ===
===== Dimension =====
Compulsory string indicating the ''dimension'' of the unit. The ''dimension'' of the 7 base units are indicated below (from [http://physics.nist.gov/cuu/pdf/sp811.pdf 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.
Sono presentati i tre oggetti principali del sistema di gestione di unità di misura , vale a dire l'''unità'', il ''dizionario delle unità'' e il ''sistema di unità''.
Two units cannot share the same ''dimension''.


==== Unità (unità di misura)====
===== Signature =====


Compulsory integer array of size 7 (number of base units) that defines what the unit is.
Come premessa, è importante sottolineare che un oggetto ''unità'' di per sé indica solo una '''dimensione''' (grandezza fisica) come lunghezza, massa, tempo ... Esso non specifica una '''grandezza''' (unità di misura) come metro, millimetro, chilometri ... Questa ultima informazione è specificata attraverso il sistema di unità.
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 [http://physics.nist.gov/cuu/pdf/sp811.pdf Guide for the Use of the International System of Units (SI)] and create new ones as needed such as for instance:
===== Dimensione (Grandezza fisica) =====
* 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.
Stringa obbligatoria che indica la ''dimensione'' (grandezza fisica) dell'unità. La ''dimensione'' delle 7 unità di base (le 7 grandezze fisiche di base) sono indicate di seguito (dalla [http://physics.nist.gov/cuu/pdf/sp811.pdf Guide for the Use of the International System of Units (SI)]) (Guida per l'uso del Sistema Internazionale di unità di misura).
* LENGTH - LUNGHEZZA
* MASS - MASSA
* TIME - TEMPO
* ELECTRIC CURRENT - CORRENTE ELETTRICA
* THERMODYNAMIC TEMPERATURE - TEMPERATURA TERMODINAMICA
* AMOUNT OF SUBSTANCE - QUANTITA' DI SOSTANZA
* LUMINOUS INTENSITY - INTENSITA' LUMINOSA


===== Symbols =====
L'attributo ''dimensione'' permette di identificare l'unità. Due unità non possono condividere la stessa ''dimensione''.
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.
===== Firma (Identificazione della grandezza fisica) =====


For instance, the list of ''symbols'' of the LENGTH unit, and their related ''magnitudes'' is:
E' un gruppo di 7 cifre intere obbligatorie (numero delle unità di misura di base) che definisce di quale unità si tratta.
La firma delle 7 unità di base sono:
* LENGTH - LUNGHEZZA: [1,0,0,0,0,0,0]
* MASS - MASSA: [0,1,0,0,0,0,0]
* TIME - TEMPO: [0,0,1,0,0,0,0]
* ELECTRIC CURRENT - CORRENTE ELETTRICA: [0,0,0,1,0,0,0]
* THERMODYNAMIC TEMPERATURE - TEMPERATURA TERMODINAMICA: [0,0,0,0,1,0,0]
* AMOUNT OF SUBSTANCE - QUANTITA' DI SOSTANZA: [0,0,0,0,0,1,0]
* LUMINOUS INTENSITY - INTENSITA' LUMINOSA: [0,0,0,0,0,0,1]

Con queste 7 unità siamo poi in grado di esprimere tutte le unità di misura derivate definite nella [http://physics.nist.gov/cuu/pdf/sp811.pdf Guida per l'uso del Sistema Internazionale di unità di misura (SI)] e anche di crearne di nuove secondo le esigenze personali, quali ad esempio:
* MASS DENSITY - DENSITA' : [-3,1,0,0,0,0,0]
* AREA - AREA: [0,2,0,0,0,0,0]

La ''firma'' è l'attributo grazie al quale la scalatura delle unità può essere realizzata in modo generale.

===== Simboli =====

Insieme di [numero reale, stringa] (rappresentante [''grandezza'', ''simbolo'']) che elenca tutti i ''simboli'' noti a FreeCAD. Grazie a questo insieme, l'API di scalatura delle unità diventa più ergonomica perché i ''simboli'' sono collegati alle ''grandezze'' correlate .

Questo insieme (array) può essere esteso quanto necessario.

Ad esempio, la lista dei ''simboli'' della unità di misura di lunghezza, e le loro relative ''grandezze'' è:


[1e+12,"Tm"],[1e+09,"Gm"],[1e+06,"Mm"],
[1e+12,"Tm"],[1e+09,"Gm"],[1e+06,"Mm"],
Line 223: Line 221:
[1e-12,"pm"],[1e-15,"fm"]
[1e-12,"pm"],[1e-15,"fm"]


I ''simboli'' standard possono essere trovati sul [http://physics.nist.gov/cuu/Units/units.html sito web del NIST] e da pag. 26 a pag. 23 e a pag. 32 (''tonnellata metrica o tonnellata'') di [http://physics.nist.gov/Pubs/SP330/sp330.pdf The International System of Units (SI)].
Standard ''symbols'' can be found on [http://physics.nist.gov/cuu/Units/units.html NIST website] and p23 to 26 and p32 (''metric ton'' or ''tonne'') of [http://physics.nist.gov/Pubs/SP330/sp330.pdf The International System of Units (SI)].


==== Dizionario delle unità ====
==== 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 =====
Tutte le unità di misura disponibili in FreeCAD, e anche quelle nuove create dall'utente, devono essere conservate nel ''dizionario delle unità'', che è un file XML (file di configurazione di FreeCAD), in modo da poter essere recuperate quando è necessario, ad esempio quando si realizza la scalatura delle unità.
Array of units, contained in the ''unit dictionary''.

===== Unità =====

Insieme delle unità, contenute nel ''dizionario delle unità''.


==== Unit system ====
==== 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 =====
Un ''sistema di unità'' è l'oggetto che permette all'utente di definire la ''grandezza'' dell'unità corrente di ciascuna delle unità di base con cui si sta lavorando. Ad esempio, sapendo che l'utente sta lavorando con i millimetri, le tonnellate e i secondi, grazie all'utilizzo di un sistema di unità, FreeCAD può sapere che l'energia è espressa in termini di milliJoule, la forza in termini di Newton, e la pressione in termini di MegaPascal.
String allowing to the user identifying what is the unit system.
Quindi un sistema di unità è definito solo da un ''nome'' (ad esempio ''Sistema di unità standard'') e da una ''tabella di grandezza'' specifica per ciascuna delle unità di base 7, che è la sua grandezza corrispondente.


===== Nome =====
===== 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
Stringa che permette all'utente di identificare il sistema di unità.


===== Grandezze =====
==== 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''.


===== Checking the unit dictionary =====
Specificando la grandezza delle 7 unità di base si definisce un sistema di unità.


====== isValid ======
Ad esempio [1e-03, 1e+03, 1, 1, 1, 1, 1], significa millimetri, tonnellata, secondo, ampere, Kelvin, mole, candela
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.
==== API di gestione di unità ====
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 ======
E' presentata solo la logica di alcuni metodi, per evidenziare alcune caratteristiche.
A unit dictionary defines a set of units and their known magnitudes.
Questi metodi potrebbero appartenere a un oggetto chiamato ''Gestore di unità''.
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''


===== Verifica del dizionario delle unità =====
===== Scaling units =====

====== isValid - Validità======

Il dizionario delle unità può essere un file XML (file di configurazione di FreeCAD). Esso contiene la lista delle unità definite. Tale dizionario è necessario affinchè il sistema di gestione dell'unità proposto funzioni.

Deve soddisfare alcune condizioni che devono essere controllate prima di attivare il sistema di gestione dell'unità.
Queste condizioni sono:
* verificare che tutte le unità di base siano definite
* verificare che una ''dimensione'' non sia definita due volte tramite le unità
* verificare in tutti i simboli esistenti che un ''simbolo'' non sia definito due volte
* verificare che le ''firme'' di tutte le unità abbiano tutte la stessa dimensione
* verificare che per tutte le unità sia definito un ''simbolo standard'' (per cui la ''grandezza'' è 1)

====== isCompatibleWithThisSignature - Compatibilità======

Un dizionario di unità definisce un insieme di unità e le loro grandezze note. Quando si gestisce una unità, è opportuno controllare che la sua firma sia compatibile con l'insieme di unità registrate nel dizionario di unità, in modo da elaborarla.
Questo controllo comprende:
* verificare che la lunghezza della ''firma'' da inserire sia della stessa dimensione delle ''firme'' del dizionario di unità

===== Scalare le unità =====


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

Conoscendo un valore, l'unità iniziale tramite il suo simbolo e l'unità di destinazione tramite il suo simbolo, scalare il valore.


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

Conoscendo un valore, l'unità iniziale tramite il suo simbolo e il sistema di unità di destinazione, scalare il valore.


====== scaleUnitFromUnitSystemToSymbol ======
====== 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 ====
Conoscendo un valore, un sistema di unità iniziale, l'unità di destinazione tramite il suo simbolo, scalare il valore.
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.
==== Le motivazioni per una tale gestione: esempio di applicazione ====


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.
Supponiamo di accingerci a creare un modello di elementi finiti. Per costruire il nostro modello, abbiamo bisogno della griglia (forma mesh), delle proprietà del materiale ed è necessario definire i parametri numerici. Considerando che possono esserci decine di proprietà dei materiali da gestire, espresse con diverse unità e a volte non sempre molto comuni, per l'utente è importante dover solo indicare un sistema globale di unità, senza altre preoccupazioni.


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.
Poi FreeCAD farebbe lui il lavoro.


It is easy with the proposed extension to scale any of these properties by knowing their signatures, magnitudes, and the target unit system.
Per gli sviluppatori e gli utenti di FreeCAD non è necessario conoscere tutte le unità che possono essere definite nei file delle proprietà del materiale, è utile fare affidamento su un sistema generico.


For each of the properties, the scaling is obtained by multiplying the initial property value with the factor <math>\frac{initialMagnitude}{targetMagnitude}</math>.
Supponiamo che in un file abbiamo un buon numero di proprietà dei materiali esotiche espresse con unità esotiche, e che vogliamo lavorare in un sistema di unità specifico.


The ''targetMagnitude'' is then simply obtained with the operation <math>\prod_{bu} targetMagnitude_{bu}^{signature_{bu}}</math>, ''bu'' standing for ''base unit''.
Con l'estensione proposta è facile scalare qualsiasi di queste proprietà conoscendo la loro firma, la grandezza e il sistema di unità di destinazione.


It becomes thus very easy to manage any number of properties with any kind of units with very few lines of Python.
Per ciascuna delle proprietà, la scalatura si ottiene moltiplicando il valore iniziale della proprietà per il fattore <math>\frac{Grandezzainiziale}{Grandezzafinale}</math>.

La ''Grandezza finale'' viene ottenuta semplicemente con l'operazione <math>\prod_{bu} Grandezzafinale_{bu}^{firma_{bu}}</math>, dove ''bu'' stà per ''unità di base''.

Diventa così molto facile gestire un numero qualsiasi di unità con qualsiasi tipo di unità tramite poche righe di Python.

== Prossime azioni ==


== Next actions ==
* Implementing Quantity and Unit classes (mostly done)
* Implementing Quantity and Unit classes (mostly done)
* Implementing InputField as User front end (in progress)
* Implementing InputField as User front end (in progress)
* UnitsCalculator as test bed (in progress)
* UnitsCalculator as test bed (in progress)
* [[Quantity/it|Quantity]] documentation (in progress)
* [[Quantity]] documentation (in progress)
* [[Std_UnitsCalculator/it|UnitsCalculator]] documentation
* UnitsCalculator documentation
* Update Material framework to work only with Quantities
* Update Material framework to work only with Quantities
* Test Cases
* Test Cases


{{languages/it | {{en|Units}} {{es|Units/es}} {{fr|Units/fr}} }}


[[Category:Poweruser Documentation/it]]
[[Category:Poweruser Documentation]]

{{clear}}
<languages/>

Revision as of 16:15, 30 November 2014

Here some reading about units:

Examples

# -- some examples of the FreeCAD unit translation system --
# make a shortcut for the examples
tu = FreeCAD.Units.parseQuantity

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

Supported units

Here the defined units in FreeCAD so far. It's easy to add a new user defined unit. The definition is here[1].

Metric length

"mm"    1.0;        // millimeter       (internal standard length)
"m"     1000.0;     // meter
"cm"    10.0;       // centimeter
"dm"    100.0;      // decimeter
"km"    1000000.0;  // kilometer

Imperial lenth

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

Metric mass

"kg"    1.0;        // kilogram       (internal standard mass)
"g"     0.001;      // gram
"mg"    0.000001;   // milligram
"t"     1000.0;     // ton 

Imperial mass

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

Angle

"deg"   1.0;        // degree         (internal standard angle)
"rad"   180/M_PI;   // radian         
"gon"   360.0/400.0;// gon   
     

Time

"s"     1.0;        // second         (internal standard time)
"min"   60.0;       // minute
"h"     3600.0;     // hour  

Rest of 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)
       

Metric Volume

"µl"    1.0;        // microliter mm^3(derived  standard volume)
"ml"    1000.0;     // milliliter cm^3    
"l"     1000000.0;  // Liter      dm^3

Purpose and principles: proposal of an extension of the unit management system

An extension unit management system is proposed in the following sections, developping the concept of unit system, activated during a running FreeCAD instance. The interest in defining such a new concept is to work more easily with as many type of physical units as one wants (even user-created ones), without increasing the complexity of unit management for the user, nor for FreeCAD developpers.

In short, event of unit scaling are localized precisely, and carried out in a generic fashion.

Achieving such a flexibility is most notably required when one starts to deal with material properties that can have very different units, difficult to manage one by one manually.

The reasoning proposed allows handling the units such as described in the Guide for the Use of the International System of Units (SI) and The International System of Units (SI) both from NIST.

In this proposal, one first recall in Brainstorming section what are the possible contexts for which unit management is required.

In Organizing section, we present the data model retained to achieve unit management, based on 3 objects, the unit, the unit dictionary, and the unit system. Finally, a short API of a 4th object called the unit manager is presented as well.

Outcome

Thanks to this extension, one aims to ease unit scaling that can occurs between different business tasks. For instance, technical drawings can be done in standard unit system, while FE modelling can be managed in an unit system more suited for it.

The exchange of data between these two kind of activities become easier with this extension.

Brainstorming

In this section are highlighted the contexts of use of such an unit management system. From these contexts, we are then able to defined its technical specifications.

Essentially 2 contexts are given as example.

Context 1: opening a data file

This case is probably the most frequent case. You receive a file containing for instance a geometrical model, or describing a material with quite a lot of properties. The geometrical model is expressed in meters, or the material properties according the international unit system.

Too bad...

You are an expert FE modelling, and you usually work with millimeter for length, MegaPascal for stress, tonne for mass...

In this context, unit management is required to scale data from an initial unit system defined in the input file to a user-defined target unit system.

Context 2: switching the unit system at runtime

In this case, you can be at the same time the guy that carries out a drawing, and the guy that will manage the FE modelling. Similarly to the previous case, the unit systems for these 2 tasks are not the same, and you need to switch the initial unit system at runtime to your favorite one.

Organizing

Logic of unit scaling

In the Brainstorming section have been presented 2 contexts when using unit scaling. Some items should be highlighted from these two contexts.

Unit coherence throughout the FreeCAD running instance

The system proposed is based on a primary assumption: the user is working in a coherent unit system. For instance, this means that if the user expresses length in millimeters, necessarily areras will be expressed in terms of squared millimeters, not squared meters. This is hypothesis one.

Unit system

Because of hypothesis one, it is possible and relevant to define an unit system. An unit system applies to:

  • a running FreeCAD instance into which you are working
  • or it may also apply globally to the content of an input file

According Guide for the Use of the International System of Units (SI) from NIST, they are 7 physical base units. We chose to express a unit system in terms of these 7 base units.

When working within an instance of FreeCAD, the user has thus to define first the unit system according to which she/he is working before she/he decides to switch to another unit system, or before importing data from an input file.

This unit system will apply till the user decides to change it. If she/he does, all data with dimensions will be scaled.

Considering hypothesis one, all data that the user will input manually in FreeCAD are assumed to be coherent with the chosen unit system.

The benefit to work with a unit system defined at a FreeCAD running instance level, or at data file level (instead of unit which are defined at the data level) is then that unit management is considerably simplified.

Here are some examples of unit systems.

  • meter, kilogram, second, ampere, Kelvin, mole, candela
  • millimeter, tonne, millisecond, ampere, Kelvin, mole, candela
  • millimeter, kilogramme, millisecond, ampere, Kelvin, mole, candela
  • ...

Base and derived units

Derived units are created by combination of base units. For instance, an acceleration (m/s) combines at the same time length and time. An interesting picture presenting the relationships between base and derived units can be seen here also from NIST.

Thanks to the definition of unit system, it is possible for the user to work with any kind of derived units, without the need for FreeCAD developpers to foresee them in advance.

Base and derived unit symbols

According to The International System of Units (SI), the symbols to specify a units are officially approved. Two consequences can be highlighted from this.

  • it is not easy for a computer program to work with unit symbols because some are greek letters for instance. Hence they can be a bit difficult to process by a program
  • while some units and their symbols can be used widely, they may be not approved officially, like for instance tonne unit (see p32 of The International System of Units (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.

Checking the unit dictionary
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
Scaling units
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 .

The targetMagnitude is then simply obtained with the operation , 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