| 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 |