1 /* -*- c-basic-offset: 4; indent-tabs-mode: nil -*- */
2 /* ====================================================================
3 * Copyright (c) 1999-2004 Carnegie Mellon University. All rights
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
13 * 2. Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in
15 * the documentation and/or other materials provided with the
19 * THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND
20 * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
21 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY
23 * NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 * ====================================================================
36 * fsg_model.h -- Word-level finite state graph
38 * **********************************************
39 * CMU ARPA Speech Project
41 * Copyright (c) 2003 Carnegie Mellon University.
42 * ALL RIGHTS RESERVED.
43 * **********************************************
47 #ifndef __FSG_MODEL_H__
48 #define __FSG_MODEL_H__
54 /* SphinxBase headers. */
55 #include <sphinxbase/prim_type.h>
56 #include <sphinxbase/glist.h>
57 #include <sphinxbase/logmath.h>
58 #include <sphinxbase/bitvec.h>
59 #include <sphinxbase/hash_table.h>
60 #include <sphinxbase/listelem_alloc.h>
61 #include <sphinxbase/sphinxbase_export.h>
64 * A single transition in the FSG.
66 typedef struct fsg_link_s {
69 int32 logs2prob; /**< log(transition probability)*lw */
70 int32 wid; /**< Word-ID; <0 if epsilon or null transition */
74 #define fsg_link_from_state(l) ((l)->from_state)
75 #define fsg_link_to_state(l) ((l)->to_state)
76 #define fsg_link_wid(l) ((l)->wid)
77 #define fsg_link_logs2prob(l) ((l)->logs2prob)
80 * Adjacency list (opaque) for a state in an FSG.
82 typedef struct trans_list_s trans_list_t;
85 * Word level FSG definition.
86 * States are simply integers 0..n_state-1.
87 * A transition emits a word and has a given probability of being taken.
88 * There can also be null or epsilon transitions, with no associated emitted
91 typedef struct fsg_model_s {
92 int refcount; /**< Reference count. */
93 char *name; /**< A unique string identifier for this FSG */
94 int32 n_word; /**< Number of unique words in this FSG */
95 int32 n_word_alloc; /**< Number of words allocated in vocab */
96 char **vocab; /**< Vocabulary for this FSG. */
97 bitvec_t *silwords; /**< Indicates which words are silence/fillers. */
98 bitvec_t *altwords; /**< Indicates which words are pronunciation alternates. */
99 logmath_t *lmath; /**< Pointer to log math computation object. */
100 int32 n_state; /**< number of states in FSG */
101 int32 start_state; /**< Must be in the range [0..n_state-1] */
102 int32 final_state; /**< Must be in the range [0..n_state-1] */
103 float32 lw; /**< Language weight that's been applied to transition
105 trans_list_t *trans; /**< Transitions out of each state, if any. */
106 listelem_alloc_t *link_alloc; /**< Allocator for FSG links. */
110 #define fsg_model_name(f) ((f)->name)
111 #define fsg_model_n_state(f) ((f)->n_state)
112 #define fsg_model_start_state(f) ((f)->start_state)
113 #define fsg_model_final_state(f) ((f)->final_state)
114 #define fsg_model_log(f,p) logmath_log((f)->lmath, p)
115 #define fsg_model_lw(f) ((f)->lw)
116 #define fsg_model_n_word(f) ((f)->n_word)
117 #define fsg_model_word_str(f,wid) (wid == -1 ? "(NULL)" : (f)->vocab[wid])
120 * Iterator over arcs.
122 typedef struct fsg_arciter_s fsg_arciter_t;
125 * Have silence transitions been added?
127 #define fsg_model_has_sil(f) ((f)->silwords != NULL)
130 * Have alternate word transitions been added?
132 #define fsg_model_has_alt(f) ((f)->altwords != NULL)
134 #define fsg_model_is_filler(f,wid) \
135 (fsg_model_has_sil(f) ? bitvec_is_set((f)->silwords, wid) : FALSE)
136 #define fsg_model_is_alt(f,wid) \
137 (fsg_model_has_alt(f) ? bitvec_is_set((f)->altwords, wid) : FALSE)
143 fsg_model_t *fsg_model_init(char const *name, logmath_t *lmath,
144 float32 lw, int32 n_state);
147 * Read a word FSG from the given file and return a pointer to the structure
148 * created. Return NULL if any error occurred.
153 * Any number of comment lines; ignored
154 * FSG_BEGIN [<fsgname>]
158 * T <from-state> <to-state> <prob> [<word-string>]
160 * ... (any number of state transitions)
162 * Any number of comment lines; ignored
165 * The FSG spec begins with the line containing the keyword FSG_BEGIN.
166 * It has an optional fsg name string. If not present, the FSG has the empty
167 * string as its name.
169 * Following the FSG_BEGIN declaration is the number of states, the start
170 * state, and the final state, each on a separate line. States are numbered
171 * in the range [0 .. <numberofstate>-1].
173 * These are followed by all the state transitions, each on a separate line,
174 * and terminated by the FSG_END line. A state transition has the given
175 * probability of being taken, and emits the given word. The word emission
176 * is optional; if word-string omitted, it is an epsilon or null transition.
178 * Comments can also be embedded within the FSG body proper (i.e. between
179 * FSG_BEGIN and FSG_END): any line with a # character in col 1 is treated
182 * Return value: a new fsg_model_t structure if the file is successfully
183 * read, NULL otherwise.
186 fsg_model_t *fsg_model_readfile(const char *file, logmath_t *lmath, float32 lw);
189 * Like fsg_model_readfile(), but from an already open stream.
192 fsg_model_t *fsg_model_read(FILE *fp, logmath_t *lmath, float32 lw);
195 * Retain ownership of an FSG.
197 * @return Pointer to retained FSG.
200 fsg_model_t *fsg_model_retain(fsg_model_t *fsg);
203 * Free the given word FSG.
205 * @return new reference count (0 if freed completely)
208 int fsg_model_free(fsg_model_t *fsg);
211 * Add a word to the FSG vocabulary.
213 * @return Word ID for this new word.
216 int fsg_model_word_add(fsg_model_t *fsg, char const *word);
219 * Look up a word in the FSG vocabulary.
221 * @return Word ID for this word
224 int fsg_model_word_id(fsg_model_t *fsg, char const *word);
227 * Add the given transition to the FSG transition matrix.
229 * Duplicates (i.e., two transitions between the same states, with the
230 * same word label) are flagged and only the highest prob retained.
233 void fsg_model_trans_add(fsg_model_t * fsg,
234 int32 from, int32 to, int32 logp, int32 wid);
237 * Add a null transition between the given states.
239 * There can be at most one null transition between the given states;
240 * duplicates are flagged and only the best prob retained. Transition
241 * probs must be <= 1 (i.e., logprob <= 0).
243 * @return 1 if a new transition was added, 0 if the prob of an existing
244 * transition was upgraded; -1 if nothing was changed.
247 int32 fsg_model_null_trans_add(fsg_model_t * fsg, int32 from, int32 to, int32 logp);
250 * Add a "tag" transition between the given states.
252 * A "tag" transition is a null transition with a non-null word ID,
253 * which corresponds to a semantic tag or other symbol to be output
254 * when this transition is taken.
256 * As above, there can be at most one null or tag transition between
257 * the given states; duplicates are flagged and only the best prob
258 * retained. Transition probs must be <= 1 (i.e., logprob <= 0).
260 * @return 1 if a new transition was added, 0 if the prob of an existing
261 * transition was upgraded; -1 if nothing was changed.
264 int32 fsg_model_tag_trans_add(fsg_model_t * fsg, int32 from, int32 to,
265 int32 logp, int32 wid);
268 * Obtain transitive closure of null transitions in the given FSG.
270 * @param nulls List of null transitions, or NULL to find them automatically.
271 * @return Updated list of null transitions.
274 glist_t fsg_model_null_trans_closure(fsg_model_t * fsg, glist_t nulls);
277 * Get the list of transitions (if any) from state i to j.
280 glist_t fsg_model_trans(fsg_model_t *fsg, int32 i, int32 j);
283 * Get an iterator over the outgoing transitions from state i.
286 fsg_arciter_t *fsg_model_arcs(fsg_model_t *fsg, int32 i);
289 * Get the current arc from the arc iterator.
292 fsg_link_t *fsg_arciter_get(fsg_arciter_t *itor);
295 * Move the arc iterator forward.
298 fsg_arciter_t *fsg_arciter_next(fsg_arciter_t *itor);
301 * Free the arc iterator (early termination)
304 void fsg_arciter_free(fsg_arciter_t *itor);
306 * Get the null transition (if any) from state i to j.
309 fsg_link_t *fsg_model_null_trans(fsg_model_t *fsg, int32 i, int32 j);
312 * Add silence word transitions to each state in given FSG.
314 * @param state state to add a self-loop to, or -1 for all states.
315 * @param silprob probability of silence transition.
318 int fsg_model_add_silence(fsg_model_t * fsg, char const *silword,
319 int state, float32 silprob);
322 * Add alternate pronunciation transitions for a word in given FSG.
325 int fsg_model_add_alt(fsg_model_t * fsg, char const *baseword,
326 char const *altword);
329 * Write FSG to a file.
332 void fsg_model_write(fsg_model_t *fsg, FILE *fp);
335 * Write FSG to a file.
338 void fsg_model_writefile(fsg_model_t *fsg, char const *file);
341 * Write FSG to a file in AT&T FSM format.
344 void fsg_model_write_fsm(fsg_model_t *fsg, FILE *fp);
347 * Write FSG to a file in AT&T FSM format.
350 void fsg_model_writefile_fsm(fsg_model_t *fsg, char const *file);
353 * Write FSG symbol table to a file (for AT&T FSM)
356 void fsg_model_write_symtab(fsg_model_t *fsg, FILE *file);
359 * Write FSG symbol table to a file (for AT&T FSM)
362 void fsg_model_writefile_symtab(fsg_model_t *fsg, char const *file);
364 #endif /* __FSG_MODEL_H__ */