Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 59d7b1d

Browse files
committedOct 23, 2023
restruct documentation
1 parent d14cd68 commit 59d7b1d

21 files changed

+41
-97
lines changed
 

‎+gams/+transfer/Alias.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,6 @@
4747
%
4848
% See also: gams.transfer.Set, gams.transfer.Container
4949

50-
%> @ingroup symbol
5150
%> @brief GAMS Alias
5251
%>
5352
%> This class represents a GAMS Alias, which is a link to another GAMS \ref

‎+gams/+transfer/Container.m

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,13 +67,12 @@
6767
% gams.transfer.Variable, gams.transfer.Equation
6868
%
6969

70-
%> @ingroup container
7170
%> @brief GAMS Transfer Container stores (multiple) symbols
7271
%>
7372
%> A GAMS GDX file is a collection of GAMS symbols (e.g. variables or
7473
%> parameters), each holding multiple symbol records. In GAMS Transfer the
7574
%> Container is the main object that holds different symbols and allows to read
76-
%> and write those to GDX. See \ref gams_transfer_matlab_container for more
75+
%> and write those to GDX. See \ref GAMS_TRANSFER_MATLAB_CONTAINER for more
7776
%> information.
7877
%>
7978
%> **Indexed Mode:**

‎+gams/+transfer/DomainViolation.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,6 @@
4747
% See also: gams.transfer.Set, gams.transfer.Symbol
4848
%
4949

50-
%> @ingroup records
5150
%> @brief Domain Violation
5251
%>
5352
%> Domain violations occur when a symbol uses other \ref gams::transfer::Set

‎+gams/+transfer/Equation.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,6 @@
6565
% See also: gams.transfer.Container, gams.transfer.EquationType, gams.transfer.Set
6666
%
6767

68-
%> @ingroup symbol
6968
%> @brief GAMS Equation
7069
%>
7170
%> **Example:**

‎+gams/+transfer/EquationType.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,6 @@
3737
% See also: gams.transfer.Equation
3838
%
3939

40-
%> @ingroup symbol
4140
%> @brief GAMS Equation Types
4241
%>
4342
%> This class holds the possible GAMS equation types similar to an enumeration

‎+gams/+transfer/Parameter.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,6 @@
6363
% See also: gams.transfer.Container, gams.transfer.Set
6464
%
6565

66-
%> @ingroup symbol
6766
%> @brief GAMS Parameter
6867
%>
6968
%> **Example:**

‎+gams/+transfer/RecordsFormat.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,6 @@
3535
% compatibility (e.g. for Octave).
3636
%
3737

38-
%> @ingroup records
3938
%> @brief GAMS Transfer Records Formats
4039
%>
4140
%> This class holds the possible GAMS Transfer formats of records similar to

‎+gams/+transfer/Set.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,6 @@
6565
% See also: gams.transfer.Container
6666
%
6767

68-
%> @ingroup symbol
6968
%> @brief GAMS Set
7069
%>
7170
%> **Example:**

‎+gams/+transfer/SpecialValues.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,6 @@
3838
% (NaN, Inf and -Inf, respectively), NA and EPS do not. The latter two are
3939
% therefore mapped to a special NaN and -0, respectively.
4040

41-
%> @ingroup records
4241
%> @brief GAMS Special Values
4342
%>
4443
%> GAMS GDX offers five special values: \ref gams::transfer::SpecialValues::NA

‎+gams/+transfer/Symbol.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,6 @@
3636
% gams.transfer.Variable, gams.transfer.Equation
3737
%
3838

39-
%> @ingroup symbol
4039
%> @brief GAMS Symbol (Set, Alias, Parameter, Variable or Equation)
4140
%>
4241
%> Use subclasses to create a GAMS Symbol, see subclass help.

‎+gams/+transfer/SymbolType.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,6 @@
3535
% compatibility (e.g. for Octave).
3636
%
3737

38-
%> @ingroup symbol
3938
%> @brief GAMS Transfer Symbol Types
4039
%>
4140
%> This class holds the possible GAMS Transfer symbol types similar to an

‎+gams/+transfer/UniverseAlias.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,6 @@
4444
%
4545
% See also: gams.transfer.Set, gams.transfer.Container, gams.transfer.Alias
4646

47-
%> @ingroup symbol
4847
%> @brief GAMS Alias to Universe
4948
%>
5049
%> This class represents a GAMS Alias to Universe.

‎+gams/+transfer/Variable.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,6 @@
6666
% See also: gams.transfer.Container, gams.transfer.VariableType, gams.transfer.Set
6767
%
6868

69-
%> @ingroup symbol
7069
%> @brief GAMS Variable
7170
%>
7271
%> **Example:**

‎+gams/+transfer/VariableType.m

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,6 @@
3737
% See also: gams.transfer.Variable
3838
%
3939

40-
%> @ingroup symbol
4140
%> @brief GAMS Variable Types
4241
%>
4342
%> This class holds the possible GAMS variable types similar to an enumeration

‎doc/DoxygenLayout.xml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<!-- Generated by doxygen 1.8.17 -->
33
<!-- Navigation index tabs for HTML output -->
44
<navindex>
5-
<tab type="mainpage" visible="yes" title=""/>
5+
<tab type="mainpage" visible="no" title=""/>
66
<tab type="pages" visible="yes" title="" intro=""/>
77
<tab type="modules" visible="yes" title="Manual" intro=
88
"GAMS Transfer Matlab consists of containers, symbols and symbol records.
@@ -18,12 +18,12 @@
1818
<tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
1919
<tab type="interfacehierarchy" visible="yes" title="" intro=""/>
2020
</tab>
21-
<!-- <tab type="classes" visible="yes" title="">
21+
<tab type="classes" visible="yes" title="">
2222
<tab type="classlist" visible="yes" title="" intro=""/>
2323
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
2424
<tab type="hierarchy" visible="yes" title="" intro=""/>
2525
<tab type="classmembers" visible="yes" title="" intro=""/>
26-
</tab> -->
26+
</tab>
2727
<tab type="structs" visible="yes" title="">
2828
<tab type="structlist" visible="yes" title="" intro=""/>
2929
<tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>

‎doc/container.dox

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
1-
/**
1+
/** \page GAMS_TRANSFER_MATLAB_CONTAINER Container
22

3-
@defgroup gams_transfer_matlab_container Container
4-
@brief Wrapper of symbols (like GDX file)
3+
\tableofcontents
54

65
A GAMS Transfer Matlab container stores a collection of \ref
7-
gams_transfer_matlab_symbol "symbols" and is therefore comparable to a GDX file.
6+
GAMS_TRANSFER_MATLAB_SYMBOLS "symbols" and is therefore comparable to a GDX file.
87
It is indeed a fundamental feature of containers to read from or write to GDX
98
files. GDX files can be operated in two different modes, `default` and
109
`indexed`, which are also supported by GAMS Transfer Matlab containers, see \ref
@@ -84,7 +83,7 @@ Finally note that GDX files store multiple values per symbol. \ref
8483
gams::transfer::Set "Sets" have `element_text`, \ref gams::transfer::Parameter "Parameters"
8584
have `value` and \ref gams::transfer::Equation "Equations" and \ref
8685
gams::transfer::Variable "Variables" have `level`, `marginal`, `lower`, `upper`,
87-
`scale`, see \ref gams_transfer_matlab_records for more information. On
86+
`scale`, see \ref GAMS_TRANSFER_MATLAB_RECORDS for more information. On
8887
default, all values are read, but you can select a subset by
8988
```
9089
c.read(source, 'values', {'level', 'marginal'});

‎doc/getting_started.dox

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
/** \page GAMS_TRANSFER_MATLAB_GETSTARTED Getting Started
22

3+
\tableofcontents
4+
35
\section GAMS_TRANSFER_MATLAB_GETSTARTED_INSTALL Install
46

57
GAMS comes with a ready-to-use GAMS Transfer Matlab (for Matlab 2018a or newer).
68
Simply add the GAMS Matlab API to the Matlab path:
79
```
8-
addpath("[PathToGAMS]/apifiles/Matlab/api")
10+
addpath("[PathToGAMS]/api/matlab")
911
```
1012

11-
Note that GAMS Transfer Matlab comes as a Matlab package and, thus, all classes
12-
must be prefixed with `gams.transfer.`. In order to avoid this, you can import
13-
the package with:
13+
For other software products, e.g. Octave, you must compile the MEX source code first. Simply run:
1414
```
15-
import gams.transfer.*
15+
gams.transfer.setup()
1616
```
1717

1818
\section GAMS_TRANSFER_MATLAB_GETSTARTED_EXAMPLE Example

‎doc/main.dox

Lines changed: 19 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,26 @@
11
/** \mainpage GAMS Transfer Matlab
22

3-
\section GAMS_TRANSFER_MATLAB_INTRO Introduction
4-
5-
GAMS Transfer is a package to maintain GAMS data outside a GAMS script in a
6-
programming language like Python or Matlab. It allows the user to add GAMS
7-
symbols (Sets, Parameters, Variables and Equations), to manipulate GAMS symbols,
8-
read symbols from a GDX file or write them to one. While keeping those
9-
operations as simple as possible for the user, GAMS Transfer's main focus is the
10-
highly efficient transfer of data between GAMS and the target programming
11-
language. In order to achieve this, symbol records – the actual and potentially
12-
large-scale data sets – are stored in native data structures of the
13-
corresponding programming languages, e.g., dataframes, tables or (sparse)
14-
matrices. The benefits of this approach are threefold:
3+
GAMS Transfer is a package to maintain GAMS data outside a GAMS script. It allows the user to add
4+
GAMS symbols (Sets, Parameters, Variables and Equations), to manipulate GAMS symbols, read symbols
5+
from a GDX file or write them to one. While keeping those operations as simple as possible for the
6+
user, GAMS Transfer Matlab's main focus is the highly efficient transfer of data between GAMS and
7+
Matlab. In order to achieve this, symbol records (the actual and potentially large-scale data sets)
8+
are stored in native data structures of Matlab (tables, structs or (sparse) matrices). The benefits
9+
of this approach are threefold:
1510
- The user is usually very familiar with these data structures.
1611
- These data structures come with a large tool box for various data operations.
17-
- Optimized methods for reading from and writing to GDX can transfer the data as
18-
a bulk –- resulting in the high performance of this package.
19-
20-
\image html overview.jpg
21-
\image latex overview.jpg
22-
23-
\subsection GAMS_TRANSFER_MATLAB_VS Using GAMS Transfer Matlab or ...?
24-
25-
\subsubsection GAMS_TRANSFER_MATLAB_VS_API ...GAMS Matlab API?
26-
27-
[GAMS Matlab API]: https://www.gams.com/latest/docs/API_MATLAB_GAMS_OVERVIEW.html
28-
29-
Both, the [GAMS Matlab API] and GAMS Transfer Matlab allow to exchange data from
30-
Matlab with GAMS. However, GAMS Transfer Matlab focuses on data exchange and for
31-
this is much more efficient. Moreover, it offers a richer set of features to
32-
read and write GDX files. On the contrary, the [GAMS Matlab API] can manage GAMS
33-
jobs which GAMS Transfer Matlab cannot do. In summary, if you are only using the
34-
[GAMS Matlab API] for data exchange, consider using GAMS Transfer Matlab
35-
instead.
36-
37-
\subsubsection GAMS_TRANSFER_MATLAB_VS_GDXMRW ...GDXMRW?
38-
39-
[GDXMRW]: https://www.gams.com/latest/docs/T_GDXMRW.html
40-
41-
[GDXMRW] has been [deprecated since GAMS
42-
38](https://www.gams.com/latest/docs/RN_38.html#g3810_GDXMRW) and may be removed
43-
in a future GAMS release. Please migrate to GAMS Transfer Matlab instead. While
44-
the purpose of these two is similar, GAMS Transfer Matlab offers more features,
45-
a more user-friendly interface and is actively maintained.
46-
47-
\subsection GAMS_TRANSFER_MATLAB_USE_DOC Using the GAMS Transfer Matlab Documentation
48-
49-
If you are new to GAMS Transfer Matlab, have a look at \ref
50-
GAMS_TRANSFER_MATLAB_GETSTARTED. This section explains how to install GAMS
51-
Transfer Matlab and shows a first exmaple that covers the most important
52-
operations. It's a good starting point to discover GAMS Transfer Matlab. For
53-
more details, refer to the manual for: (1) \ref gams_transfer_matlab_container,
54-
(2) \ref gams_transfer_matlab_symbol and (3) \ref gams_transfer_matlab_records.
55-
Good advice: Read the documentation in this order as it will guide you from more
56-
general topics like \ref gams::transfer::Container "Container" to more detailed
57-
topics like \ref GAMS_TRANSFER_MATLAB_RECORDS_FORMAT. Note that at the bottom of
58-
each of the three, you can find a list of GAMS Transfer Matlab classes that
59-
belong to the corresponding topic. Those class documentations document each
60-
method and property of the classes and give a good overview of what the class is
61-
capable of. Finally, once installed, it is also possible to get help from within
62-
Matlab. Simply run:
12+
- Optimized methods for reading from and writing to GDX can transfer the data as a bulk –- resulting
13+
in the high performance of this package.
14+
15+
If you are new to GAMS Transfer Matlab, have a look at \ref GAMS_TRANSFER_MATLAB_GETSTARTED. It
16+
explains how to install GAMS Transfer Matlab and shows a first exmaple that covers the most
17+
important operations. It's a good starting point to discover GAMS Transfer Matlab. For more details,
18+
refer to the manual for: (1) \ref GAMS_TRANSFER_MATLAB_CONTAINER, (2) \ref
19+
GAMS_TRANSFER_MATLAB_SYMBOLS and (3) \ref GAMS_TRANSFER_MATLAB_RECORDS. Good advice: Read the
20+
documentation in this order as it will guide you from more general topics like \ref
21+
gams::transfer::Container "Container" to more detailed topics like \ref
22+
GAMS_TRANSFER_MATLAB_RECORDS_FORMAT. Furthermore, it is also possible to get help from within
23+
Matlab:
6324
```
6425
help GAMSTransfer
6526
```

‎doc/records.dox

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,22 @@
1-
/**
1+
/** \page GAMS_TRANSFER_MATLAB_RECORDS Records
22

3-
@defgroup gams_transfer_matlab_records Records
4-
@brief Symbol Records
3+
\tableofcontents
54

65
Symbol records are the actual data. In GAMS Transfer Matlab they are stored in
76
Matlab native data structures, structs, tables, dense or sparse matrices (see
87
\ref GAMS_TRANSFER_MATLAB_RECORDS_FORMAT for more information). In GDX, a record
98
is the combination of domain entry data and value data. Domain entries are given
109
as \ref GAMS_TRANSFER_MATLAB_RECORDS_UELS "UELs" using Matlab `categorical`. Work
1110
with `categorical` as you would work with strings -- it's just a way to save
12-
memory. The values a \ref gams_transfer_matlab_symbol "symbol" stores per record
11+
memory. The values a \ref GAMS_TRANSFER_MATLAB_SYMBOLS "symbol" stores per record
1312
depends on the \ref gams::transfer::SymbolType "symbol type". \ref
1413
gams::transfer::Set "Sets" have `element_text`, \ref gams::transfer::Parameter "Parameters"
1514
have `value` and \ref gams::transfer::Equation "Equations" and \ref
1615
gams::transfer::Variable "Variables" have `level`, `marginal`, `lower`, `upper` and
1716
`scale`. If some of these value fields are not provided, then default values are
1817
used. A \ref GAMS_TRANSFER_MATLAB_RECORDS_FORMAT "record format" is chosen for
1918
each symbol and not for each of these values independently. Hence note, a \ref
20-
gams_transfer_matlab_container "container" can store different symbols with
19+
GAMS_TRANSFER_MATLAB_CONTAINER "container" can store different symbols with
2120
different \ref GAMS_TRANSFER_MATLAB_RECORDS_FORMAT "record formats".
2221

2322
When working with symbol records, there are two things that can go wrong:

‎doc/symbols.dox

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
1-
/**
1+
/** \page GAMS_TRANSFER_MATLAB_SYMBOLS Symbols
22

3-
@defgroup gams_transfer_matlab_symbol Symbols
4-
@brief Symbols (Set, Alias, Parameter, Variable, Equation)
3+
\tableofcontents
54

65
A symbol is either a GAMS \ref gams::transfer::Set "Set", \ref gams::transfer::Alias
76
"Alias", \ref gams::transfer::Parameter "Parameter", \ref gams::transfer::Variable
87
"Variable" or \ref gams::transfer::Equation "Equation". In GAMS Transfer Matlab, a
98
symbol cannot live on it's own, but is always part of a \ref
10-
gams_transfer_matlab_container "container".
9+
GAMS_TRANSFER_MATLAB_CONTAINER "container".
1110

1211
\section GAMS_TRANSFER_MATLAB_SYMBOL_DOMAIN Symbol Domain
1312

@@ -124,7 +123,7 @@ apply, see also \ref GAMS_TRANSFER_MATLAB_RECORDS_DOMVIOL.
124123
Need more convenience by sacrificing efficiency? Go to \ref
125124
GAMS_TRANSFER_MATLAB_SYMBOL_CONVENIENT_RECORDS.
126125

127-
Symbol \ref gams_transfer_matlab_records "records" are stored in the property
126+
Symbol \ref GAMS_TRANSFER_MATLAB_RECORDS "records" are stored in the property
128127
\ref gams::transfer::Symbol::records "Symbol.records". It is most efficient to
129128
modify the data inplace. Note that the records have to satisfy the chosen \ref
130129
GAMS_TRANSFER_MATLAB_RECORDS_FORMAT "records format". Otherwise, the symbol will

‎gams_transfer_doc.sh

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
mkdir -p build
44

55
(cat doc/Doxyfile && \
6-
echo "PROJECT_NUMBER=0.7.0"; \
6+
echo "PROJECT_NUMBER=0.8.0"; \
77
echo "INPUT=+gams doc/main.dox doc/getting_started.dox doc/container.dox doc/symbols.dox doc/records.dox"; \
88
echo "OUTPUT_DIRECTORY=build/doc"; \
99
echo "FILTER_PATTERNS=*m=ext/doxymatlab/m2cpp.pl"; \

0 commit comments

Comments
 (0)
Please sign in to comment.