commit a868657b7786bf447bf56c11ea31320cbc91874f
parent c7bf1d98d83f761c22ccb8d67c2c291e94453fd7
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 14 Oct 2025 15:28:19 +0200
stardis: add plugin reference documentation
Only the functions that create library data and those that create
physical properties are documented.
These are the only two functions whose behavior depends on the user via
the arguments they define after the PROG_PARAMS directive via the
Stardis interface for programmable properties, which is the only
interface through which the plugin's functions are supposed to be
called.
Diffstat:
2 files changed, 332 insertions(+), 0 deletions(-)
diff --git a/Makefile b/Makefile
@@ -156,6 +156,7 @@ install: library util pkg $(PLUGIN)
install 644 "$(DESTDIR)$(INCPREFIX)/star" src/smeteo.h; \
install 755 "$(DESTDIR)$(BINPREFIX)/" smeteo; \
install 644 "$(DESTDIR)$(MANPREFIX)/man1" doc/smeteo.1; \
+ install 644 "$(DESTDIR)$(MANPREFIX)/man3" doc/libstardis_smeteo.3; \
install 644 "$(DESTDIR)$(MANPREFIX)/man5" doc/smeteo.5; \
install 644 "$(DESTDIR)$(PREFIX)/share/doc/star-meteo" COPYING README.md; \
if [ $(PLUGIN) = "stardis" ]; then \
@@ -169,12 +170,14 @@ uninstall:
rm -f "$(DESTDIR)$(INCPREFIX)/star/smeteo.h"
rm -f "$(DESTDIR)$(BINPREFIX)/smeteo"
rm -f "$(DESTDIR)$(MANPREFIX)/man1/smeteo.1"
+ rm -f "$(DESTDIR)$(MANPREFIX)/man3/libstardis_smeteo.3"
rm -f "$(DESTDIR)$(MANPREFIX)/man5/smeteo.5"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/star-meteo/COPYING"
rm -f "$(DESTDIR)$(PREFIX)/share/doc/star-meteo/README.md"
lint:
mandoc -T lint -Wbase doc/smeteo.1 || [ $$? -le 1 ]
+ mandoc -T lint -Wbase doc/libstardis_smeteo.3 || [ $$? -le 1 ]
mandoc -T lint -Wbase doc/smeteo.5 || [ $$? -le 1 ]
clean: clean_test
diff --git a/doc/libstardis_smeteo.3 b/doc/libstardis_smeteo.3
@@ -0,0 +1,329 @@
+.\" Copyright (C) 2025 |Méso|Star> (contact@meso-star.com)
+.\"
+.\" This program is free software: you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation, either version 3 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU Lesser General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU Lesser General Public License
+.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
+.Dd October 14, 2025
+.Dt LIBSTARDIS_SMETEO 3
+.Os
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh NAME
+.Nm libstardis_smeteo
+.Nd
+.Xr stardis 1
+plugin for handling meteorological data
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SYNOPSIS
+.In stardis_smeteo.h
+.Ft void*
+.Fo stardis_create_library_data
+.Fa "const struct stardis_program_context* ctx"
+.Fa "size_t argc"
+.Fa "char* argv[]"
+.Fc
+.Ft void*
+.Fo stardis_create_data
+.Fa "const struct stardis_description_create_context* ctx"
+.Fa "void* lib_data"
+.Fa "size_t argc"
+.Fa "char* argv"
+.Fc
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DESCRIPTION
+These functions implement the interface for creating programmable data
+for
+.Xr stardis 1 .
+They are part of a stardis plugin that loads meteorological data as
+described by the
+.Xr smeteo 5
+file format.
+This data is used by the plugin to define connection conditions and
+boundary conditions based on meteorological data, i.e.
+which varies depending on time.
+.Pp
+.Nm
+is intended to be dynamically loaded by
+.Xr stardis 1
+as programmable boundary or connection conditions.
+The functions described in this documentation are therefore not intended
+to be called directly by a programmer, but by the
+.Xr stardis 1
+programmable interface, which internally manages input arguments such as
+.Fa ctx
+and
+.Fa lib_data .
+Only the
+.Fa argc
+and
+.Fa argv
+parameters are meaningful to the
+.Xr stardis 1
+user.
+They reflect the options that it can define via this programmable
+interface
+.Po
+see the
+.Xr stardis-input 5
+file format
+.Pc .
+This documentation therefore lists the values of these arguments that
+the user can enter when declaring programmable properties via this
+plugin.
+.\""""""""""""""""""""""""""""""""""""""
+.Ss Library data
+The
+.Fn stardis_create_library_data
+function is called once when the plugin is loaded by
+.Xr stardis 1
+.Po
+see the
+.Ql PROGRAM
+keyword in
+.Xr stardis-input 5
+.Pc .
+.Pp
+This function creates the data shared by all physical properties that
+will rely on this instance of the library.
+Its behavior depends on its
+.Fa argc
+and
+.Fa argv
+variables.
+Their values are those that would be taken by the
+.Fa argc
+and
+.Fa argv
+arguments of the
+.Fn main
+function of a C program whose synopsis would be:
+.Pp
+.Nm stardis-smeteo
+.Op Fl a Ar sun_algo
+.Ar file
+.Pp
+except for the name of the program, i.e.
+.Nm stardis-smeteo ,
+which is purely
+fictitious here, replaced by the name defined in the
+.Ql PROGRAM
+directive
+of the
+.Xr stardis-input 5
+file responsible for instantiating the plugin for
+.Xr stardis 1 .
+.Pp
+The
+.Ar file
+argument is the path to a
+.Xr smeteo 5
+file that defines the meteorological data to be loaded.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl a Ar sun_algo
+Defines the algorithm to use to calculate the position of the sun when
+its contribution is modeled by a spherical external source
+.Po
+see the
+.Ql SPHERICAL_SOURCE[_PROG]
+directive in the
+.Xr stardis-input 5
+file format
+.Pc .
+.Pp
+The solar position algorithms are as follows:
+.Bl -tag -width Ds
+.It Cm meeus
+The algorithm described in the Jean Meeus' book,
+.Dq Astronomical Algorithm .
+This is the default algorithm if no other is explicitly defined.
+.It Cm psa
+The algorithm developed by the
+.Dq Palaforma Solar de Almería .
+.El
+.El
+.\""""""""""""""""""""""""""""""""""""""
+.Ss Physical properties
+The
+.Fn stardis_create_data
+function is called each time a
+stardis property is declared as dependent on an instance of the
+.Nm
+plugin, i.e., as a programmable property using the
+.Nm
+library on the meteorological data loaded when the library data was
+created
+.Pq see the Sx Library data No sub-section .
+.Pp
+This function creates the corresponding physical property from its
+.Fa argc
+and
+.Fa argv
+variables.
+Their values are those that would be taken by the
+.Fa argc
+and
+.Fa argv
+arguments of the
+.Fn main
+function of a C program whose synopsis would be:
+.Pp
+.Nm stardis-smeteo-phyprop
+.Op Fl fh
+.Op Fl t Ar temperature
+.Pp
+except for the name of the program, i.e.
+.Nm stardis-smeteo-phyprop ,
+which is purely fictitious here, replaced by the name of the
+programmable physical property defined in the
+.Xr stardis-input 5
+file.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl f
+When used to declare a boundary condition or a connection condition,
+solar flux is taken into account as an imposed flux at the interface.
+.It Fl h
+When used to declare a boundary condition or a connection condition, the
+interface convection coefficient is retrieved from the meteorological
+data loaded by the library instance
+.Pq see Xr smeteo 5 .
+If this option is not defined, the interface convection coefficient is
+assumed to be zero.
+.It Fl t Ar temperature
+When used to declare a Dirichlet boundary condition, set the interface
+temperature to
+.Ar temperature
+.Pq in Kelvin .
+If this option is not defined, the Dirichlet boundary condition uses the
+surface temperature defined in the meteorological data loaded by the
+library instance
+.Pq see Xr smeteo 5 .
+.El
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXIT STATUS
+Upon successful, a pointer to the allocated data is returned.
+Otherwise, a null pointer is returned.
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh EXAMPLES
+The functions documented here are not intended to be called directly,
+but via the
+.Xr stardis 1
+programmable properties interface.
+The following examples therefore illustrate
+.Xr stardis-input 5
+files based on the
+.Nm
+plugin to define programmable properties that ultimately call these
+functions.
+.Pp
+The following
+.Xr stardis-input 5
+file, defines a slab whose lower surface has a fixed temperature of
+284K.
+A Robin+Neumann boundary condition is imposed on its upper surface.
+Its convection coefficient, fluid temperature (i.e., atmosphere), and
+imposed flux are retrieved from meteorological data. the latter
+representing the solar flux imposed on the interface.
+The other surfaces are adiabatic to simulate an infinite slab:
+.Bd -literal -offset Ds
+# Configure the plugin to use the meteorological data stored
+# in the smeteo.txt file.
+PROGRAM Meteo libstardis_smeteo.so smeteo.txt
+
+# Define the ground
+SOLID ground 1 1500 1500 0.02 281.85 UNKNOWN 0 FRONT ground.stl
+
+# Use the "Meteo" plugin to define convective exchange between
+# the surface and the atmosphere and take into account solar
+# contribution by imposing a flux
+HF_BOUNDARY_FOR_SOLID_PROG atm Meteo ground_Z.stl PROG_PARAMS -hf
+
+# Fix the underground temperature to 284 K
+T_BOUNDARY_FOR_SOLID underground 284.0 ground_z.stl
+
+# Make other interfaces adiabatic
+H_BOUNDARY_FOR_SOLID adiabatic 0 0 0 0 0 ground_xXyY.stl
+.Ed
+.Pp
+Below, the
+.Xr stardis-input 5
+file defines the ground as a slab-shaped geometry immersed in a fluid
+.Pq i.e., the atmosphere
+whose temperature is retrieved from meteorological data.
+A convective exchange is added between the atmosphere and the ground
+using the convection coefficient described in the meteorological data.
+The underground temperature is fixed to 284 K.
+The contribution of the sun is modeled by an external spherical source
+with a radius of 6.987e8 m, whose position is calculated by
+.Nm
+based on the location of the meteorological data and the time, using the
+PSA algorithm.
+Its direct and diffuse contribution is retrieved from meteorological
+data as is the ambiant radiative temperature.
+The other surfaces are adiabatic:
+.Bd -literal -offset Ds
+# Configure the plugin to use the meteorological data stored
+# in the smeteo.txt file and to use the algorithm developed
+# by the "Palaforma Solar de Almería" to calculate the
+# position of the sun
+PROGRAM Meteo libstardis_smeteo.so smeteo.txt PROG_PARAMS -a psa
+
+# Define the ground
+SOLID ground 1 1500 1500 0.02 281.85 UNKNOWN 0 FRONT ground.stl
+
+# Define the atmosphere as a fluid at a fixed temperature
+# retrieved from the "Meteo" plugin
+FLUID_PROG atmosphere Meteo BACK ground.stl'
+
+# Use the "Meteo" plugin to add a convective exchange
+# between the ground surface and the atmosphere
+SOLID_FLUID_CONNECTION_PROG hdT Meteo ground_Z.stl PROG_PARAMS -h
+
+# Fix the underground temperature to 284 K
+SOLID_FLUID_CONNECTION_PROG ut Meteo ground_z.stl PROG_PARAMS -t284
+
+# Make other interfaces adiabatic
+SOLID_FLUID_CONNECTION adiabatic 300 0 0 0 ground_xXyY.stl
+
+# Use the "Meteo" plugin to calculate the position and
+# contribution of the sun declared as an external spherical
+# source
+SPHERICAL_SOURCE_PROG 6.987e8 Meteo
+
+# Retrieve the radiative temperature from the meteorological data
+# loaded by the "Meteo" plugin
+TRAD_PROG Meteo
+.Ed
+.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh SEE ALSO
+.Xr stardis 1 ,
+.Xr smeteo 5 ,
+.Xr stardis-input 5
+.Rs
+.%A Jean Meeus
+.%B Astronomical Algorithms
+.%D 1991
+.Re
+.Rs
+.%A Manuel Blanco-Muriel
+.%A Diego C. Alarcón-Padilla
+.%A Teodoro López-Moratalla
+.%A Martín Lara-Coira
+.%T Computing the solar vector
+.%J Solar Energy
+.%V 70
+.%N 5
+.%D 2001
+.%P 431-441
+.Re
