Debian Codegraph @

src/atlas/field/Field.h

raw
1 /*
2 * (C) Copyright 2013 ECMWF.
3 *
4 * This software is licensed under the terms of the Apache Licence Version 2.0
5 * which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
6 * In applying this licence, ECMWF does not waive the privileges and immunities
7 * granted to it by virtue of its status as an intergovernmental organisation
8 * nor does it submit to any jurisdiction.
9 */
10
11 /// @author Willem Deconinck
12 /// @date Sep 2014
13
14 #pragma once
15
16 #include <iosfwd>
17 #include <string>
18
19 #include "eckit/config/Parametrisation.h"
20
21 #include "atlas/array/ArrayShape.h"
22 #include "atlas/array/DataType.h"
23 #include "atlas/array_fwd.h"
24 #include "atlas/library/config.h"
25 #include "atlas/util/Config.h"
26 #include "atlas/util/ObjectHandle.h"
27 #include "atlas/field/Halo.h"
28
29 namespace eckit {
30 class Parametrisation;
31 }
32 namespace atlas {
33 namespace field {
34 class FieldImpl;
35 }
36 } // namespace atlas
37 namespace atlas {
38 namespace util {
39 class Config;
40 class Metadata;
41 }
42 } // namespace atlas
43 namespace atlas {
44 class FunctionSpace;
45 }
46
47 namespace atlas {
48
49 /// @brief A Field contains an Array, Metadata, and a reference to a FunctionSpace
50 ///
51 /// The Field is a key component of Atlas. It contains an \ref array::Array object and a \ref util::Metadata object.
52 /// Furthermore it contains a link to a FunctionSpace object.
53 ///
54 /// A Field should typically be created via the FunctionSpace::createField() method, which ensures
55 /// that the Field is completely setup.
56 ///
57 /// A field can be implicitly converted to an Array reference, so that it can be passed to routines that
58 /// expect an Array. This is especially useful to create an ArrayView:
59 ///
60 /// @code{.cpp}
61 /// Field field = functionspace.createField<double>( ... );
62 /// auto view = array::make_view<double,2>( field );
63 /// @endcode
64 class Field : DOXYGEN_HIDE(public util::ObjectHandle<field::FieldImpl>) {
65 public:
66 using Handle::Handle;
67 Field() = default;
68
69 /// @brief Create field from parametrisation
70 Field(const eckit::Parametrisation&);
71
72 /// @brief Create field with given name, Datatype and ArrayShape
73 Field(const std::string& name, array::DataType, const array::ArrayShape& = array::ArrayShape());
74
75 /// @brief Create field with given name, Datatype and ArraySpec
76 Field(const std::string& name, array::DataType, array::ArraySpec&&);
77
78 /// @brief Create field with given name, and take ownership of given Array
79 Field(const std::string& name, array::Array*);
80
81 /// @brief Create field by wrapping existing data, Datatype of template and
82 /// ArraySpec
83 template <typename DATATYPE>
84 Field(const std::string& name, DATATYPE* data, const array::ArraySpec&);
85
86 /// @brief Create field by wrapping existing data, Datatype of template and
87 /// ArrayShape
88 template <typename DATATYPE>
89 Field(const std::string& name, DATATYPE* data, const array::ArrayShape&);
90
91 /// @brief Deep copy
92 Field clone(const eckit::Parametrisation& = util::Config()) const;
93
94 // -- Conversion
95
96 /// @brief Implicit conversion to Array
97 operator const array::Array&() const;
98 operator array::Array&();
99
100 /// @brief Access contained Array
101 const array::Array& array() const;
102 array::Array& array();
103
104 bool valid() const { return get() != nullptr; }
105
106 // -- Accessors
107
108 /// @brief Access to raw data
109 void* storage();
110
111 /// @brief Internal data type of field
112 array::DataType datatype() const;
113
114 /// @brief Name associated to this field
115 const std::string& name() const;
116
117 /// @brief Rename this field
118 void rename(const std::string& name);
119
120 /// @brief Access to metadata associated to this field
121 const util::Metadata& metadata() const;
122 util::Metadata& metadata();
123
124 /// @brief Resize field to given shape
125 void resize(const array::ArrayShape& shape);
126
127 void insert(idx_t idx1, idx_t size1);
128
129 /// @brief Shape of this field in Fortran style (reverse order of C style)
130 const std::vector<int>& shapef() const;
131
132 /// @brief Strides of this field in Fortran style (reverse order of C style)
133 const std::vector<int>& stridesf() const;
134
135 /// @brief Shape of this field (reverse order of Fortran style)
136 const array::ArrayShape& shape() const;
137
138 /// @brief Strides of this field
139 const array::ArrayStrides& strides() const;
140
141 /// @brief Shape of this field associated to index 'i'
142 idx_t shape(idx_t i) const;
143
144 /// @brief Stride of this field associated to index 'i'
145 idx_t stride(idx_t i) const;
146
147 /// @brief Number of values stored in this field
148 size_t size() const;
149
150 /// @brief Rank of field
151 idx_t rank() const;
152
153 /// @brief Number of bytes occupied by the values of this field
154 size_t bytes() const;
155
156 bool contiguous() const;
157
158 /// @brief Output information of field
159 friend std::ostream& operator<<(std::ostream& os, const Field& v);
160
161 /// @brief Output information of field plus raw data
162 void dump(std::ostream& os) const;
163
164 /// Metadata that is more intrinsic to the Field, and queried often
165 void set_levels(idx_t n);
166 idx_t levels() const;
167
168 /// Metadata that is more intrinsic to the Field, and queried often
169 void set_variables(idx_t n);
170 idx_t variables() const;
171
172 void set_horizontal_dimension(const std::vector<idx_t>&);
173 std::vector<idx_t> horizontal_dimension() const;
174
175 void set_functionspace(const FunctionSpace& functionspace);
176 const FunctionSpace& functionspace() const;
177
178 /// @brief Return the memory footprint of the Field
179 size_t footprint() const;
180
181 bool dirty() const;
182
183 void set_dirty(bool = true) const;
184
185 field::Halo& halo() const;
186
187 void haloExchange(bool on_device = false) const;
188 void adjointHaloExchange(bool on_device = false) const;
189
190 // -- Methods related to host-device synchronisation
191 void updateHost() const;
192 void updateDevice() const;
193 void syncHost() const;
194 void syncDevice() const;
195 void syncHostDevice() const;
196 bool hostNeedsUpdate() const;
197 bool deviceNeedsUpdate() const;
198 void setHostNeedsUpdate(bool) const;
199 void setDeviceNeedsUpdate(bool) const;
200 void setHostNeedsUpdate() const;
201 void setDeviceNeedsUpdate() const;
202 bool deviceAllocated() const;
203 void allocateDevice();
204 void deallocateDevice();
205 void reactivateDeviceWriteViews() const;
206 void reactivateHostWriteViews() const;
207 };
208
209 extern template Field::Field(const std::string&, float*, const array::ArraySpec&);
210 extern template Field::Field(const std::string&, float*, const array::ArrayShape&);
211 extern template Field::Field(const std::string&, double*, const array::ArraySpec&);
212 extern template Field::Field(const std::string&, double*, const array::ArrayShape&);
213 extern template Field::Field(const std::string&, long*, const array::ArraySpec&);
214 extern template Field::Field(const std::string&, long*, const array::ArrayShape&);
215 extern template Field::Field(const std::string&, int*, const array::ArraySpec&);
216 extern template Field::Field(const std::string&, int*, const array::ArrayShape&);
217
218 //------------------------------------------------------------------------------------------------------
219
220 } // namespace atlas