View Javadoc
1   package org.djunits.quantity;
2   
3   import org.djunits.quantity.def.Quantity;
4   import org.djunits.unit.AbstractUnit;
5   import org.djunits.unit.UnitRuntimeException;
6   import org.djunits.unit.Unitless;
7   import org.djunits.unit.scale.LinearScale;
8   import org.djunits.unit.scale.Scale;
9   import org.djunits.unit.si.SIUnit;
10  import org.djunits.unit.system.UnitSystem;
11  
12  /**
13   * Volume is the amount of three-dimensional space occupied by matter, measured in cubic meters (m3).
14   * <p>
15   * Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
16   * for project information <a href="https://djunits.org" target="_blank">https://djunits.org</a>. The DJUNITS project is
17   * distributed under a <a href="https://djunits.org/docs/license.html" target="_blank">three-clause BSD-style license</a>.
18   * @author Alexander Verbraeck
19   */
20  public class Volume extends Quantity<Volume>
21  {
22      /** Constant with value zero. */
23      public static final Volume ZERO = ofSi(0.0);
24  
25      /** Constant with value one. */
26      public static final Volume ONE = ofSi(1.0);
27  
28      /** Constant with value NaN. */
29      @SuppressWarnings("checkstyle:constantname")
30      public static final Volume NaN = ofSi(Double.NaN);
31  
32      /** Constant with value POSITIVE_INFINITY. */
33      public static final Volume POSITIVE_INFINITY = ofSi(Double.POSITIVE_INFINITY);
34  
35      /** Constant with value NEGATIVE_INFINITY. */
36      public static final Volume NEGATIVE_INFINITY = ofSi(Double.NEGATIVE_INFINITY);
37  
38      /** Constant with value MAX_VALUE. */
39      public static final Volume POS_MAXVALUE = ofSi(Double.MAX_VALUE);
40  
41      /** Constant with value -MAX_VALUE. */
42      public static final Volume NEG_MAXVALUE = ofSi(-Double.MAX_VALUE);
43  
44      /** */
45      private static final long serialVersionUID = 600L;
46  
47      /**
48       * Instantiate a Volume quantity with a unit.
49       * @param valueInUnit the value, expressed in the unit
50       * @param unit the unit in which the value is expressed
51       */
52      public Volume(final double valueInUnit, final Volume.Unit unit)
53      {
54          super(valueInUnit, unit);
55      }
56  
57      /**
58       * Return a Volume instance based on an SI value.
59       * @param si the si value
60       * @return the Volume instance based on an SI value
61       */
62      public static Volume ofSi(final double si)
63      {
64          return new Volume(si, Volume.Unit.SI);
65      }
66  
67      @Override
68      public Volume instantiateSi(final double si)
69      {
70          return ofSi(si);
71      }
72  
73      @Override
74      public SIUnit siUnit()
75      {
76          return Volume.Unit.SI_UNIT;
77      }
78  
79      /**
80       * Returns a Volume representation of a textual representation of a value with a unit. The String representation that can be
81       * parsed is the double value in the unit, followed by a localized or English abbreviation of the unit. Spaces are allowed,
82       * but not required, between the value and the unit.
83       * @param text the textual representation to parse into a Volume
84       * @return the Scalar representation of the value in its unit
85       * @throws IllegalArgumentException when the text cannot be parsed
86       * @throws NullPointerException when the text argument is null
87       */
88      public static Volume valueOf(final String text)
89      {
90          return Quantity.valueOf(text, ZERO);
91      }
92  
93      /**
94       * Returns a Volume based on a value and the textual representation of the unit, which can be localized.
95       * @param valueInUnit the value, expressed in the unit as given by unitString
96       * @param unitString the textual representation of the unit
97       * @return the Scalar representation of the value in its unit
98       * @throws IllegalArgumentException when the unit cannot be parsed or is incorrect
99       * @throws NullPointerException when the unitString argument is null
100      */
101     public static Volume of(final double valueInUnit, final String unitString)
102     {
103         return Quantity.of(valueInUnit, unitString, ZERO);
104     }
105 
106     @Override
107     public Volume.Unit getDisplayUnit()
108     {
109         return (Volume.Unit) super.getDisplayUnit();
110     }
111 
112     /**
113      * Calculate the division of Volume and Volume, which results in a Dimensionless scalar.
114      * @param v scalar
115      * @return scalar as a division of Volume and Volume
116      */
117     public final Dimensionless divide(final Volume v)
118     {
119         return new Dimensionless(this.si() / v.si(), Unitless.BASE);
120     }
121 
122     /**
123      * Calculate the multiplication of Volume and Density, which results in a Mass scalar.
124      * @param v scalar
125      * @return scalar as a multiplication of Volume and Density
126      */
127     public final Mass multiply(final Density v)
128     {
129         return new Mass(this.si() * v.si(), Mass.Unit.SI);
130     }
131 
132     /**
133      * Calculate the multiplication of Volume and Pressure, which results in a Energy scalar.
134      * @param v scalar
135      * @return scalar as a multiplication of Volume and Pressure
136      */
137     public final Energy multiply(final Pressure v)
138     {
139         return new Energy(this.si() * v.si(), Energy.Unit.SI);
140     }
141 
142     /**
143      * Calculate the division of Volume and Length, which results in a Area scalar.
144      * @param v scalar
145      * @return scalar as a division of Volume and Length
146      */
147     public final Area divide(final Length v)
148     {
149         return new Area(this.si() / v.si(), Area.Unit.SI);
150     }
151 
152     /**
153      * Calculate the division of Volume and Area, which results in a Length scalar.
154      * @param v scalar
155      * @return scalar as a division of Volume and Area
156      */
157     public final Length divide(final Area v)
158     {
159         return new Length(this.si() / v.si(), Length.Unit.SI);
160     }
161 
162     /**
163      * Calculate the multiplication of Volume and LinearObjectDensity, which results in a Area scalar.
164      * @param v scalar
165      * @return scalar as a multiplication of Volume and LinearObjectDensity
166      */
167     public final Area multiply(final LinearObjectDensity v)
168     {
169         return new Area(this.si() * v.si(), Area.Unit.SI);
170     }
171 
172     /**
173      * Calculate the division of Volume and Duration, which results in a FlowVolume scalar.
174      * @param v scalar
175      * @return scalar as a division of Volume and Duration
176      */
177     public final FlowVolume divide(final Duration v)
178     {
179         return new FlowVolume(this.si() / v.si(), FlowVolume.Unit.SI);
180     }
181 
182     /**
183      * Calculate the division of Volume and FlowVolume, which results in a Duration scalar.
184      * @param v scalar
185      * @return scalar as a division of Volume and FlowVolume
186      */
187     public final Duration divide(final FlowVolume v)
188     {
189         return new Duration(this.si() / v.si(), Duration.Unit.SI);
190     }
191 
192     @Override
193     public VolumetricObjectDensity reciprocal()
194     {
195         return VolumetricObjectDensity.ofSi(1.0 / this.si());
196     }
197 
198     /******************************************************************************************************/
199     /********************************************** UNIT CLASS ********************************************/
200     /******************************************************************************************************/
201 
202     /**
203      * Volume.Unit encodes the volume unit (length x length x length).
204      * <p>
205      * Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved.
206      * See for project information <a href="https://djunits.org" target="_blank">https://djunits.org</a>. The DJUNITS project is
207      * distributed under a <a href="https://djunits.org/docs/license.html" target="_blank">three-clause BSD-style license</a>.
208      * @author Alexander Verbraeck
209      */
210     @SuppressWarnings("checkstyle:constantname")
211     public static class Unit extends AbstractUnit<Volume.Unit, Volume>
212     {
213         /** Constant for the cubic inch. */
214         public static final double CONST_CUBIC_INCH = cubed(Length.Unit.CONST_IN);
215 
216         /** Constant for the cubic foot. */
217         public static final double CONST_CUBIC_FOOT = cubed(Length.Unit.CONST_FT);
218 
219         /** Constant for the cubic yard. */
220         public static final double CONST_CUBIC_YARD = cubed(Length.Unit.CONST_YD);
221 
222         /** Constant for the imperial gallon. */
223         public static final double CONST_GALLON_IMP = 4.54609E-3;
224 
225         /** Constant for imperial fluid ounce. */
226         public static final double CONST_OZ_IMP = CONST_GALLON_IMP / 160.0;
227 
228         /** Constant for US gallon. */
229         public static final double CONST_GALLON_US = 231.0 * CONST_CUBIC_INCH;
230 
231         /** Constant for US fluid ounce. */
232         public static final double CONST_OZ_US = CONST_GALLON_US / 128.0;
233 
234         /** The dimensions of Volume: m3. */
235         public static final SIUnit SI_UNIT = SIUnit.of("m3");
236 
237         /** Cubic meter. */
238         public static final Volume.Unit m3 = new Volume.Unit("m3", "cubic meter", 1.0, UnitSystem.SI_BASE);
239 
240         /** The SI or BASE unit. */
241         public static final Volume.Unit SI = m3;
242 
243         /** mm^3. */
244         public static final Volume.Unit mm3 = m3.deriveUnit("mm3", "cubic millimeter", 1.0E-9, UnitSystem.SI_BASE);
245 
246         /** cm^3. */
247         public static final Volume.Unit cm3 = m3.deriveUnit("cm3", "cubic centimeter", 1.0E-6, UnitSystem.SI_BASE);
248 
249         /** dm^3. */
250         public static final Volume.Unit dm3 = m3.deriveUnit("dm3", "cubic decimeter", 1.0E-3, UnitSystem.SI_BASE);
251 
252         /** dam^3. */
253         public static final Volume.Unit dam3 = m3.deriveUnit("dam3", "cubic decameter", 1.0E3, UnitSystem.SI_BASE);
254 
255         /** hm^3. */
256         public static final Volume.Unit hm3 = m3.deriveUnit("hm3", "cubic hectometer", 1.0E6, UnitSystem.SI_BASE);
257 
258         /** km^3. */
259         public static final Volume.Unit km3 = m3.deriveUnit("km3", "cubic kilometer", 1.0E9, UnitSystem.SI_BASE);
260 
261         /** in^3. */
262         public static final Volume.Unit in3 = m3.deriveUnit("in3", "cubic inch", CONST_CUBIC_INCH, UnitSystem.IMPERIAL);
263 
264         /** ft^3. */
265         public static final Volume.Unit ft3 = m3.deriveUnit("ft3", "cubic foot", CONST_CUBIC_FOOT, UnitSystem.IMPERIAL);
266 
267         /** yd^3. */
268         public static final Volume.Unit yd3 = m3.deriveUnit("yd3", "cubic yard", CONST_CUBIC_YARD, UnitSystem.IMPERIAL);
269 
270         /** mile^3. */
271         public static final Volume.Unit mi3 =
272                 m3.deriveUnit("mi3", "cubic mile", cubed(Length.Unit.CONST_MI), UnitSystem.IMPERIAL);
273 
274         /** Nautical mile^3. */
275         public static final Volume.Unit NM3 =
276                 m3.deriveUnit("NM3", "cubic Nautical Mile", cubed(Length.Unit.CONST_NM), UnitSystem.OTHER);
277 
278         /** liter. */
279         public static final Volume.Unit L = dm3.deriveUnit("L", "liter", 1.0, UnitSystem.SI_ACCEPTED);
280 
281         /** gallon (US), fluids. */
282         public static final Volume.Unit gal_US =
283                 m3.deriveUnit("gal(US)", "gallon (US)", CONST_GALLON_US, UnitSystem.US_CUSTOMARY);
284 
285         /** gallon (imperial). */
286         public static final Volume.Unit gal_imp =
287                 m3.deriveUnit("gal(imp)", "gallon (imp)", CONST_GALLON_IMP, UnitSystem.IMPERIAL);
288 
289         /** quart (fluid US) = 1/4 US gallon. */
290         public static final Volume.Unit qt_US = gal_US.deriveUnit("qt(US)", "quart (US)", 0.25, UnitSystem.US_CUSTOMARY);
291 
292         /** quart (imperial) = 1/4 imp gallon. */
293         public static final Volume.Unit qt_imp = gal_imp.deriveUnit("qt(imp)", "quart (imp)", 0.25, UnitSystem.IMPERIAL);
294 
295         /** pint (fluid US) = 1/2 US quart. */
296         public static final Volume.Unit pt_US = qt_US.deriveUnit("pt(US)", "pint (US)", 0.5, UnitSystem.US_CUSTOMARY);
297 
298         /** pint (imperial) = 1/2 imp quart. */
299         public static final Volume.Unit pt_imp = qt_imp.deriveUnit("pt(imp)", "pint (imp)", 0.5, UnitSystem.IMPERIAL);
300 
301         /** ounce (fluid US) = 1/16 US pint. */
302         public static final Volume.Unit fl_oz_US =
303                 m3.deriveUnit("fl.oz(US)", "fluid ounce (US)", CONST_OZ_US, UnitSystem.US_CUSTOMARY);
304 
305         /** ounce (fluid imperial) = 1/20 imp pint. */
306         public static final Volume.Unit fl_oz_imp =
307                 m3.deriveUnit("fl.oz(imp)", "fluid ounce (imp)", CONST_OZ_IMP, UnitSystem.IMPERIAL);
308 
309         /** Cubic lightyear. */
310         public static final Volume.Unit ly3 =
311                 m3.deriveUnit("ly3", "cubic lightyear", cubed(Length.Unit.CONST_LY), UnitSystem.OTHER);
312 
313         /** Cubic Parsec. */
314         public static final Volume.Unit pc3 =
315                 m3.deriveUnit("pc3", "cubic Parsec", cubed(Length.Unit.CONST_PC), UnitSystem.OTHER);
316 
317         /**
318          * Create a new Volume unit.
319          * @param id the id or main abbreviation of the unit
320          * @param name the full name of the unit
321          * @param scaleFactorToBaseUnit the scale factor of the unit to convert it TO the base (SI) unit
322          * @param unitSystem the unit system such as SI or IMPERIAL
323          */
324         public Unit(final String id, final String name, final double scaleFactorToBaseUnit, final UnitSystem unitSystem)
325         {
326             super(id, name, new LinearScale(scaleFactorToBaseUnit), unitSystem);
327         }
328 
329         /**
330          * Return a derived unit for this unit, with textual abbreviation(s) and a display abbreviation.
331          * @param textualAbbreviation the textual abbreviation of the unit, which doubles as the id
332          * @param displayAbbreviation the display abbreviation of the unit
333          * @param name the full name of the unit
334          * @param scale the scale to use to convert between this unit and the standard (e.g., SI, BASE) unit
335          * @param unitSystem unit system, e.g. SI or Imperial
336          */
337         public Unit(final String textualAbbreviation, final String displayAbbreviation, final String name, final Scale scale,
338                 final UnitSystem unitSystem)
339         {
340             super(textualAbbreviation, displayAbbreviation, name, scale, unitSystem);
341         }
342 
343         @Override
344         public SIUnit siUnit()
345         {
346             return SI_UNIT;
347         }
348 
349         @Override
350         public Unit getBaseUnit()
351         {
352             return SI;
353         }
354 
355         @Override
356         public Volume ofSi(final double si)
357         {
358             return Volume.ofSi(si);
359         }
360 
361         @Override
362         public Unit deriveUnit(final String textualAbbreviation, final String displayAbbreviation, final String name,
363                 final double scaleFactor, final UnitSystem unitSystem)
364         {
365             if (getScale() instanceof LinearScale ls)
366             {
367                 return new Volume.Unit(textualAbbreviation, displayAbbreviation, name,
368                         new LinearScale(ls.getScaleFactorToBaseUnit() * scaleFactor), unitSystem);
369             }
370             throw new UnitRuntimeException("Only possible to derive a unit from a unit with a linear scale");
371         }
372 
373         /**
374          * Return the cubed value of the argument.
375          * @param x the value to cube
376          * @return x^3
377          */
378         private static double cubed(final double x)
379         {
380             return x * x * x;
381         }
382     }
383 }